Wiki

Wiki: Basics of event synchronization and observation logs

Comparisons break down if we don't leave behind the source of the label, not just the signal.

Mind Uploading Research Project

Public Page Updated: 2026-03-28 Practical guide

How to use this page

Read this first to avoid getting lost

This page is a wiki that explains why raw EEG waveforms alone are not reproducible in research from the perspectives of event markers, event semantics, time synchronization, manual scoring, and report-derived labels. The purpose is to prevent not only ``waveform files are available but cannot be compared,'' but also ``labels are available but provenance is ambiguous and cannot be compared,'' and ``time is available but clock domain is ambiguous and cannot be compared.''

  • Raw EEG alone may not tell you the signal at the moment of what happened.
  • Event markers, stimulation logs, and synchronization information may not be restored later.
  • BIDS's `events.tsv` is a timestamp table, not event semantics by itself.
  • LSL strengthens intra-LAN synchronization, but does not automatically provide the true value of intra-device delay or stimulus presentation delay.
  • Stored-data anchors, stream alignment, digital trigger capture, physical output onset, and uncontrolled-response timing are different timing-validation classes.
  • Cue onset, expert interval, hypnogram, and report-derived label are different even though they are the same labeled data.
  • Recording bad channels and bad segments is also part of the evidence.
Helpful next pages
Introduction to EEG Data & Bench Hands-on
Best for
People who have started working with EEG data and want to experience the bare minimum of BIDS and QC
Reading time
12-18 minutes
Accuracy note
What we are dealing with here is the minimum observation log and label provenance, but in the 2026-03-28 update, we also clarify the differences in the roles of BIDS event tables, HED semantics, LSL synchronization, physical timing validation, and Motion-BIDS-type metadata. Although each issue requires additional metadata, the principle of keeping events, meanings, clock systems, and timing-validation classes separate remains the same.

Relatively clear at this stage

What we know now

  • Waveform files alone may not be sufficient to reconstruct task and stimulus responses.
  • If you don't record delays, jitter, and drift, your strengths in temporal resolution will be undermined.
  • BIDS/EEG-BIDS provides a container for events and metadata, but machine-readable semantics like HED are useful for cross-study reuse.
  • Even with LSL and trigger lines, time fidelity cannot be audited without specifying the clock domain and device-side delay.
  • A BIDS onset or sample index does not by itself prove physical display/audio onset, and a digital trigger does not by itself prove uncontrolled response timing.
  • If you do not write annotation provenance, you may not be able to reuse the same label name.
  • Recording bad channels/bad segments is directly linked to transparency of exclusions.

Still unresolved beyond this point

What we still do not know

  • We are still in the process of operational design as to how detailed metadata will be required for all assignments.
  • How to unify the minimum synchronization log in complex multimodal simultaneous measurements is a future issue.
  • We still need to adjust how far event semantics should be made mandatory in HED / ontology / scorer rules.
  • The site-wide schema for how far report-derived labels should be separated from signal-only benchmarks is still being finalized.

Learn the basics

Check the basics in the wiki

What the wiki is for

The wiki is a learning aid. For the project's official current synthesis, success criteria, and operating rules, always return to the public pages.

The shortest answer

Raw EEG is a sequence of electrical signals. However, what we often want to know in research is ``When and what signals occur''. Without that correspondence table, the meaning will be ambiguous even if you look at it later.

Assumptions added in 2026-03 literature audit

This page treats not only event logs but also label provenance as observation logs. In other words, even if the same "correct label" is used, it will not be a comparable benchmark unless it is written whether it is an annotation channel, an expert's interval annotation, a whole-night hypnogram, or a label derived from a doctor's report.

Main weakness this page needed to fix

Although the site already stated that events and synchronization matter, it still did not cleanly separate time anchors, event semantics, and clock alignment. BIDS task events provide a descriptive framework through events.tsv and JSON sidecars, but as Robbins et al. (2021) and Hermes et al. (2025) show, cross-study reuse also requires machine-readable semantics such as HED. Furthermore, as Kothe et al. (2025) show, LSL can strengthen network synchronization without automatically giving you device-internal delay or stimulus-presentation delay. That is why this site audits event fidelity in three tiers rather than treating it as a single checkbox.

2026-03-28 re-audit: timing evidence still needed a ladder

The remaining weakness was that this page could still let a reader treat BIDS onset/sample fields, LSL alignment, TTL markers, photodiode traces, and microphone / loopback tests as if they were interchangeable proofs of timing. The current standards and primary literature do not support that compression. The BIDS specification defines onset relative to the first stored data point, not the physical onset at the screen or speaker. Hermes et al. (2025) shows that HED sharpens machine-actionable semantics, not hardware latency truth. Kothe et al. (2025) shows that LSL can compensate cross-device offsets and jitter, but residual setup offsets must still be tested on the actual instruments. Lepauvre et al. (2024) and Bridges et al. (2020) then show that physical stimulus onset and response timing need external validation because software package, operating system, and hardware combinations can materially shift delay and jitter. Therefore, this site now reads timing evidence as a validation ladder rather than one sync checkbox.

Why raw EEG alone is not enough

For example, if we do not know how many times a stimulus appeared during a task, at what timing a button was pressed, or which sections were excluded due to noise, different people will interpret the same waveform differently. In other words, if you look only at the waveform, it may not be clear what you are comparing.

Event markers and stimulus log

Record What is it needed for
Event marker Indicates where stimulus presentation, response, state change, etc. correspond to on the waveform.
Stimulus log It records which stimuli appeared, in what order, and under what conditions.
Reaction log Associate the subject's button presses, answers, failed trials, etc. with the waveform.

Even if there is only an event marker, if the content of the stimulus or the name of the condition is ambiguous, it will be difficult to reanalyze it. Conversely, just having a stimulus log is not enough unless it is linked to EEG time.

Event fidelity is audited in three layers

layer What to fix here Misreading that is likely to occur if missing
1. Time anchor Correspondence with onset/duration, sample index, clock domain, stimulus/response log. ``When the event happened'' becomes ambiguous, and epoching and delayed evaluation break down.
2. Event semantics trial_type, condition name, HED tags, manual scoring rule, report usage flag. Even if the label name is the same, the meaning will be different and cross-study meta/mega analysis will be broken.
3. Synchronization and transport Clock offset, delay, jitter, drift, transport path, presence or absence of resampling/smoothing. If LSL or trigger is just a sub-ms ground truth, it will be easy to misread it.

BIDS task events primarily provide the first layer, HED supplements the second-layer semantics, and LSL supports third-layer network synchronization. Therefore, this site does not treat these as interchangeable tools.

Timing validation is a ladder, not one box

Validation class What it directly fixes What it still does not prove Typical artifact to keep
Stored-data anchor Fixes where an event sits in the saved data file by onset, duration, and optionally sample. Does not prove physical display/audio onset, device throughput delay, or participant response timing. events.tsv, events.json, acquisition start definition, discarded-sample rule.
Stream alignment Fixes cross-device clock offset, drift, and network-jitter handling across synchronized streams. Does not prove the true latency of displays, speakers, amplifiers, or buttons. LSL/XDF log, clock domain, offset / RTT summary, resync policy.
Acquisition-side digital marker capture Fixes when a trigger pulse reached the acquisition system or DAQ input. Does not prove when the stimulus actually became visible/audible or when the participant actually responded. TTL or marker trace, DAQ channel, trigger wiring map, marker-to-stream relation.
Physical output onset Fixes the real-world onset and duration of a visual or auditory event at the actuator. Does not prove subjective perception time, neural processing latency, or response-device timing. Photodiode trace, microphone trace, audio loopback, high-speed-camera or equivalent setup note.
Uncontrolled-response timing Fixes the gap between the logged response timestamp and the actual button / key / actuator response. Does not prove stimulus onset timing or internal cognitive latency. Contact microphone, force sensor, loopback, response-box validation log.

On this site, a submission has to name the highest rung actually tested. Saying “we used BIDS” fixes the stored-data anchor. Saying “we used LSL” fixes stream alignment. Saying “we sent TTL markers” fixes acquisition-side digital capture. Claims about physical stimulus onset or true response timing require an external measurement rung such as photodiode, microphone, or loopback.

Read the origins of labels in four different ways

Label type Representative examples What it directly represents Minimum auxiliary log that should be kept
cue-locked annotation channel EEG Motor Movement/Imagery T0 / T1 / T2 The design timing of the issue cue and motion/imagery onset. Leave run ID, task ID, subject ID, visual cue condition, and epoching rule.
expert interval annotation CHB-MIT seizure onset / offset This is the event section during long-term recording. Leave file order, gap, case-to-subject support, montage changes.
manual hypnogram Sleep-EDF's R&K sleep stage This is the coarse state label of whole-night. Leave scoring manual, scorer ID, night / study conditions, and label mapping.
report-derived / triaged label TUH EEG / TUSZ report keyword search and clinician report Clinical label and triage information attached to session/file. Leave report usage flag, patient / session ID, signal-only or multimodal declaration.

Three things to look for in time synchronization

Term Meaning What is the problem
Delay How many ms is the difference between the actual event and the record? The time of the post-stimulus response is shifted, leading to incorrect interpretation.
Jitter How much does the deviation fluctuate each time? Averaging will blur the peaks and make the response appear weaker.
Drift The clock lag increases over a long period of time. The later the time, the greater the synchronization error becomes.

This section explains the meaning of the observation log. If you want to see how these affect end-to-end stability and safe stopping in L3 closed-loop evaluation, Wiki: Closed-loop, delay, jitter, and safe stopping is a supplementary lesson.

LSL is powerful, but not hardware ground truth

The Lab Streaming Layer (LSL) is extremely useful as a foundation for synchronizing multiple streams within the same LAN and consistently handling clock offsets and stream metadata. Kothe et al. (2025) showed that LSL can achieve millisecond precision with software-based synchronization. However, the same paper also makes clear that the input device's throughput delay and on-device processing delay cannot be estimated or corrected by LSL alone. Therefore, even if LSL is used, display delay, audio delay, and amplifier buffer delay must still be measured separately.

Things you should leave behind even if you are using LSL Reason
timestamp domain If you do not write whether it is based on the presentation PC, acquisition PC, or device clock, the meaning of the time difference will be lost.
device-side delay The internal delays of the amplifier, display, audio output, and microcontroller cannot be determined by software timestamp alone.
drift / resync policy In long-term recording, the alignment error in the second half changes depending on whether or not drift correction is applied.
validation method You need to know which method you used to estimate the delay, such as photodiode, loopback, TTL, or common signal input.

What to log with the 4 starter datasets

The last column is the operational reasoning for this site

The what not to overread column below marks the operational boundary that this site draws from the logging granularity directly described in official dataset documentation and primary literature.

Dataset Current logging Additional details to preserve What not to overread
EEG Motor Movement/Imagery .event and the annotation channel record cue-locked onset with T0 / T1 / T2 tags. Keep subject, run, task block, epoching window, and EOG / EMG audit results. Do not read this cue-locked motor task as spontaneous thought readout.
CHB-MIT The summary and .seizure annotations preserve seizure intervals, case structure, file gaps, and surrogate dates. Keep case-to-subject linkage, gap length, whether recording is continuous, and montage summaries. Do not treat each file as an independent sample or read the dataset as a gap-free monitoring log.
Sleep-EDF The dataset includes an R&K hypnogram, Fpz-Cz / Pz-Oz EEG, and a 1 Hz event marker. Keep the scoring manual, scorer, study arm, night ID, and any mapping rules to AASM labels. Do not claim sub-second sleep-event timing simply because the EEG itself is sampled at 100 Hz.
TUH EEG / TUSZ Depending on the subset, the dataset includes patient / session hierarchy, EDF, clinician reports, and expert seizure annotation. Keep report-usage flags, patient / session splits, and any report-keyword-derived triage. Do not write report-assisted clinical labels as pure EEG signal-only results.

Why leave bad channel / bad segment

It is normal to exclude channels with large noise or sections broken by body movement. However, without that record, another person cannot reproduce the same exclusion later.

What you want to keep as a minimum

  • bad channel:Which channel was marked bad and for what reason?
  • bad segment:Which time segment did you exclude?
  • Threshold:What criteria were used to exclude it?
  • How to fix:Did you interpolate or discard?

Minimum information required for EEG-BIDS

Item Meaning
`events.tsv` Leaves the time and type of stimulus and response.
`events.json` and HED Explain the meaning of trial_type and other columns, and optionally make event semantics machine-readable with HED tags.
`channels.tsv` Leave the status and type of each channel.
JSON metadata Leave the sampling frequency, reference method, measurement conditions, etc.
clock / sync log Clock domain, delay, jitter, drift, synchronization method, and measurement method are recorded in separate logs.
`*_coordsystem.json` and extended schema When using electrodes, motion sensors, or pose streams, leave the coordinate system and measurement arrangement as first-class metadata.
QC / Exclusion Log Leave bad channels, bad segments, noise, and exclusion reasons in external logs and derivatives.

Event Fidelity Card required on this site

As of the 2026-03-28 site rule, dataset cards and runbooks that contain events must include at least the following six items. The point is not to wait until everything is perfect, but to make missing pieces visible and define where claims must stop.

Item Minimum details to include
1. Event anchor Onset / duration / sample, source file, and the clock domain to which the time refers.
2. Event semantics trial_type, condition definitions, HED or an equivalent vocabulary, and whether semantics come from signal-only annotation or manual scoring / reports.
3. Clock domain and stream alignment Name the clock domain, synchronization middleware if any, offset / drift handling, and resynchronization policy.
4. Timing validation class Name whether timing evidence comes from stored-data anchor only, digital marker capture, physical output onset, or uncontrolled-response testing, together with measured delay / jitter summary and the measurement method.
5. Provenance Scorer ID, scoring manual, report-usage flag, and whether the label is signal-only or multimodal.
6. Geometry / multimodal metadata Electrode coordinates, coordinate system, and the frame plus schema of any additional motion, video, or physiology streams.

Information that is difficult to restore later

If you do not record the following information, you will have to guess it later.

  • Exact time of stimulus presentation:Rough order cannot be substituted.
  • Clock domain:If you do not state which clock a timestamp belongs to, you cannot interpret differences across multiple streams.
  • Timing validation class:If you do not say whether a number comes from stored-data anchor, TTL, photodiode, microphone, or loopback, sync evidence becomes impossible to interpret.
  • Actual delay and jitter: Sometimes equipment and software settings are not enough.
  • Device-side delay:Even if you use LSL or trigger, you need to measure the internal delay of the display, audio, and amplifier separately.
  • Reason for exclusion:Even if you look back on it, you won't know why you threw it away.
  • Label provenance:If you do not record whether a label came from manual scoring or a report-derived rule, you cannot compare it safely even when the label name is the same.
  • Event semantics: If there is no meaning of trial_type, condition name, or HED tags, the same name may be different conditions.
  • scoring manual / scorer:Manual hypnograms like Sleep-EDF change their meaning for reuse when they lose their reference and scorer.
  • report usage flag:In TUH-style datasets, you otherwise cannot tell later whether a label depended on reports or came from signal-only processing.
  • Coordinate system and sensor frame: Adding motion and pose but not leaving frame makes multimodal integration non-reusable.
  • On-the-spot operational notes: Electrode troubles and synchronization errors cannot be read from the waveform alone.

References

Where to go back next

Please use Introduction to EEG to return to the role of EEG as a whole, Data & Bench to return to selecting starter data, and Hands-on to return to the minimal loop procedure.