Skip to content

Commit

Permalink
ENH: Harmonize CoordinateSystem details for MRI, MEG, EEG, iEEG (#717)
Browse files Browse the repository at this point in the history 
* harmonize coordsystems

* fix table pipe

* remove two typos

* fix typo

* text clarifications

Co-authored-by: Taylor Salo <tsalo006@fiu.edu>

Co-authored-by: Taylor Salo <tsalo006@fiu.edu>
  • Loading branch information
@sappelhoff @tsalo
sappelhoff and tsalo authored Feb 1, 2021
1 parent 2da3e7c commit 3b612fb
Show file tree
Hide file tree
Showing 3 changed files with 66 additions and 30 deletions.
7 changes: 4 additions & 3 deletions src/04-modality-specific-files/02-magnetoencephalography.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -346,9 +346,10 @@ Anatomical landmarks:
It is also RECOMMENDED that the MRI voxel coordinates of the actual anatomical
landmarks for co-registration of MEG with structural MRI are stored in the
`AnatomicalLandmarkCoordinates` field in the JSON sidecar of the corresponding
T1w MRI anatomical data of the subject seen in the MEG session (see
[here](01-magnetic-resonance-imaging-data.md#anatomy-imaging-data) ) - for
example: `sub-01/ses-mri/anat/sub-01_ses-mri_acq-mprage_T1w.json`
T1w MRI anatomical data of the subject seen in the MEG session
(see [Anatomy Imaging Data](01-magnetic-resonance-imaging-data.md#anatomy-imaging-data)).

For example: `sub-01/ses-mri/anat/sub-01_ses-mri_acq-mprage_T1w.json`

In principle, these locations are those of absolute anatomical markers. However,
the marking of NAS, LPA and RPA is more ambiguous than that of for example, AC and PC.
Expand Down
27 changes: 15 additions & 12 deletions src/04-modality-specific-files/04-intracranial-electroencephalography.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -393,13 +393,13 @@ General fields:

Fields relating to the iEEG electrode positions:

| **Key name** | **Requirement level** | **Data type** | **Description** |
| ----------------------------------- | -------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| iEEGCoordinateSystem | REQUIRED | [string][] | Defines the coordinate system for the iEEG sensors. See [Appendix VIII](../99-appendices/08-coordinate-systems.md) for a list of restricted keywords for coordinate systems. If `Other`, provide definition of the coordinate system in `iEEGCoordinateSystemDescription`. If positions correspond to pixel indices in a 2D image (of either a volume-rendering, surface-rendering, operative photo, or operative drawing), this must be "Pixels". For more information, see the section on [2D coordinate systems](#allowed-2d-coordinate-systems) |
| iEEGCoordinateUnits | REQUIRED | [string][] | Units of the \_electrodes.tsv, MUST be "m", "mm", "cm" or "pixels". |
| iEEGCoordinateSystemDescription | RECOMMENDED, but REQUIRED if `iEEGCoordinateSystem` is `Other` | [string][] | Free-form text description of the coordinate system. May also include a link to a documentation page or paper describing the system in greater detail. |
| iEEGCoordinateProcessingDescription | RECOMMENDED | [string][] | Has any post-processing (such as projection) been done on the electrode positions (for example, "surface_projection", "none"). |
| iEEGCoordinateProcessingReference | RECOMMENDED | [string][] | A reference to a paper that defines in more detail the method used to localize the electrodes and to post-process the electrode positions. . |
| **Key name** | **Requirement level** | **Data type** | **Description** |
| ----------------------------------- | -------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| iEEGCoordinateSystem | REQUIRED | [string][] | Defines the coordinate system for the iEEG sensors. See [Appendix VIII](../99-appendices/08-coordinate-systems.md) for a list of restricted keywords for coordinate systems. If `"Other"`, provide definition of the coordinate system in `iEEGCoordinateSystemDescription`. If positions correspond to pixel indices in a 2D image (of either a volume-rendering, surface-rendering, operative photo, or operative drawing), this MUST be `"Pixels"`. For more information, see the section on [2D coordinate systems](#allowed-2d-coordinate-systems) |
| iEEGCoordinateUnits | REQUIRED | [string][] | Units of the `*_electrodes.tsv`, MUST be `"m"`, `"mm"`, `"cm"` or `"pixels"`. MUST be `"pixels"` if `iEEGCoordinateSystem` is `Pixels`. |
| iEEGCoordinateSystemDescription | RECOMMENDED, but REQUIRED if `iEEGCoordinateSystem` is `Other` | [string][] | Free-form text description of the coordinate system. May also include a link to a documentation page or paper describing the system in greater detail. |
| iEEGCoordinateProcessingDescription | RECOMMENDED | [string][] | Has any post-processing (such as projection) been done on the electrode positions (for example, "surface_projection", "none"). |
| iEEGCoordinateProcessingReference | RECOMMENDED | [string][] | A reference to a paper that defines in more detail the method used to localize the electrodes and to post-process the electrode positions. . |

### Recommended 3D coordinate systems

Expand All @@ -410,11 +410,14 @@ about preferred names of coordinate systems, such as ACPC).

### 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/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.
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/rendering of the electrodes on the brain.
In this case, `iEEGCoordinateSystem` MUST be defined as `"Pixels"`,
and `iEEGCoordinateUnits` 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.

### Multiple coordinate systems

Expand Down
62 changes: 47 additions & 15 deletions src/99-appendices/08-coordinate-systems.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,53 +47,82 @@ different conventions used in specific software packages developed by different

Generally, across the MEG, EEG, and iEEG modalities, the first two pieces of
information for a coordinate system (origin and orientation) are specified in
`<datatype>CoordinateSystem`.
`<CoordSysType>CoordinateSystem`.
The third piece of information for a coordinate system (units) are specified in
`<datatype>CoordinateUnits`.
Here, `<datatype>` can be one of `MEG`, `EEG`, or `iEEG`, depending on the
modality that is being used.

Allowed values for the `<datatype>CoordinateSystem` field come from a list of
`<CoordSysType>CoordinateUnits`.
Here, `<CoordSysType>` can be one of of the following,
depending on the data that is supposed to be documented:

- `MEG`
- `EEG`
- `iEEG`
- `Fiducials`
- `AnatomicalLandmark`
- `HeadCoil`
- `DigitizedHeadPoints`

Allowed values for the `<CoordSysType>CoordinateSystem` field come from a list of
restricted keywords, as listed in the sections below.

Note that `Fiducials`, `AnatomicalLandmark`, `HeadCoil`, and `DigitizedHeadPoints`
`CoordSysType`s share the restricted keywords with the data modality they are shared with.
For example, if an `AnatomicalLandmark` field is shared as part of an EEG dataset,
the EEG-specific coordinate systems apply.
However, if it is shared as part of an MEG dataset,
the MEG-specific coordinate systems apply.

If no value from the list of restricted keywords fits, there is always the
option to specify the value as follows:

- `Other`: Use this for other coordinate systems and specify further details
in the `<datatype>CoordinateSystemDescription` field
- `Other`: Use this for other coordinate systems and specify all
required details in the `<CoordSysType>CoordinateSystemDescription` field

**If you believe a specific coordinate system should be added to the list
of restricted keywords for MEG, EEG, or iEEG, please open a new issue on the
[bids-standard/bids-specification GitHub repository](https://github.com/bids-standard/bids-specification/issues/new/choose).**

## MEG Specific Coordinate Systems

Restricted keywords for the `<datatype>CoordinateSystem` field in the
Restricted keywords for the `<CoordSysType>CoordinateSystem` field in the
`coordinatesystem.json` file for MEG datasets:

- `CTF`: ALS orientation and the origin between the ears
- `ElektaNeuromag`: RAS orientation and the origin between the ears
- `4DBti`: ALS orientation and the origin between the ears
- `KitYokogawa`: ALS orientation and the origin between the ears
- `ChietiItab`: RAS orientation and the origin between the ears
- Any keyword from the list of [Standard template identifiers](#standard-template-identifiers)

Note that the short descriptions above do not capture all details, There are
detailed extensive descriptions of these EEG coordinate systems on the
detailed extensive descriptions of these coordinate systems on the
[FieldTrip toolbox web page](https://www.fieldtriptoolbox.org/faq/how_are_the_different_head_and_mri_coordinate_systems_defined)

## EEG Specific Coordinate Systems

Restricted keywords for the `<datatype>CoordinateSystem` field in the
Restricted keywords for the `<CoordSysType>CoordinateSystem` field in the
`coordsystem.json` file for EEG datasets:

- `CapTrak`: RAS orientation and the origin between the ears
- Any keyword from the list of [Standard template identifiers](#standard-template-identifiers)

In the case that EEG was recorded simultaneously with MEG,
the restricted keywords for
[MEG specific coordinate systems](#meg-specific-coordinate-systems)
can also be applied to EEG:

- `CTF`
- `ElektaNeuromag`
- `4DBti`
- `KitYokogawa`
- `ChietiItab`

Note that the short descriptions above do not capture all details, There are
detailed extensive descriptions of these EEG coordinate systems on the
detailed extensive descriptions of these coordinate systems on the
[FieldTrip toolbox web page](https://www.fieldtriptoolbox.org/faq/how_are_the_different_head_and_mri_coordinate_systems_defined).

## iEEG Specific Coordinate Systems

Restricted keywords for the `<datatype>CoordinateSystem` field in the
Restricted keywords for the `<CoordSysType>CoordinateSystem` field in the
`coordsystem.json` file for iEEG datasets:

- `Pixels`: If electrodes are localized in 2D space (only x and y are
Expand All @@ -112,14 +141,17 @@ Restricted keywords for the `<datatype>CoordinateSystem` field in the
[ACPC site](https://www.fieldtriptoolbox.org/faq/acpc/) on the FieldTrip
toolbox wiki.

- Any keyword from the list of
[Standard template identifiers](#standard-template-identifiers)

## Image-based Coordinate Systems

The transformation of the real world geometry to an artificial frame of
reference is described in `<datatype>CoordinateSystem`.
reference is described in `<CoordSysType>CoordinateSystem`.
Unless otherwise specified below, the origin is at the AC and the orientation of
the axes is RAS.
Unless specified explicitly in the sidecar file in the
`<datatype>CoordinateUnits` field, the units are assumed to be mm.
`<CoordSysType>CoordinateUnits` field, the units are assumed to be mm.

### Standard template identifiers

Expand Down

0 comments on commit 3b612fb

Please sign in to comment.