diff --git a/.circleci/config.yml b/.circleci/config.yml index 4e6d245a9c..bce29c30ea 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -49,6 +49,7 @@ jobs: --ignore-url 'https://jsoneditoronline.org' \ --ignore-url 'https://rrid.site.*' \ --ignore-url 'https://jsr.io/.*' \ + --ignore-url 'https://scicrunch.org/resolver/.*' \ ~/project/site/*html ~/project/site/*/*.html else echo "Release PR - do nothing" diff --git a/mkdocs.yml b/mkdocs.yml index 288a5f68f7..52f60a5d16 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 - Electromyography: modality-specific-files/electromyography.md - Derivatives: - BIDS Derivatives: derivatives/introduction.md @@ -45,6 +46,7 @@ nav: - MEG file formats: appendices/meg-file-formats.md - MEG systems: appendices/meg-systems.md - Coordinate systems: appendices/coordinate-systems.md + - Microelectrode surgical coordinates: appendices/microelectrode-surgical-coordinates.md - Quantitative MRI: appendices/qmri.md - Arterial Spin Labeling: appendices/arterial-spin-labeling.md - Cross modality correspondence: appendices/cross-modality-correspondence.md diff --git a/src/appendices/coordinate-systems.md b/src/appendices/coordinate-systems.md index 9c661b7b10..4adcf3182c 100644 --- a/src/appendices/coordinate-systems.md +++ b/src/appendices/coordinate-systems.md @@ -255,6 +255,162 @@ Please note that `space-scanner` SHOULD NOT be used, it is mentioned in this spe | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | scanner | The intrinsic coordinate system of the original image (the first entry of `RawSources`) after reconstruction and conversion to NIfTI or equivalent for the case of surfaces and dual volume/surface files. | +## Microelectrode Electrophysiology Specific Coordinate Systems + +Restricted keywords for the `MicroephysCoordinateSystem` field in the +`coordsystem.json` file for microelectrode electrophysiology datasets (both `icephys` and `ecephys`): + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Coordinate SystemDescriptionReference
Pixels + If electrodes are localized in 2D space (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/rendering of the electrodes on the brain. In this case, coordinates must be + (row,column) pairs, with (0,0) corresponding to the upper left pixel and (N,0) corresponding + to the lower left pixel. +
Stereotaxic + A generic stereotaxic coordinate system commonly used in animal neuroscience for surgical targeting + and electrode localization. The origin is at bregma, a skull landmark defined as the intersection + of the coronal and sagittal sutures. The three axes are: AP (Anterior-Posterior) with positive values + anterior to the reference point, ML (Medial-Lateral) with positive values to the right of midline, + and DV (Dorsal-Ventral) with positive values ventral to the reference point. + See the [Microelectrode Surgical Coordinates](microelectrode-surgical-coordinates.md) + appendix for detailed axis conventions and angle definitions. + Units are typically in millimeters or micrometers. +
AllenCCFv3 + Allen Common Coordinate Framework version 3 (RRID:SCR_020999), + a 3D reference space for the mouse brain based on average anatomy. The framework provides a systematic + way to map and compare data across different experiments and labs. Origin and orientation follow the + Allen Institute conventions. + doi:10.1016/j.cell.2020.04.007
WaxholmSpace + A standardized 3D coordinate system for the mouse brain (RRID:SCR_001592) + based on high-resolution imaging data. + doi:10.1016/j.neuroimage.2010.06.067
WistarRatAtlas + A multidimensional magnetic resonance histology atlas of the adult Wistar rat brain + (RRID:SCR_006288). This atlas provides + high-resolution anatomical reference for rat brain studies. + doi:10.1016/j.neuroimage.2012.05.041
PaxinosWatson + The Paxinos and Watson rat brain atlas (RRID:SCR_006369), + a widely used stereotaxic coordinate system for the rat brain. + Provides standardized coordinates based on skull landmarks (bregma, lambda) for targeting brain structures. + Multiple editions available; users should specify the edition used in MicroephysCoordinateSystemDescription. + Paxinos G, Watson C. The Rat Brain in Stereotaxic Coordinates. Academic Press.
FranklinPaxinos + The Franklin and Paxinos mouse brain atlas (RRID:SCR_007127), + a widely used stereotaxic coordinate system for the mouse brain. + Provides standardized coordinates based on skull landmarks (bregma, lambda) for targeting brain structures. + Multiple editions available; users should specify the edition used in MicroephysCoordinateSystemDescription. + Franklin KBJ, Paxinos G. The Mouse Brain in Stereotaxic Coordinates. Academic Press.
SwansonRat + The Swanson rat brain atlas, a widely used stereotaxic coordinate system for the rat brain. + Provides detailed cytoarchitectonic parcellation and standardized coordinates for targeting brain structures. + Multiple editions available; users should specify the edition used in MicroephysCoordinateSystemDescription. + Swanson LW. Brain Maps: Structure of the Rat Brain. Elsevier.
CHARM + Cortical Hierarchy Atlas of the Rhesus Macaque, a modern MRI-based atlas for the macaque brain. + Provides hierarchical cortical parcellation based on anatomical connectivity patterns. + doi:10.1016/j.neuroimage.2021.117997
D99 + Digital version of the Saleem and Logothetis macaque brain atlas. + Provides detailed parcellation of the rhesus macaque brain based on histological sections. + doi:10.1093/cercor/bhw248
PaxinosMacaque + The Paxinos rhesus macaque brain atlas, a stereotaxic coordinate system for the macaque brain. + Provides standardized coordinates based on stereotaxic landmarks for targeting brain structures. + Multiple editions available; users should specify the edition used in MicroephysCoordinateSystemDescription. + Paxinos G, Huang XF, Petrides M, Evrard, H. The Rhesus Monkey Brain in Stereotaxic Coordinates. Academic Press.
MarmosetBrainAtlas + A standardized 3D coordinate system for the common marmoset brain. + Provides high-resolution anatomical reference for marmoset brain studies. + doi:10.1016/j.neuroimage.2017.12.004
individual + Subject-specific anatomical coordinate system derived from the individual subject's anatomy. The origin + and orientation should be specified in MicroephysCoordinateSystemDescription. This coordinate + system requires specifying an additional, subject-specific file to be fully defined. +
Other + Use this for other coordinate systems and specify all required details in the + MicroephysCoordinateSystemDescription field. +
+ +If you believe a specific coordinate system should be added to the list +of restricted keywords for microelectrode electrophysiology, please open a new issue on the +[bids-standard/bids-specification GitHub repository](https://github.com/bids-standard/bids-specification/issues/new/choose). + +For detailed information about coordinate systems in microelectrode electrophysiology, +including probe angles and anatomical reference points, see the +[Microelectrode Electrophysiology specification](../modality-specific-files/microelectrode-electrophysiology.md#coordinate-system-json-_coordsystemjson). + [common file level metadata fields]: ../derivatives/common-data-types.md#common-file-level-metadata-fields diff --git a/src/appendices/microelectrode-surgical-coordinates.md b/src/appendices/microelectrode-surgical-coordinates.md new file mode 100644 index 0000000000..c40e1aa241 --- /dev/null +++ b/src/appendices/microelectrode-surgical-coordinates.md @@ -0,0 +1,61 @@ +# Microelectrode Surgical Coordinates + +The surgical coordinates system provides a standard way to describe the placement of an intracranial probe implantation during surgery. + +## Anatomical Reference Points + +In neurosurgery and research, it can be important to define coordinates for where in the brain a surgical intervention will take place. +These coordinates rely on anatomical markers that are uniform across individuals. +There are two major anatomical markers on the dorsal surface of the brain that are formed when the plates of the skull fuse during development, and these markers are often used to identify the location of various anatomical structures of the brain. + +Bregma and Lambda anatomical reference points + +**Bregma**: the anatomical point on the skull at which the coronal suture (between frontal and parietal bones) is intersected perpendicularly by the sagittal suture (between left and right parietal bones). + +**Lambda**: the meeting point of the sagittal suture (between left and right parietal bones) and the lambdoid suture (between parietal and occipital bones). + +Both points serve as standard reference points for stereotaxic coordinates in neuroscience research. `(0,0,0)` is assumed to be Bregma when working with rodents. It may optionally be defined differently using `anatomical_reference_point`, and MUST be defined for other species. + +## Stereotaxic Coordinate System Conventions + +All stereotaxic coordinate systems follow a right-handed coordinate system with the following conventions: + +AP_ML_DV coordinate system + +- **AP (Anterior-Posterior) axis:** Positive values are anterior to reference point +- **ML (Medial-Lateral) axis:** Positive values are to the right (as seen from behind) +- **DV (Dorsal-Ventral) axis:** Positive values are ventral (following right-hand rule). For humans, this is the superior-inferior axis, and positive values point to inferior. + +Proper understanding and application of these angles is critical for accurate probe placement and experimental reproducibility. All stereotaxic measurements use three angles to specify orientation: + +### AP angle (Anterior-Posterior rotation) + +AP angle rotation diagram + +- Measured as rotation from the vertical axis in the sagittal plane +- 0° represents vertical along DV axis +- Range: -180° to +180° +- Positive values indicate anterior rotation +- Example: +15° indicates probe tilted 15° anteriorly from vertical + +### ML angle (Medial-Lateral rotation) + +ML angle rotation diagram + +- Measured as rotation from the vertical axis in the coronal plane +- 0° represents vertical along DV axis +- Range: -180° to +180° +- Positive values indicate rightward/clockwise rotation (as seen from behind) +- Example: +20° indicates probe tilted 20° to the right from vertical + +### Rotation angle (around probe axis) + +Rotation angle diagram + +- 0° when probe features align with the coronal plane +- Range: -180° to +180° (or 0° to 360°) +- Positive rotation is clockwise when viewed from above + +!!! note "Source Attribution" + + The coordinate system conventions and angle definitions presented in this section are adapted from the [BrainSTEM documentation](https://support.brainstem.org/datamodel/schemas/coordinates/). MIT License; Copyright (c) 2025 Peter C. Petersen 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..b406347e76 --- /dev/null +++ b/src/modality-specific-files/microelectrode-electrophysiology.md @@ -0,0 +1,933 @@ +# 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 without + specifically targeting the membrane of neurons, measuring field potentials (μV) from nearby neurons. + Examples: Recordings with microelectrode 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, intracellular 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: + + + + + + + + + + + + + + + + + + + + + +
FormatExtension(s)Description
Neuroscience Information Exchange Format.nix + A generic and open framework with an hdf5 backend and a defined interface to many microephys formats via the + Neo library. The .nix file has to contain a valid Neo structure. +
Neurodata Without Borders.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`) + +All metadata that is not directly related to one of the other metadata files (probe/electrode/channel information) should be stored in a single JSON file corresponding to the datatype: `_icephys.json` or `_ecephys.json` for intracellular and extracellular, respectively. + +There should be one such JSON file for each data file. + +The `*_ecephys.json` or `*_icephys.json` file can be used to store any microephys-specific metadata for the dataset. All setup-related metadata should be stored 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 + +{{ 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-