diff --git a/mkdocs.yml b/mkdocs.yml index 114e05c135..31bb10fe6a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,6 +19,7 @@ nav: - Microscopy: modality-specific-files/microscopy.md - Near-Infrared Spectroscopy: modality-specific-files/near-infrared-spectroscopy.md - Motion: modality-specific-files/motion.md + - Microelectrode Electrophysiology: modality-specific-files/microelectrode-electrophysiology.md - Derivatives: - BIDS Derivatives: derivatives/introduction.md - Common data types and metadata: derivatives/common-data-types.md diff --git a/src/modality-specific-files/microelectrode-electrophysiology.md b/src/modality-specific-files/microelectrode-electrophysiology.md new file mode 100644 index 0000000000..ac16034b18 --- /dev/null +++ b/src/modality-specific-files/microelectrode-electrophysiology.md @@ -0,0 +1,58 @@ +# Microelectrode Electrophysiology + +Support for Microelectrode Electrophysiology was developed as a [BIDS Extension Proposal](../extensions.md#bids-extension-proposals) [BEP032: Animal electrophysiology (ephys)](https://bids.neuroimaging.io/bep032). + +Please see [Citing BIDS](../introduction.md#citing-bids) on how to appropriately credit this extension +when referring to it in the context of the academic literature. + +This BEP has been initiated by members of the INCF Working Group on Standardized Data Structures, +that was initiated in 2020 to develop a set of specifications and tools +that would allow the standardization of a directory structure for experimental data recorded +with animal models in neuroscience, and its associated metadata. + +Please consider joining this working group if you would like to contribute to this effort. +You can also reach the moderators of this BEP through our [main discussion forum](https://github.com/INCF/neuroscience-data-structure/issues), where you can participate in existing discussions or raise new questions / issues. + +Most core principles of the original BIDS and particulars of BIDS-iEEG specification are adopted +for this modality as well, though some special considerations and additional fields were added. + +Several [example Microelectrode Electrophysiology datasets](https://bids-standard.github.io/bids-examples/#microephys) +have been formatted using this specification and can be used for practical guidance when curating a new dataset. + +## Primary data file formats + +Unprocessed microelectrode electrophysiology (`microephys`) modality data (of `icephys` or `ecephys` datatypes) must be stored in an [open file format](https://en.wikipedia.org/wiki/Open_format), +while the native format, if different, can be stored in an optional `sourcedata/` directory. +The native file format is used in case conversion elicits the loss of crucial metadata specific to manufacturers and specific acquisition systems. +Metadata should be included alongside the data in the `.json` and `.tsv` files. +The current list of allowed data file formats: + +| **Format** | **Extension(s)** | **Description** | +--------------------------------------------------------------------------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Neuroscience Information Exchange Format](https://nixio.readthedocs.io/en/latest/) | `.nix` | A generic and open framework with an hdf5 backend and a defined interface to many ephys formats via the [Neo library](https://neo.readthedocs.io/en/latest/). The `.nix` file has to contain a valid Neo structure. | +| [Neurodata Without Borders](https://www.nwb.org) | `.nwb` | BRAIN Initiative Data Standard based on an hdf5 backend ... | + +Both of these formats can also store essential metadata of the datasets. +Some of these need to be duplicated in BIDS `.tsv` and `.json` sidecar files. +Even though the duplication requires additional effort to ensure the consistency of the data, it provides a number of advantages: +- Making the dataset easier for humans to scan as essential information is easily accessible without loading the data files +- The dataset follows the BIDS standard and can benefit from tools building on top of this standard, starting with [bids-validator](https://github.com/bids-standard/bids-validator). +- It simplifies the separation of data and basic metadata, for example to publish a dataset in a light-weight fashion with access to the data files on request (as implemented by [DataLad](https://www.datalad.org)). + +## + + +{{ MACROS___make_filename_template( + "raw", + datatypes=["ecephys", "icephys"], + suffixes=["ecephys", "icephys", "events"] +) +}} + + diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml index 3ccb32d324..5010d2453f 100644 --- a/src/schema/objects/columns.yaml +++ b/src/schema/objects/columns.yaml @@ -42,6 +42,41 @@ age: for privacy purposes. type: number unit: year +alpha_rotation: + name: alpha_rotation + display_name: Alpha rotation + description: | + Euler angle to match probe extension dimensions (width, height, depth) to global x, y, z coordinates. + unit: + degree +associated_brain_region: + name: associated_brain_region + display_name: Associated brain region + description: | + A textual indication on the location of the probe, + preferably species-independent terms as obtained, for example from Uberon. + type: string +associated_brain_region_id: + name: associated_uberon_brain_region_id + display_name: Associated brain region identifier + description: | + An identifier of the associated brain region based on the Uberon ontology + for anatomical structures in animals, for example "UBERON:0010415" + type: number +associated_brain_region_quality_type: + name: associated_brain_region_quality_type + display_name: Associated brain region quality type + description: | + The method used to identify the associated brain region (estimated|proof) + depending on anatomical pictures proofing the location or indirect estimation of the location. + type: string +beta_rotation: + name: beta_rotation + display_name: Beta rotation + description: | + Euler angle to match probe extension dimensions (width, height, depth) to global x, y, z coordinates. + unit: + degree cardiac: name: cardiac display_name: Cardiac measurement @@ -84,6 +119,19 @@ component: - $ref: objects.enums.quat_z.value - $ref: objects.enums.quat_w.value - n/a +contact_count: + name: contact_count + display_name: Contact count + description: | + Number of miscellaneous analog contacts for auxiliary signals. + type: number +depth__probes: + name: height + display_name: Height + description: | + Physical height of the probe. + type: number + unit: mm detector__channels: name: detector display_name: Detector Name @@ -131,6 +179,12 @@ description: description: | Brief free-text description of the channel, or other information of interest. type: string +device_serial_number: + name: device_serial_number + display_name: Device serial number + description: | + The serial number of the probe (provided by the manufacturer). + type: string description__optode: name: description display_name: Description @@ -172,6 +226,13 @@ filename: Relative paths to files. type: string format: participant_relative +gamma_rotation: + name: gamma_rotation + display_name: Gamma rotation + description: | + Euler angle to match probe extension dimensions (width, height, depth) to global x, y, z coordinates. + unit: + degree group__channel: name: group display_name: Channel group @@ -213,6 +274,13 @@ handedness: - AMBIDEXTROUS - Ambidextrous - n/a +height__probes: + name: height + display_name: Height + description: | + Physical height of the probe. + type: number + unit: mm hemisphere: name: hemisphere display_name: Electrode hemisphere @@ -288,6 +356,12 @@ material: description: | Material of the electrode (for example, `Tin`, `Ag/AgCl`, `Gold`). type: string +material__probes: + name: material__probes + display_name: Material + description: | + A textual description of the base material of the probe. + type: string metabolite_parent_fraction: name: metabolite_parent_fraction display_name: Metabolite parent fraction @@ -412,6 +486,12 @@ reference__ieeg: - type: string enum: - n/a +reference_atlas: + name: reference_atlas + display_name: Reference atlas + description: | + Name of reference atlas used for associated brain region identification, preferably an ebrains supported atlas. + type: string reference_frame: name: reference_frame display_name: Reference frame @@ -724,6 +804,12 @@ type__optodes: - $ref: objects.enums.source.value - $ref: objects.enums.detector.value - n/a +type__probes: + name: type + display_name: Type + description: | + The type of the probe. + type: string units: name: units display_name: Units @@ -806,6 +892,13 @@ whole_blood_radioactivity: Radioactivity in whole blood samples, in unit of radioactivity measurements in whole blood samples (for example, `kBq/mL`). type: number +width__probes: + name: width + display_name: Width + description: | + Physical width of the probe. + type: number + unit: mm x: name: x display_name: X position diff --git a/src/schema/objects/datatypes.yaml b/src/schema/objects/datatypes.yaml index c51fa41382..1e57a7892d 100644 --- a/src/schema/objects/datatypes.yaml +++ b/src/schema/objects/datatypes.yaml @@ -16,6 +16,11 @@ dwi: display_name: Diffusion-Weighted Imaging description: | Diffusion-weighted imaging (DWI). +ecephys: + value: ecephys + display_name: Extracellular Electrophysiology + description: | + Electrophysiological data from extracellular microelectrodes eeg: value: eeg display_name: Electroencephalography @@ -30,6 +35,11 @@ func: display_name: Task-Based Magnetic Resonance Imaging description: | Task (including resting state) imaging data +icephys: + value: icephys + display_name: Intracellular Electrophysiology + description: | + Electrophysiological data acquired from intracellular or patch microelectrodes ieeg: value: ieeg display_name: Intracranial electroencephalography diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml index 6facc34c0d..2745e7bc1b 100644 --- a/src/schema/objects/entities.yaml +++ b/src/schema/objects/entities.yaml @@ -331,12 +331,12 @@ split: display_name: Split description: | In the case of long data recordings that exceed a file size of 2Gb, - `.fif` files are conventionally split into multiple parts. - Each of these files has an internal pointer to the next file. + `.fif`, `.nwb`, `.nix` files are conventionally split into multiple parts. + Each of the `.fif` files has an internal pointer to the next file. This is important when renaming these split recordings to the BIDS convention. Instead of a simple renaming, files should be read in and saved under their - new names with dedicated tools like [MNE-Python](https://mne.tools/), + new names with dedicated tools like [MNE-Python](https://mne.tools/) for `.fif`, which will ensure that not only the filenames, but also the internal file pointers, will be updated. It is RECOMMENDED that `.fif` files with multiple parts use the `split-` entity to indicate each part. diff --git a/src/schema/objects/extensions.yaml b/src/schema/objects/extensions.yaml index 96056e497d..21535aae96 100644 --- a/src/schema/objects/extensions.yaml +++ b/src/schema/objects/extensions.yaml @@ -189,6 +189,11 @@ niigz: display_name: Compressed NIfTI description: | A compressed Neuroimaging Informatics Technology Initiative (NIfTI) data file. +nix: + value: .nix + display_name: Neuroscience Information Exchange Format + description: | + A [Neuroscience Information Exchange](https://nixio.readthedocs.io) file. nwb: value: .nwb display_name: Neurodata Without Borders Format diff --git a/src/schema/objects/modalities.yaml b/src/schema/objects/modalities.yaml index 4809e380df..73018dce44 100644 --- a/src/schema/objects/modalities.yaml +++ b/src/schema/objects/modalities.yaml @@ -35,3 +35,6 @@ motion: nirs: display_name: Near-Infrared Spectroscopy description: Data acquired with NIRS. +microephys: + display_name: Microelectrode Electrophysiology + description: Electrophysiological data acquired using microelectodes. diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml index 0ddc8647d2..f4f0c3f7af 100644 --- a/src/schema/objects/suffixes.yaml +++ b/src/schema/objects/suffixes.yaml @@ -573,6 +573,11 @@ dwi: display_name: Diffusion-weighted image description: | Diffusion-weighted imaging contrast (specialized T2 weighting). +ecephys: + value: ecephys + display_name: Extracellular Electrophysiology + description: | + Extracellular electrophysiological data. eeg: value: eeg display_name: Electroencephalography @@ -612,6 +617,11 @@ hipCT: display_name: HiP-CT description: | Hierarchical Phase-Contrast Tomography imaging data +icephys: + value: icephys + display_name: Inracellular Electrophysiology + description: | + Intracellular electrophysiological data. ieeg: value: ieeg display_name: Intracranial Electroencephalography @@ -744,6 +754,16 @@ physio: display_name: Physiological recording description: | Physiological recordings such as cardiac and respiratory signals. +probe: + value: probe + display_name: A recording probe + description: | + A probe with one or more recording contacts. +probes: + value: probes + display_name: Implanted physical devices + description: | + Physical devices used for recording microelectrode electrophysiology data, whether chronically or acutely implanted. probseg: value: probseg display_name: Probabilistic Segmentation diff --git a/src/schema/rules/files/raw/channels.yaml b/src/schema/rules/files/raw/channels.yaml index 06c213be17..ea1b164483 100644 --- a/src/schema/rules/files/raw/channels.yaml +++ b/src/schema/rules/files/raw/channels.yaml @@ -16,6 +16,16 @@ channels: acquisition: optional run: optional +# microephys has an additional 'sample' entity +channels__microephys: + $ref: rules.files.raw.channels.channels + datatypes: + - icephys + - ecephys + entities: + $ref: rules.files.raw.channels.channels.entities + sample: optional + # MEG has an additional entity available channels__meg: $ref: rules.files.raw.channels.channels @@ -57,6 +67,17 @@ coordsystem__eeg: $ref: rules.files.raw.channels.coordsystem.entities space: optional +# microephys has sample AND space entities +coordsystem__microephys: + $ref: rules.files.raw.channels.coordsystem + datatypes: + - ecephys + - icephys + entities: + $ref: rules.files.raw.channels.coordsystem.entities + sample: optional + space: optional + electrodes: suffixes: - electrodes diff --git a/src/schema/rules/files/raw/microephys.yaml b/src/schema/rules/files/raw/microephys.yaml new file mode 100644 index 0000000000..4a5aaaf5bc --- /dev/null +++ b/src/schema/rules/files/raw/microephys.yaml @@ -0,0 +1,38 @@ +--- +microephys: + suffixes: + - ecephys + - icephys + extensions: + - .nwb + # possible future: serialization in .zarr format to accompany .ome.zarr + # - .nwb.zarr + - .nix + datatypes: + - ecephys + - icephys + entities: + subject: required + session: optional + sample: optional + task: optional + acquisition: optional + run: optional + split: optional + +probes: + suffixes: + - probes + extensions: + - .tsv + datatypes: + - ecephys + - icephys + entities: + subject: required + session: optional + sample: optional + task: optional + acquisition: optional + run: optional + split: optional