[ENH] microelectrode electrophysiology specification (BEP032)

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

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 (`icephys` and `ecephys` modalities) data 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)).
+
+##
+
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the directory
+  src/schema/rules/files/raw
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filename_template(
+   "raw",
+   datatypes=["ecephys", "icephys"],
+   suffixes=["ecephys", "icephys", "events"]
+)
+}}
+
+<!-- Link Definitions -->

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

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

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-<index>` entity to indicate each part.

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

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.

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

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

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