[ENH]: BEP032 formal review

.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"

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

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`):
+
+<table>
+  <thead>
+    <tr>
+      <th><strong>Coordinate System</strong></th>
+      <th><strong>Description</strong></th>
+      <th><strong>Reference</strong></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Pixels</td>
+      <td>
+        If electrodes are localized in 2D space (x and y are specified and z is <code>n/a</code>), 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.
+      </td>
+      <td></td>
+    </tr>
+    <tr>
+      <td>Stereotaxic</td>
+      <td>
+        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.
+      </td>
+      <td></td>
+    </tr>
+    <tr>
+      <td>AllenCCFv3</td>
+      <td>
+        Allen Common Coordinate Framework version 3 (<a href="https://scicrunch.org/resolver/RRID:SCR_020999">RRID:SCR_020999</a>),
+        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.
+      </td>
+      <td><a href="https://doi.org/10.1016/j.cell.2020.04.007">doi:10.1016/j.cell.2020.04.007</a></td>
+    </tr>
+    <tr>
+      <td>WaxholmSpace</td>
+      <td>
+        A standardized 3D coordinate system for the mouse brain (<a href="https://scicrunch.org/resolver/RRID:SCR_001592">RRID:SCR_001592</a>)
+        based on high-resolution imaging data.
+      </td>
+      <td><a href="https://doi.org/10.1016/j.neuroimage.2010.06.067">doi:10.1016/j.neuroimage.2010.06.067</a></td>
+    </tr>
+    <tr>
+      <td>WistarRatAtlas</td>
+      <td>
+        A multidimensional magnetic resonance histology atlas of the adult Wistar rat brain
+        (<a href="https://scicrunch.org/resolver/RRID:SCR_006288">RRID:SCR_006288</a>). This atlas provides
+        high-resolution anatomical reference for rat brain studies.
+      </td>
+      <td><a href="https://doi.org/10.1016/j.neuroimage.2012.05.041">doi:10.1016/j.neuroimage.2012.05.041</a></td>
+    </tr>
+    <tr>
+      <td>PaxinosWatson</td>
+      <td>
+        The Paxinos and Watson rat brain atlas (<a href="https://scicrunch.org/resolver/RRID:SCR_006369">RRID:SCR_006369</a>),
+        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 <code>MicroephysCoordinateSystemDescription</code>.
+      </td>
+      <td>Paxinos G, Watson C. The Rat Brain in Stereotaxic Coordinates. Academic Press.</td>
+    </tr>
+    <tr>
+      <td>FranklinPaxinos</td>
+      <td>
+        The Franklin and Paxinos mouse brain atlas (<a href="https://scicrunch.org/resolver/RRID:SCR_007127">RRID:SCR_007127</a>),
+        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 <code>MicroephysCoordinateSystemDescription</code>.
+      </td>
+      <td>Franklin KBJ, Paxinos G. The Mouse Brain in Stereotaxic Coordinates. Academic Press.</td>
+    </tr>
+    <tr>
+      <td>SwansonRat</td>
+      <td>
+        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 <code>MicroephysCoordinateSystemDescription</code>.
+      </td>
+      <td><a href="https://doi.org/10.1002/cne.24381">Swanson LW. Brain Maps: Structure of the Rat Brain. Elsevier.</a></td>
+    </tr>
+    <tr>
+      <td>CHARM</td>
+      <td>
+        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.
+      </td>
+      <td><a href="https://doi.org/10.1016/j.neuroimage.2021.117997">doi:10.1016/j.neuroimage.2021.117997</a></td>
+    </tr>
+    <tr>
+      <td>D99</td>
+      <td>
+        Digital version of the Saleem and Logothetis macaque brain atlas.
+        Provides detailed parcellation of the rhesus macaque brain based on histological sections.
+      </td>
+      <td><a href="https://doi.org/10.1093/cercor/bhw248">doi:10.1093/cercor/bhw248</a></td>
+    </tr>
+    <tr>
+      <td>PaxinosMacaque</td>
+      <td>
+        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 <code>MicroephysCoordinateSystemDescription</code>.
+      </td>
+      <td>Paxinos G, Huang XF, Petrides M, Evrard, H. The Rhesus Monkey Brain in Stereotaxic Coordinates. Academic Press.</td>
+    </tr>
+    <tr>
+      <td>MarmosetBrainAtlas</td>
+      <td>
+        A standardized 3D coordinate system for the common marmoset brain.
+        Provides high-resolution anatomical reference for marmoset brain studies.
+      </td>
+      <td><a href="https://doi.org/10.1016/j.neuroimage.2017.12.004">doi:10.1016/j.neuroimage.2017.12.004</a></td>
+    </tr>
+    <tr>
+      <td>individual</td>
+      <td>
+        Subject-specific anatomical coordinate system derived from the individual subject's anatomy. The origin
+        and orientation should be specified in <code>MicroephysCoordinateSystemDescription</code>. This coordinate
+        system requires specifying an additional, subject-specific file to be fully defined.
+      </td>
+      <td></td>
+    </tr>
+    <tr>
+      <td>Other</td>
+      <td>
+        Use this for other coordinate systems and specify all required details in the
+        <code>MicroephysCoordinateSystemDescription</code> field.
+      </td>
+      <td></td>
+    </tr>
+  </tbody>
+</table>
+
+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).
+
 <!-- Link Definitions -->
 
 [common file level metadata fields]: ../derivatives/common-data-types.md#common-file-level-metadata-fields

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.
+
+<img src="../modality-specific-files/images/bregma_and_lambda.png" alt="Bregma and Lambda anatomical reference points" style="max-width: 600px;">
+
+**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:
+
+<img src="../modality-specific-files/images/AP_ML_DV.png" alt="AP_ML_DV coordinate system" style="max-width: 600px;">
+
+-   **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)
+
+<img src="../modality-specific-files/images/AP_angle.png" alt="AP angle rotation diagram" style="max-width: 600px;">
+
+-   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)
+
+<img src="../modality-specific-files/images/ML_angle.png" alt="ML angle rotation diagram" style="max-width: 600px;">
+
+-   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)
+
+<img src="../modality-specific-files/images/rotation_angle.png" alt="Rotation angle diagram" style="max-width: 600px;">
+
+-   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