EEG Annotation Recording Start Offset Tool

Description

Explicit clock-offset corrected annotation index with nearest-sample, half-toward-positive-infinity rounding.

Neurophysiological research records use sample coordinates, event clocks, epoch boundaries, references, signal amplitudes, and spectral bins. Timing conversions and support shares depend on rate, origin, exclusion, and boundary policies. Arithmetic on supplied values is separate from signal detection, validated acquisition, or neurological interpretation.

Explicit clock-offset corrected annotation index with nearest-sample, half-toward-positive-infinity rounding.

When to use this tool

Use EEG Annotation Recording Start Offset when you need this research signal, sample, event, epoch, reference, or spectral component from supplied data.

How to use the tool and how it works

Enter annotationSeconds, recordingStartSeconds, clockOffsetSeconds, sampleHz. Use the units and conventions below.
Run the tool. Correct any format, range, or cross-field input error before interpreting the output.
Read relativeSeconds, nearestSample, sampleErrorSeconds. Use the output convention below.

For positive sampleHz return relativeSeconds=annotationSeconds-recordingStartSeconds-clockOffsetSeconds, nearestSample=Math.round(relativeSeconds*sampleHz), and sampleErrorSeconds=nearestSample/sampleHz-relativeSeconds.^[1]

Input field	Meaning and units	Accepted input
annotationSeconds	Annotation Seconds	Required. Finite number.
recordingStartSeconds	Recording Start Seconds	Required. Finite number.
clockOffsetSeconds	Clock Offset Seconds	Required. Finite number.
sampleHz	Positive samples per second.	Required. Finite number; strictly above 0.

Output field	Interpretation	Returned shape
relativeSeconds	Relative Seconds	Required. Finite number.
nearestSample	Nearest Sample	Required. Safe integer.
sampleErrorSeconds	Rounded sample time minus supplied corrected annotation time.	Required. Finite number.

json

{
  "input": {
    "annotationSeconds": 12,
    "recordingStartSeconds": 10,
    "clockOffsetSeconds": 0.1,
    "sampleHz": 100
  },
  "output": {
    "relativeSeconds": 1.9,
    "nearestSample": 190,
    "sampleErrorSeconds": 0
  }
}

Limitations and assumptions

Times use seconds and the offset is supplied. Negative samples are allowed and half ties round toward positive infinity; no annotation is authenticated, signal resampled, clock synchronized, or clinical event detected.
Inputs must satisfy both the field types and the cross-field conditions above. Invalid input causes an error; a successful false flag or documented placeholder is a different result.
Numeric calculations use binary floating point unless exact decimal-integer arithmetic is explicitly stated. No hidden measurement tolerance or decimal rounding is added; nonfinite or out-of-contract results are rejected. Numeric signed-zero results are exported as zero.

Alternative or Complementary methods

Use calibrated acquisition and the intended signal-analysis protocol for a complete assessment. Verify sample rate, coordinate origin, clock offsets, reference configuration, filtering assumptions, and observation support.

References

Calculation and input contract: neurology/eeg-annotation-recording-start-offset — tool.io

Similar or alternative tools

EEG Sample Event Offset
Map one supplied EEG event sample relative to an explicit sample origin/rate and sample-rounding convention.
EEG Filter Delay Sample Shift
Explicit supplied filter group-delay shift, preserving fractional sample positions rather than silently rounding event timing.