From 149d231b8ad358c26daf95f38807bdbda9b04667 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Thu, 28 Jan 2021 12:10:48 +0100 Subject: [PATCH 1/5] harmonize coordsystems --- .../02-magnetoencephalography.md | 7 ++- .../04-intracranial-electroencephalography.md | 17 +++--- src/99-appendices/08-coordinate-systems.md | 58 ++++++++++++++----- 3 files changed, 59 insertions(+), 23 deletions(-) diff --git a/src/04-modality-specific-files/02-magnetoencephalography.md b/src/04-modality-specific-files/02-magnetoencephalography.md index cdaf9e7c08..5da9a27f43 100644 --- a/src/04-modality-specific-files/02-magnetoencephalography.md +++ b/src/04-modality-specific-files/02-magnetoencephalography.md @@ -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. diff --git a/src/04-modality-specific-files/04-intracranial-electroencephalography.md b/src/04-modality-specific-files/04-intracranial-electroencephalography.md index 7ec764021c..b783438245 100644 --- a/src/04-modality-specific-files/04-intracranial-electroencephalography.md +++ b/src/04-modality-specific-files/04-intracranial-electroencephalography.md @@ -395,8 +395,8 @@ 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". | +| 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. . | @@ -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 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 diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md index fc25424ab1..f59460fd26 100644 --- a/src/99-appendices/08-coordinate-systems.md +++ b/src/99-appendices/08-coordinate-systems.md @@ -47,19 +47,35 @@ 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 -`CoordinateSystem`. +`CoordinateSystem`. The third piece of information for a coordinate system (units) are specified in -`CoordinateUnits`. -Here, `` can be one of `MEG`, `EEG`, or `iEEG`, depending on the -modality that is being used. - -Allowed values for the `CoordinateSystem` field come from a list of +`CoordinateUnits`. +Here, `` can be one of of the following, +depending on the data that is supposed to be codumented: + +- `MEG` +- `EEG` +- `iEEG` +- `Fiducials` +- `AnatomicalLandmark` +- `HeadCoil` +- `DigitizedHeadPoints` + +Allowed values for the `CoordinateSystem` field come from a list of restricted keywords, as listed in the sections below. + +Note that `Fiducials`, `AnatomicalLandmark`, `HeadCoil`, and `DigitizedHeadPoints` +`CoordSysTypes` 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 `CoordinateSystemDescription` field +- `Other`: Use this for other coordinate systems and specify all + required details in the `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 @@ -67,7 +83,7 @@ of restricted keywords for MEG, EEG, or iEEG, please open a new issue on the ## MEG Specific Coordinate Systems -Restricted keywords for the `CoordinateSystem` field in the +Restricted keywords for the `CoordinateSystem` field in the `coordinatesystem.json` file for MEG datasets: - `CTF`: ALS orientation and the origin between the ears @@ -75,6 +91,7 @@ Restricted keywords for the `CoordinateSystem` field in the - `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 @@ -82,10 +99,22 @@ detailed extensive descriptions of these EEG coordinate systems on the ## EEG Specific Coordinate Systems -Restricted keywords for the `CoordinateSystem` field in the +Restricted keywords for the `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 @@ -93,7 +122,7 @@ detailed extensive descriptions of these EEG coordinate systems on the ## iEEG Specific Coordinate Systems -Restricted keywords for the `CoordinateSystem` field in the +Restricted keywords for the `CoordinateSystem` field in the `coordsystem.json` file for iEEG datasets: - `Pixels`: If electrodes are localized in 2D space (only x and y are @@ -112,14 +141,17 @@ Restricted keywords for the `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 `CoordinateSystem`. +reference is described in `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 -`CoordinateUnits` field, the units are assumed to be mm. +`CoordinateUnits` field, the units are assumed to be mm. ### Standard template identifiers From e7c010e0a677cba2f427ce1314c4719dc4b00e78 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Thu, 28 Jan 2021 12:20:14 +0100 Subject: [PATCH 2/5] fix table pipe --- .../04-intracranial-electroencephalography.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/04-modality-specific-files/04-intracranial-electroencephalography.md b/src/04-modality-specific-files/04-intracranial-electroencephalography.md index b783438245..5773991cfe 100644 --- a/src/04-modality-specific-files/04-intracranial-electroencephalography.md +++ b/src/04-modality-specific-files/04-intracranial-electroencephalography.md @@ -393,13 +393,13 @@ General fields: Fields relating to the iEEG electrode positions: -| **Key name** | **Requirement level** | **Data type** | **Description** | -| ----------------------------------- | -------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **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. . | +| 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 From b22e05a9bfa25c4b407432c5be2c9f7156ac7da2 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Thu, 28 Jan 2021 12:34:00 +0100 Subject: [PATCH 3/5] remove two typos --- src/99-appendices/08-coordinate-systems.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md index f59460fd26..798eb653da 100644 --- a/src/99-appendices/08-coordinate-systems.md +++ b/src/99-appendices/08-coordinate-systems.md @@ -94,7 +94,7 @@ Restricted keywords for the `CoordinateSystem` field in the - 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 @@ -117,7 +117,7 @@ can also be applied to EEG: - `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 From 862dc7e10e081280d68ae321dc83a746b882a814 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Thu, 28 Jan 2021 18:06:46 +0100 Subject: [PATCH 4/5] fix typo --- src/99-appendices/08-coordinate-systems.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md index 798eb653da..7ed394060a 100644 --- a/src/99-appendices/08-coordinate-systems.md +++ b/src/99-appendices/08-coordinate-systems.md @@ -51,7 +51,7 @@ information for a coordinate system (origin and orientation) are specified in The third piece of information for a coordinate system (units) are specified in `CoordinateUnits`. Here, `` can be one of of the following, -depending on the data that is supposed to be codumented: +depending on the data that is supposed to be documented: - `MEG` - `EEG` From 322cc7246312e977bd60955ff3b4bbcbbb2a671f Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Fri, 29 Jan 2021 17:58:49 +0100 Subject: [PATCH 5/5] text clarifications Co-authored-by: Taylor Salo --- .../04-intracranial-electroencephalography.md | 2 +- src/99-appendices/08-coordinate-systems.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/04-modality-specific-files/04-intracranial-electroencephalography.md b/src/04-modality-specific-files/04-intracranial-electroencephalography.md index 5773991cfe..67ebf6f02d 100644 --- a/src/04-modality-specific-files/04-intracranial-electroencephalography.md +++ b/src/04-modality-specific-files/04-intracranial-electroencephalography.md @@ -415,7 +415,7 @@ 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 capitalization). +(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. diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md index 7ed394060a..2c67c11a74 100644 --- a/src/99-appendices/08-coordinate-systems.md +++ b/src/99-appendices/08-coordinate-systems.md @@ -65,7 +65,7 @@ Allowed values for the `CoordinateSystem` field come from a list o restricted keywords, as listed in the sections below. Note that `Fiducials`, `AnatomicalLandmark`, `HeadCoil`, and `DigitizedHeadPoints` -`CoordSysTypes` share the restricted keywords with the data modality they are shared with. +`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,