Neurophysiology Metadata Workflow

Code and analysis supporting the manuscript on multi-standard metadata interoperability for BIDS, NWB, and openMINDS.

Repository Structure

analysis/          Gap analysis tables (coverage, conflicts)
data/
  cedar/           CEDAR template and instances (Layer 2-3)
  odml/            odML schema and validated instances (Layer 1, 4)
converters/        Conversion pipeline code
scripts/           CEDAR API utility scripts
standards/         Pinned standard specifications (submodules)

Five-Layer Architecture

Layer 1: odML Template     ->  data/odml/templates/    (schema definition)
Layer 2: CEDAR Template    ->  data/cedar/templates/   (UI implementation)
Layer 3: CEDAR Instance    ->  data/cedar/instances/   (raw user input)
Layer 4: odML Instance     ->  data/odml/instances/    (validated, source of truth)
Layer 5: Standard Outputs  ->  (generated by converters/)

Converters read exclusively from Layer 4. See converters/README.md for details.

Conversion Scripts

# Generate odML template from mapping (Layer 2 -> Layer 1)
python converters/generate_odml_template.py

# Convert CEDAR instances to odML (Layer 3 -> Layer 4)
python converters/cedar_to_odml.py --all
python converters/cedar_to_odml.py instance.json

# Convert odML to BIDS/NWB/openMINDS (Layer 4 -> Layer 5)
python converters/odml_to_standards.py --all -o output/
python converters/odml_to_standards.py instance.odml.yaml -o output/

# Validate outputs
python converters/validate_outputs.py --all output/

Configuration files:

• converters/mappings/cedar_odml.yaml — Layer 3->4 field mapping
• converters/mappings/crosswalk_subject.yaml — Layer 4->5 field mapping + transforms

See converters/README.md for architecture details and transform documentation.

Standards Versions

Standard	Repository	Commit
BIDS	bids-standard/bids-specification	1cc32de2 (schema-1.1.5)
NWB	NeurodataWithoutBorders/nwb-schema	1cbd9a8c (2.9.0)
openMINDS	openMetadataInitiative/openMINDS	2632108e (v4 schemas; Subject/SubjectState/Strain identical to latest)
openMINDS instances	openMetadataInitiative/openMINDS_instances	d34f192f
PyNWB	NeurodataWithoutBorders/pynwb	4b7f5516 (post-3.1.3)

Schema Files Used for Analysis

The gap analysis tables were validated against the following schema files:

BIDS (participants.tsv, sessions.tsv columns):

• standards/bids/src/schema/rules/tabular_data/modality_agnostic.yaml
• standards/bids/src/schema/objects/columns.yaml (controlled vocabularies for sex, handedness, age, species, strain, strain_rrid, pathology)

NWB (Subject container):

• standards/nwb/core/nwb.file.yaml (lines 412-460: Subject neurodata_type_def)

PyNWB (best practice recommendations not in schema):

• standards/pynwb/src/pynwb/file.py (lines 80-116: Subject class)
  • age: ISO 8601 Duration format (lines 81-82)
  • sex: F/M/U/O vocabulary (lines 102-104)
  • species: latin binomial name (lines 105-106)
  • weight: kilograms unit (lines 110-112)

Note: The NWB schema defines these fields as free text (dtype: text). The format/vocabulary recommendations come from the PyNWB library docstrings, not the schema.

openMINDS (Subject, SubjectState):

• standards/openminds/schemas/v4.0/core/research/subject.schema.omi.json
• standards/openminds/schemas/v4.0/core/research/subjectState.schema.omi.json
• standards/openminds/schemas/v4.0/core/research/strain.schema.omi.json

openMINDS controlled terms (BiologicalSex, Handedness, AgeCategory, SubjectAttribute):

• standards/openminds-instances/instances/v4.0/terminologies/

CEDAR Test Instances

Test instances in data/cedar/instances/ cover different species and field combinations:

Instance	Purpose
Mouse_01_C57BL6J_Control	Strain RRID, age in days, genotype, genetic strain type
Macaque_M1_Trained_Adult	No strain, age in years, handedness, negative relative time
Patient_01_Epilepsy_Monitoring	Pathology (MONDO), unknown sex, clinical scenario

All three instances are created via the CEDAR API (scripts/create_instances.py). An earlier bootstrap instance created through the CEDAR web UI is archived in scripts/cedar_bootstrap/ — it was used to reverse-engineer the JSON-LD structure for the API script.

See data/cedar/instances/cedar_mock_instances.md for detailed field values.

Getting Started

Prerequisites

This project uses uv for dependency management. Install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone and Setup

# Clone with submodules
git clone --recurse-submodules https://github.com/[username]/neuro-multi-standard-workflow.git
cd neuro-multi-standard-workflow

# Install dependencies (uv reads .python-version for correct Python)
uv sync

If you already cloned without submodules:

git submodule update --init --recursive

Running Scripts

# Using uv run (recommended)
uv run python converters/odml_to_standards.py --all -o output/

# Or activate the virtual environment
source .venv/bin/activate
python converters/odml_to_standards.py --all -o output/

License

Code in converters/, scripts/, and project configuration files is licensed under MIT. Mock data, templates, analysis, and documentation in data/, analysis/, docs/, and output/ are licensed under CC BY 4.0. All data in this repository is synthetic and created for demonstration purposes.

Third-party components

The standards/ directory contains git submodules of external projects, each under its own license:

• bids — CC BY 4.0
• nwb — BSD-3-Clause
• openminds, openminds-instances — MIT
• pynwb — BSD-3-Clause

See each submodule's LICENSE file for details.