From ef4a939cf297cdbd8441992abd796d0a3a45967e Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Tue, 20 Aug 2024 09:10:57 -0400 Subject: [PATCH] feat(schema): Move coordsystem.json rules out of rules.sidecars (#1892) * feat(schema): Move coordsystem.json rules out of rules.sidecars * feat: Add make_json_table macro * feat(spec): Render coordsystem JSON tables * feat(metaschema): Add schema.rules.json --- src/metaschema.json | 13 +- .../electroencephalography.md | 8 +- .../intracranial-electroencephalography.md | 4 +- .../magnetoencephalography.md | 12 +- .../near-infrared-spectroscopy.md | 8 +- src/schema/rules/json/eeg.yaml | 91 +++++++++++ src/schema/rules/json/ieeg.yaml | 50 +++++++ src/schema/rules/json/meg.yaml | 141 ++++++++++++++++++ src/schema/rules/json/nirs.yaml | 93 ++++++++++++ src/schema/rules/sidecars/eeg.yaml | 85 ----------- src/schema/rules/sidecars/ieeg.yaml | 44 ------ src/schema/rules/sidecars/meg.yaml | 136 ----------------- src/schema/rules/sidecars/nirs.yaml | 93 ------------ tools/mkdocs_macros_bids/macros.py | 25 ++++ tools/mkdocs_macros_bids/main.py | 1 + .../bidsschematools/render/__init__.py | 2 + .../bidsschematools/render/tables.py | 43 +++++- 17 files changed, 470 insertions(+), 379 deletions(-) create mode 100644 src/schema/rules/json/eeg.yaml create mode 100644 src/schema/rules/json/ieeg.yaml create mode 100644 src/schema/rules/json/meg.yaml create mode 100644 src/schema/rules/json/nirs.yaml diff --git a/src/metaschema.json b/src/metaschema.json index f6e5a62d25..7df2856177 100644 --- a/src/metaschema.json +++ b/src/metaschema.json @@ -386,19 +386,25 @@ "required": ["common", "deriv", "raw"], "additionalProperties": false }, + "json": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/json" + } + }, "sidecars": { "type": "object", "patternProperties": { "^derivatives$": { "type": "object", "properties": { - "common_derivatives": { "$ref": "#/definitions/sidecar" } + "common_derivatives": { "$ref": "#/definitions/json" } }, "required": ["common_derivatives"], "additionalProperties": false }, "^(?!derivatives$)[a-z_]+$": { - "$ref": "#/definitions/sidecar" + "$ref": "#/definitions/json" }, "additionalProperties": false }, @@ -476,6 +482,7 @@ "required": [ "entities", "files", + "json", "sidecars", "tabular_data", "common_principles", @@ -586,7 +593,7 @@ } } }, - "sidecar": { + "json": { "type": "object", "patternProperties": { "^[a-zA-Z0-9_]+$": { diff --git a/src/modality-specific-files/electroencephalography.md b/src/modality-specific-files/electroencephalography.md index 8a584bb7a0..782012f3ea 100644 --- a/src/modality-specific-files/electroencephalography.md +++ b/src/modality-specific-files/electroencephalography.md @@ -390,7 +390,7 @@ The definitions of the fields specified in these tables may be found in A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table("eeg.EEGCoordsystemGeneral") }} +{{ MACROS___make_json_table("json.eeg.EEGCoordsystemGeneral") }} Fields relating to the EEG electrode positions: @@ -402,7 +402,7 @@ The definitions of the fields specified in these tables may be found in A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table("eeg.EEGCoordsystemPositions") }} +{{ MACROS___make_json_table("json.eeg.EEGCoordsystemPositions") }} Fields relating to the position of fiducials measured during an EEG session/run: @@ -414,7 +414,7 @@ The definitions of the fields specified in these tables may be found in A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table("eeg.EEGCoordsystemFiducials") }} +{{ MACROS___make_json_table("json.eeg.EEGCoordsystemFiducials") }} Fields relating to the position of anatomical landmark measured during an EEG session/run: @@ -426,7 +426,7 @@ The definitions of the fields specified in these tables may be found in A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table(["eeg.EEGCoordsystemLandmark", "eeg.EEGCoordsystemLandmarkDescriptionRec"]) }} +{{ MACROS___make_json_table(["json.eeg.EEGCoordsystemLandmark", "json.eeg.EEGCoordsystemLandmarkDescriptionRec"]) }} If the position of anatomical landmarks is measured using the same system or device used to measure electrode positions, and if thereby the anatomical diff --git a/src/modality-specific-files/intracranial-electroencephalography.md b/src/modality-specific-files/intracranial-electroencephalography.md index 096b96f97d..dc15d9f92d 100644 --- a/src/modality-specific-files/intracranial-electroencephalography.md +++ b/src/modality-specific-files/intracranial-electroencephalography.md @@ -389,7 +389,7 @@ The definitions of the fields specified in these tables may be found in A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table("ieeg.iEEGCoordsystemGeneral") }} +{{ MACROS___make_json_table("json.ieeg.iEEGCoordsystemGeneral") }} Fields relating to the iEEG electrode positions: @@ -401,7 +401,7 @@ The definitions of the fields specified in these tables may be found in A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table("ieeg.iEEGCoordsystemPositions") }} +{{ MACROS___make_json_table("json.ieeg.iEEGCoordsystemPositions") }} ### Recommended 3D coordinate systems diff --git a/src/modality-specific-files/magnetoencephalography.md b/src/modality-specific-files/magnetoencephalography.md index c3896a908e..babc92be7c 100644 --- a/src/modality-specific-files/magnetoencephalography.md +++ b/src/modality-specific-files/magnetoencephalography.md @@ -343,7 +343,7 @@ The definitions of the fields specified in these tables may be found in A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table("meg.MEGCoordsystemWithEEG") }} +{{ MACROS___make_json_table("json.meg.MEGCoordsystemWithEEG") }} Head localization coils: @@ -355,7 +355,7 @@ The definitions of the fields specified in these tables may be found in A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table("meg.MEGCoordsystemHeadLocalizationCoils") }} +{{ MACROS___make_json_table("json.meg.MEGCoordsystemHeadLocalizationCoils") }} Digitized head points: @@ -367,7 +367,7 @@ The definitions of the fields specified in these tables may be found in A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table("meg.MEGCoordsystemDigitizedHeadPoints") }} +{{ MACROS___make_json_table("json.meg.MEGCoordsystemDigitizedHeadPoints") }} Anatomical MRI: @@ -379,7 +379,7 @@ The definitions of the fields specified in these tables may be found in A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table("meg.MEGCoordsystemAnatomicalMRI") }} +{{ MACROS___make_json_table("json.meg.MEGCoordsystemAnatomicalMRI") }} Anatomical landmarks: @@ -391,7 +391,7 @@ The definitions of the fields specified in these tables may be found in A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table("meg.MEGCoordsystemAnatomicalLandmarks") }} +{{ MACROS___make_json_table("json.meg.MEGCoordsystemAnatomicalLandmarks") }} 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 @@ -419,7 +419,7 @@ The definitions of the fields specified in these tables may be found in A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table("meg.MEGCoordsystemFiducialsInformation") }} +{{ MACROS___make_json_table("json.meg.MEGCoordsystemFiducialsInformation") }} For more information on the definition of anatomical landmarks, please visit: [How are the Left and Right Pre-Auricular (LPA and RPA) points defined? - FieldTrip Toolbox](https://www.fieldtriptoolbox.org/faq/how_are_the_lpa_and_rpa_points_defined/) diff --git a/src/modality-specific-files/near-infrared-spectroscopy.md b/src/modality-specific-files/near-infrared-spectroscopy.md index 7382560a43..b423b4c2dd 100644 --- a/src/modality-specific-files/near-infrared-spectroscopy.md +++ b/src/modality-specific-files/near-infrared-spectroscopy.md @@ -386,7 +386,7 @@ A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table("nirs.CoordsystemGeneral") }} +{{ MACROS___make_json_table("json.nirs.CoordsystemGeneral") }} Fields relating to the NIRS optode positions: @@ -399,7 +399,7 @@ A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table(["nirs.CoordinateSystem", "nirs.CoordinateSystemDescriptionRec"]) }} +{{ MACROS___make_json_table(["json.nirs.CoordinateSystem", "json.nirs.CoordinateSystemDescriptionRec"]) }} Fields relating to the position of fiducials measured during an NIRS session/run: @@ -412,7 +412,7 @@ A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table(["nirs.Fiducials", "nirs.FiducialsCoordinateSystemDescriptionRec"]) }} +{{ MACROS___make_json_table(["json.nirs.Fiducials", "json.nirs.FiducialsCoordinateSystemDescriptionRec"]) }} Fields relating to the position of anatomical landmarks measured during an NIRS session/run: @@ -425,7 +425,7 @@ A guide for using macros can be found at https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md --> -{{ MACROS___make_sidecar_table(["nirs.AnatomicalLandmark", "nirs.AnatomicalLandmarkCoordinateSystemDescriptionRec"]) }} +{{ MACROS___make_json_table(["json.nirs.AnatomicalLandmark", "json.nirs.AnatomicalLandmarkCoordinateSystemDescriptionRec"]) }} ### Example `*_coordsystem.json` diff --git a/src/schema/rules/json/eeg.yaml b/src/schema/rules/json/eeg.yaml new file mode 100644 index 0000000000..f42956671f --- /dev/null +++ b/src/schema/rules/json/eeg.yaml @@ -0,0 +1,91 @@ +# +# Groups of related metadata fields +# +# Assumptions: never need disjunction of selectors +# Assumptions: top-to-bottom overrides is sufficient logic + +--- +# General fields +EEGCoordsystemGeneral: + selectors: + - datatype == "eeg" + - suffix == "coordsystem" + fields: + IntendedFor: + level: optional + description_addendum: | + This identifies the MRI or CT scan associated with the electrodes, + landmarks, and fiducials. + +# Fields relating to the EEG electrode positions +EEGCoordsystemPositions: + selectors: + - datatype == "eeg" + - suffix == "coordsystem" + fields: + EEGCoordinateSystem: required + EEGCoordinateUnits: required + EEGCoordinateSystemDescription: + level: recommended + level_addendum: required if `EEGCoordinateSystem` is `"Other"` + +EEGCoordsystemOther: + selectors: + - datatype == "eeg" + - suffix == "coordsystem" + - '"EEGCoordinateSystem" in json' + - json.EEGCoordinateSystem == "Other" + fields: + EEGCoordinateSystemDescription: required + +# Fields relating to the position of fiducials measured during an EEG session/run +EEGCoordsystemFiducials: + selectors: + - datatype == "eeg" + - suffix == "coordsystem" + fields: + FiducialsDescription: optional + FiducialsCoordinates: recommended + FiducialsCoordinateSystem: recommended + FiducialsCoordinateUnits: recommended + FiducialsCoordinateSystemDescription: + level: recommended + level_addendum: required if `FiducialsCoordinateSystem` is `"Other"` + +EEGCoordsystemOtherFiducialCoordinateSystem: + selectors: + - datatype == "eeg" + - suffix == "coordsystem" + - json.FiducialsCoordinateSystem == "Other" + fields: + FiducialsCoordinateSystemDescription: required + +# Fields relating to the position of anatomical landmark measured during an EEG session/run +EEGCoordsystemLandmark: + selectors: + - datatype == "eeg" + - suffix == "coordsystem" + fields: + AnatomicalLandmarkCoordinates: recommended + AnatomicalLandmarkCoordinateSystem: + level: recommended + description_addendum: Preferably the same as the `EEGCoordinateSystem`. + AnatomicalLandmarkCoordinateUnits: recommended + +EEGCoordsystemLandmarkDescriptionRec: + selectors: + - datatype == "eeg" + - suffix == "coordsystem" + - json.AnatomicalLandmarkCoordinateSystem != "Other" + fields: + AnatomicalLandmarkCoordinateSystemDescription: + level: recommended + level_addendum: required if `AnatomicalLandmarkCoordinateSystem` is `"Other"` + +EEGCoordsystemLandmarkDescriptionReq: + selectors: + - datatype == "eeg" + - suffix == "coordsystem" + - json.AnatomicalLandmarkCoordinateSystem == "Other" + fields: + AnatomicalLandmarkCoordinateSystemDescription: required diff --git a/src/schema/rules/json/ieeg.yaml b/src/schema/rules/json/ieeg.yaml new file mode 100644 index 0000000000..4271cfe952 --- /dev/null +++ b/src/schema/rules/json/ieeg.yaml @@ -0,0 +1,50 @@ +# +# Groups of related metadata fields +# +# Assumptions: never need disjunction of selectors +# Assumptions: top-to-bottom overrides is sufficient logic + +--- +# General fields +iEEGCoordsystemGeneral: + selectors: + - datatype == "ieeg" + - suffix == "coordsystem" + fields: + IntendedFor__ds_relative: + level: optional + description_addendum: | + If only a surface reconstruction is available, this should point to + the surface reconstruction file. + Note that this file should have the same coordinate system + specified in `iEEGCoordinateSystem`. + For example, **T1**: `'bids::sub-