diff --git a/mkdocs.yml b/mkdocs.yml index ef36d6eb5c..d2751fd103 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,6 +20,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/microelectrode-electrophysiology.md b/src/modality-specific-files/microelectrode-electrophysiology.md new file mode 100644 index 0000000000..8d74534a17 --- /dev/null +++ b/src/modality-specific-files/microelectrode-electrophysiology.md @@ -0,0 +1,672 @@ +# 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. + +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. + +!!! 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. + +## Primary data file formats + +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` | 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)). + + +## + + + + + +{{ MACROS___make_filename_template( + "raw", + datatypes=["icephys"], + suffixes=["icephys", "events", "channels", "electrodes","scans","probes","coordsystem"] +) +}} + +{{ MACROS___make_filename_template( + "raw", + datatypes=["ecephys"], + suffixes=["ecephys", "events", "channels", "electrodes","scans","probes","coordsystem"] +) +}} + + +# PARTICIPANT keyfiles +## Participant information + +The `participants.tsv` file is located at the root of the data set directory. +Its presence is RECOMMENDED in order to describe information about the individual subjects (animals) from which the data was recorded. +It follows the [general BIDS specifications to describe participants](../modality-agnostic-files.md#participants-file). + +On top of the existing columns that can be present in this file and that are described in the BIDS specifications (`participant_id`, `species`, `strain`, `strain_rrid`, `sex`, `handedness`, and `age`), we propose to allow adding the following ones: + + +# EPHYS specific files + +The following metadata files are REQUIRED for a given animal ephys session: + +1. `[_ses-]_probes.tsv`: A REQUIRED file listing information on the device used to acquire the electrophysiology data, such as implant or probe specification, location, material, and others. +2. `[_ses-]_electrodes.tsv`: A REQUIRED file listing information on the points of electrical contact to the tissue, such as impedance, names, relative positions, and others. +3. `[_ses-]_channels.tsv`: A REQUIRED file listing information on the recorded signals, such as preprocessing, filtering, ids, and others. + +As with all tsv-based metadata files in BIDS the probes, electrodes and channels tsv files can be accompanied by json sidecar files. + + +## Coordinate System JSON (`*_coordsystem.json`) & Photos of electrode positions (`_photo.jpg`) + +This file provides metadata on the global coordinate system in which the electrodes are placed. +This file is **RECOMMENDED**, and the listed required fields below must be included if a `*_coordsystem.json` file is provided. + +The coordinate system can be defined using reference pictures, anatomical landmarks, brain images, or a reference atlas. +For more details, see the [BIDS Coordinate Systems specifications](../appendices/coordinate-systems.md). + + +Fields relating to the ephys probe and electrode positions: + +{{ MACROS___make_metadata_table( + { + "MicroephysCoordinateSystem":"REQUIRED", + "MicroephysCoordinateUnits":"REQUIRED", + "MicroephysCoordinateSystemDescription":"RECOMMENDED", + "MicroephysCoordinateSystemPhoto":"OPTIONAL", + "MEGCoordinateSystem":"REQUIRED", + } +) }} + +### Allowed 2D coordinate systems + +If electrodes are localized in 2D space (only `x` and `y` are specified, and `z` is `"n/a"`), +then the positions in this file MUST correspond to the locations expressed in pixels on the +photo, drawing, or rendering of the electrodes on the brain. + +In this case, `ephysCoordinateSystem` MUST be defined as `"Pixels"`, +and `ephysCoordinateUnits` MUST be defined as `"pixels"` (note the difference in capitalization). + +Furthermore, the coordinates MUST be `(row,column)` pairs, +with `(0,0)` corresponding to the upper-left pixel and `(N,0)` corresponding to the lower-left pixel. + + +### Photos of the electrode positions (`*_photo.jpg`) + +These can include photos of the electrodes on the brain surface, +photos of anatomical features or landmarks (such as sulcal structures), and fiducials. +Photos can also include an X-ray picture, a flatbed scan of a schematic drawing made during surgery, +or screenshots of a brain rendering with electrode positions. + +The photos may need to be cropped and/or blurred to conceal identifying features +or entirely omitted prior to sharing, depending on the obtained consent. + +If there are photos of the electrodes, the [`_acq-