Add parallel sleep staging annotations example

[viranovskaya]

• BIDS Specification PR: NONE
• BIDS Validator PR: NONE
• Related discussion: BIDS Extension for Sleep Data and Annotations bids-specification#2138
• TODOs:
  • Validate the example with the current BIDS validator

This adds a small synthetic EEG example with manual and automated sleep staging in the same events.tsv file.

Each annotation is one row. Manual and automated labels can therefore overlap, use different channel sets, or leave different intervals unscored. The HED sidecar keeps overlapping annotations in separate groups. Rows with the same onset are assembled into one event-level annotation, while the manual and automated labels remain distinguishable as separate groups.

The example also keeps the original stage label, scoring standard, annotation method, annotator ID and optional confidence. It includes a few disagreements, R&K S3/S4 mapped to N3, movement and an unscored interval.

Checked with:

bids-validator eeg_sleep_staging --config default-config.json --ignoreWarnings

[VisLab]

HED short form should be used. Tools translate using the HED schema.

[viranovskaya]

Thanks, I see what you mean. score_2.1.0 is partnered with HED 8.4.0, so I’ve switched the dataset to use the library schema directly and removed the sc: prefixes, matching the existing xeeg_hed_score example. Both BIDS and HEDTools validation pass. Am I still missing anything?

[VisLab]

This is very close. Most importantly, the HED annotations file: sub-01_task-sleep_acq-psg_events.json should not be in the sub directory. Instead it should be renamed task-sleep_events.json and moved to the top level of the dataset (at the same level as dataset_description.json).

As with most datasets, the JSON sidecar is quite generic and applies equally to every events.tsv file in the dataset. Some datasets have different tasks in the same low level directories. You can have multiple of these JSON files at the top level, one for each task.

On annotator_id, I would use the tag ID instead of Label. The Label tag can only take values that are in the name class (contain only letters, numbers, or dash), while the ID can take on virtually any printable character.

[viranovskaya]

Thanks, fixed both points. I moved the HED sidecar to eeg_sleep_staging/task-sleep_events.json so it applies at the dataset level, and changed the annotator_id HED value to ID/#. The local BIDS validator now passes.