diff --git a/mkdocs.yml b/mkdocs.yml index c48b878783..446df5ad2e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,6 +24,7 @@ nav: - Near-Infrared Spectroscopy: modality-specific-files/near-infrared-spectroscopy.md - Motion: modality-specific-files/motion.md - Magnetic Resonance Spectroscopy: modality-specific-files/magnetic-resonance-spectroscopy.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/images/AP_ML_DV.png b/src/modality-specific-files/images/AP_ML_DV.png new file mode 100644 index 0000000000..442ea21556 Binary files /dev/null and b/src/modality-specific-files/images/AP_ML_DV.png differ diff --git a/src/modality-specific-files/images/AP_angle.png b/src/modality-specific-files/images/AP_angle.png new file mode 100644 index 0000000000..bd5194a37b Binary files /dev/null and b/src/modality-specific-files/images/AP_angle.png differ diff --git a/src/modality-specific-files/images/ML_angle.png b/src/modality-specific-files/images/ML_angle.png new file mode 100644 index 0000000000..765d43f3c0 Binary files /dev/null and b/src/modality-specific-files/images/ML_angle.png differ diff --git a/src/modality-specific-files/images/bregma_and_lambda.png b/src/modality-specific-files/images/bregma_and_lambda.png new file mode 100644 index 0000000000..b995027c4a Binary files /dev/null and b/src/modality-specific-files/images/bregma_and_lambda.png differ diff --git a/src/modality-specific-files/images/coordinates.png b/src/modality-specific-files/images/coordinates.png new file mode 100644 index 0000000000..ef0527e384 Binary files /dev/null and b/src/modality-specific-files/images/coordinates.png differ diff --git a/src/modality-specific-files/images/rotation_angle.png b/src/modality-specific-files/images/rotation_angle.png new file mode 100644 index 0000000000..e09e03b6ec Binary files /dev/null and b/src/modality-specific-files/images/rotation_angle.png differ diff --git a/src/modality-specific-files/microelectrode-electrophysiology.md b/src/modality-specific-files/microelectrode-electrophysiology.md new file mode 100644 index 0000000000..4c553afc9d --- /dev/null +++ b/src/modality-specific-files/microelectrode-electrophysiology.md @@ -0,0 +1,1012 @@ +# 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 was initiated by members of the INCF Working Group on Standardized Data Structures in 2020 +to develop specifications and tools for standardizing experimental data recorded with animal models +in neuroscience and its associated metadata. + +!!! example "Example datasets" + + 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. + +## Terminology: Modality and Datatypes + +The Microelectrode Electrophysiology modality encompasses recordings made with micrometer-scale electrodes, +distinguishing it from related BIDS modalities (EEG, MEG, iEEG) that use larger electrodes. +This modality is primarily used in animal research. + +Within this modality, BIDS defines two datatypes based on fundamentally different recording techniques (see [Issue #1800](https://github.com/bids-standard/bids-specification/issues/1800)): + +- **`ecephys`** (Extracellular Electrophysiology): Electrodes remain in the extracellular space, + measuring field potentials (μV) from nearby neurons without membrane penetration. + Examples: Neuropixels probes, tetrodes, multi-electrode arrays. + +- **`icephys`** (Intracellular Electrophysiology): Electrodes penetrate or attach to cell membranes to directly measure + intracellular potentials (mV) and cellular dynamics. + Examples: cell-attached patch clamp, whole-cell patch clamp, sharp electrode recordings. + +These datatypes differ in recording technique, signal amplitude, required metadata +(for example, `pipette_solution` and `recording_mode` for icephys; probe geometry for ecephys), +and analysis pipelines. The terms are established and used in [Neurodata Without Borders (NWB)](https://www.nwb.org). + +Both datatypes share a unified BIDS structure (probes, electrodes, channels) with technique-specific optional metadata fields. +Files are organized into `ecephys/` or `icephys/` subdirectories with corresponding file suffixes. + +## Primary Data File Formats + +Microelectrode electrophysiology 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 microephys 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` | An open data standard for neurophysiology, including data from intracellular and extracellular electrophysiology experiments. | + +Both of these formats can also store essential metadata of the datasets. +Some of this metadata needs 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 several advantages: + +- It makes the dataset easier for humans to scan, as essential information is easily accessible without loading the data files. +- The dataset adheres to the BIDS standard and can benefit from tools built on top of this standard, such as [bids-validator](https://github.com/bids-standard/bids-validator). +- It simplifies the separation of data and basic metadata, enabling, for example, the publication of a dataset in a lightweight fashion with access to the data files on request (as implemented by [DataLad](https://www.datalad.org)). + + + + + +### icephys + +{{ MACROS___make_filename_template( +"raw", +datatypes=["icephys"], +suffixes=["icephys", "events", "channels", "electrodes","scans","probes","coordsystem"] +) +}} + +### ecephys + +{{ MACROS___make_filename_template( +"raw", +datatypes=["ecephys"], +suffixes=["ecephys", "events", "channels", "electrodes","scans","probes","coordsystem"] +) +}} + +## Sidecar JSON (`*_icephys.json` and `*_ecephys.json`) + +We propose to store all metadata that is not directly related to one of the other metadata files (probe/electrode/channel information) into a single JSON file corresponding to the datatype: `_icephys.json` or `_ecephys.json` for intracellular and extracellular correspondingly. + +There should be one such JSON file for each data file. + +The `*_ephys.json` file can be used to store any microephys-specific metadata for the dataset. We recommend storing all setup-related metadata in a dedicated node of the JSON file called `Setup`. +We recommend using the following keys to describe the setup: + +### Institution Information + +{{ MACROS___make_sidecar_table("microephys.microephysInstitutionInformation") }} + +### Setup Information + +{{ MACROS___make_sidecar_table("microephys.microephysSetup") }} + +### Processing Information + +{{ MACROS___make_sidecar_table("microephys.microephysProcessing") }} + +### Additional Procedure Information + +Furthermore, additional information can be stored about the recording procedure. +We RECOMMEND to use a dedicated `Procedure` node with the following keys: + +- `Pharmaceuticals` +- `Sample` +- `Supplementary` + + + +#### Pharmaceuticals + +For each pharmaceutical we RECOMMEND to use a dedicated node with the name of the Pharmaceuticals containing the following administration details: + +{{ MACROS___make_sidecar_table("microephys.microephysPharmaceuticals") }} + +#### Sample + +{{ MACROS___make_sidecar_table("microephys.microephysSample") }} + +#### Supplementary + +{{ MACROS___make_sidecar_table("microephys.microephysSupplementary") }} + +### Task Information + +If the OPTIONAL [` task-