Week 9: Neuroinformatics -- Standards, Sharing, and Credit¶

Overview¶

A finished analysis is not a finished contribution. The data behind it has to be reproducible, shareable, and citable, or the work dies with the paper. Two standards carry the weight: the Brain Imaging Data Structure (BIDS) answers where everything lives (structure), and Hierarchical Event Descriptors (HED) answer what every event meant (semantics). The single most useful idea this week: the bar for a complete annotation is concrete and falsifiable. A language model should be able to reconstruct the stimulus, or the experiment, from the annotation alone. That is not a metaphor; it is exactly the test demonstrated in the Healthy Brain Network EEG (HBN-EEG) paper (Shirazi et al., 2024, Figure 9), where Claude Sonnet 3.5 regenerated the Surround Suppression stimulus from its HED description with no image.

The dataset throughout is HBN-EEG, the very data the course has analyzed since Week 3. It is itself a BIDS + HED dataset published on both OpenNeuro and NEMAR with exactly the tools this session teaches: the loop closes, the data you analyzed is the worked example for how to share data.

Slides¶

Use arrow keys to navigate. Press F for fullscreen, ? for shortcuts.

Guide¶

The rest of this page walks through the workflow in the order the live session follows.

1. The Reuse-and-Credit Gap¶

A lab collects dense, synchronized data. What reaches re-users is a thin events.tsv with one cryptic column and a results figure locked in a folder. Three locks snap shut at once.

• Structure -- where is everything? Custom layouts mean every re-user writes glue code first.
• Semantics -- what did the events mean? A numeric event code is meaningless outside the lab.
• Credit -- who is cited when it is reused? Without a DOI and author identifiers, reuse traces back to no one.

2. Two Standards, One Bar¶

BIDS answers where; HED answers what. The bar that judges both is the same: someone, or a language model, can reconstruct your experiment without emailing you.

• BIDS (Brain Imaging Data Structure) -- a filesystem convention plus metadata. Structure.
• HED (Hierarchical Event Descriptors) -- a controlled, composable, validatable event vocabulary. Semantics.

3. BIDS: One Layout, Every Dataset¶

A filesystem convention plus metadata: predictable names (sub-, ses-, task-), JSON sidecars, and TSV tables.

A BIDS dataset is readable by EEGLAB, MNE-Python, the BIDS validator, and BIDS Apps, and it is the upload format both OpenNeuro and NEMAR expect. Standard structure is also what makes mega-analysis across studies possible. The payoff is leverage, not bureaucracy.

4. Where Structure Ends¶

The JSON sidecar carries acquisition metadata; events.tsv carries the timeline.

{
  "TaskName": "surroundSupp",
  "SamplingFrequency": 500,
  "EEGReference": "Cz",
  "PowerLineFrequency": 60,
  "EEGChannelCount": 128
}

onset    duration   value
0.000    n/a        12
1.500    n/a        14
3.000    n/a        12

Structure tells you where an event sits on the timeline. It cannot tell you what the event was. That gap is semantics.

5. HED: the Semantics Standard¶

events.tsv is thin: an onset and a cryptic numeric code. Stimulus, modality, condition, response, context -- all real, all recorded, none of it in the shared file. (HBN originally shipped numeric codes; the first curation step replaced them with meaningful strings, then annotated with HED.)

One HED tag is a comma-separated path through a controlled schema; the hierarchy carries meaning, so analysis works at any level:

Action, Move, Move-body-part, Move-upper-extremity, Press

You can analyze at the leaf (Press) or any ancestor (Move). The sidecar pattern keeps events.tsv unchanged; all semantics live in events.json under HED keys.

6. The Bar: Recreate the Stimulus¶

In the HBN-EEG paper, the HED annotation of the Surround Suppression task was handed to Claude Sonnet 3.5 with no image, and the model regenerated the visual stimulus from the annotation alone.

Everything structural came back correct: the gratings, the vertical-grating background, central fixation, the contrast relationship, four disks present. The only miss was the disks' size and position -- both awkward to express in HED, so they were left out, and the model had no way to reproduce them.

Cite: Shirazi et al. (2024), HBN-EEG: The FAIR implementation of the Healthy Brain Network EEG dataset, bioRxiv 10.1101/2024.10.03.615261.

7. HEDit: AI-assisted HED¶

HED workflows stall for most labs, and it is a workflow problem, not a willingness problem: roughly 2000 tags, expert-only fluency, a validator with cryptic messages.

HEDit turns the wall into a paragraph. You write one rich prose description per event value; a Parser to Tagger to Validator pipeline (LangGraph, with the official HED validator in the loop) returns a BIDS-compliant events.json with HED plus a provenance trail. The schema is the contract; no agent invents vocabulary. And HEDit is only as good as the description: it is tuned for exactly the detail the recreate-the-stimulus bar demands.

8. The neuroinformatics Plugin: 2 Skills + 1 Agent¶

• /neuroinformatics:bids-conversion -- a guided conversion to BIDS.
• bids-validator (agent) -- autonomous validation and fixes. This week's mechanical defence.
• /neuroinformatics:experiment-design -- the data-collection side (PsychoPy + Lab Streaming Layer); in the plugin, not today's focus.

A guided six-step conversion ends where the next act begins, validation:

1. Inventory  ->  2. Scaffold  ->  3. Convert files  ->  4. JSON sidecars  ->  5. TSV tables  ->  6. Validate

Modalities: EEG, EMG, MEG, fMRI, and behavioral data.

9. The bids-validator Agent: the Mechanical Defence¶

The agent runs the BIDS validator, categorizes findings, applies fixes with confirmation, re-validates, and reports readiness.

## BIDS Validation Report
Subjects: 12   Modalities: eeg
Errors fixed: 2
  [FIXED] missing dataset_description.json
  [FIXED] _eeg.json missing PowerLineFrequency -> 60
Remaining warnings: 2
Ready for submission: YES

10. Sharing: OpenNeuro and NEMAR¶

OpenNeuro is the de-facto open BIDS archive: validated on ingest, public, DOI-minted.

NEMAR specializes in EEG/MEG BIDS datasets and sits next to San Diego Supercomputer Center compute, so you can analyze without downloading. HBN-EEG lives on both.

11. nemar-cli: Validation, Upload, Publish¶

Validation is one command, and also runs automatically on upload and on every update pull request:

nemar dataset validate ./my-dataset

The full path, and the collaboration model:

nemar auth login                          # one-time, API key cached
nemar dataset validate ./my-dataset       # BIDS check, must pass
nemar dataset upload ./my-dataset         # creates a private GitHub repo
nemar dataset publish request nm000XXX    # admin approves -> public + DOI

upload creates a private GitHub repository where you are the admin: invite collaborators and push directly while you stage. After publishing, changes go through pull requests and version tags. (OpenNeuro also supports private upload, just command-line only, so the NEMAR advantage is this collaboration model plus the rich DOI metadata, not "private vs public.")

12. DOI Minting + ORCID Auto-link¶

On publish, nemar-cli mints a concept DOI (one stable citation across all versions) plus per-version DOIs, via EZID writing DataCite kernel-4 metadata (the DOIs carry the 10.82901/NEMAR.<id> prefix), and auto-links every author's ORCID iD. The dataset then appears on each author's ORCID record automatically. OpenNeuro does not link authors to ORCID on the DOI yet.

13. The Metadata Gap: Proof on a Real Dataset¶

Live DataCite data, the same HBN-EEG Release 1, the same eight authors, two homes.

14. Live Walkthrough¶

Two small, honest actions, about four minutes total:

1. HEDit -- write one rich prose description of an HBN event and watch it become a validated HED string.
2. nemar dataset validate -- run it on the HBN practicum dataset and read the clean BIDS report.

15. Before Next Week¶

• Install research-skills; it bundles neuroinformatics, figures, manuscript, opencite, grant, project, and presentation.
• If you have a small EEG/EMG dataset, try /neuroinformatics:bids-conversion and run the bids-validator agent.
• Browse HBN-EEG on NEMAR and OpenNeuro; compare the two DOI records on DataCite Commons.
• Optional: try HEDit on one event from your own experiment, written as a rich paragraph.

Week 10 is the capstone: building your own plugin.

Resources¶

Course materials

• Week 9 session
• Week 9 blog (markdown source)
• Course repository
• research-skills plugin (bundles neuroinformatics, figures, manuscript, opencite, grant, project, presentation)

Standards and tools

• BIDS specification (Brain Imaging Data Structure)
• HED (Hierarchical Event Descriptors)
• HEDit (natural language to validated HED)
• nemar-cli (upload, validate, version, and publish to NEMAR)
• OpenNeuro and NEMAR (open BIDS archives)
• DataCite Commons (inspect DOI metadata)
• ORCID (researcher and contributor identifiers)

Reference

• Shirazi et al. (2024), HBN-EEG: The FAIR implementation of the Healthy Brain Network EEG dataset, bioRxiv 10.1101/2024.10.03.615261
• Open Science Collective Discord