Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[FIX] reorganize anat filename templates #1419

Merged
merged 7 commits into from
Mar 6, 2023
Merged

[FIX] reorganize anat filename templates #1419

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3793281
split anat filename templates into parametric, non parametric, deface…
Remi-Gau Feb 14, 2023
1cfe60b
Apply suggestions from code review
Remi-Gau Feb 20, 2023
08e8d04
rm reconstruction definition
Remi-Gau Feb 20, 2023
859d865
move defacing and task sections
Remi-Gau Feb 20, 2023
7576eed
rename heading and metadata group
Remi-Gau Feb 24, 2023
6e7df7b
move institution information up
Remi-Gau Feb 24, 2023
268dc7b
move filename template
Remi-Gau Feb 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions src/appendices/qmri.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,49 @@ representing acquisition parameters (`echo`, `flip`, `inv`, `mt`) or file parts

If a qMRI file collection is intended for creating structural quantitative maps (for example, `T1map`),
files belonging to that collection are stored in the `anat` subdirectory.

List of currently supported collections:

<!--
This block generates a suffix table.
The definitions of these fields can be found in
src/schema/rules/files/raw
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_suffix_table(
[
"MESE",
"MEGRE",
"VFA",
"IRT1",
"MP2RAGE",
"MPM",
"MTS",
"MTR",
]
)
}}

<!--
This block generates a filename templates.
The inputs for this macro can be found in the directory
src/schema/rules/files/raw
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_filename_template("raw", datatypes=["anat"], suffixes=[
"MESE",
"MEGRE",
"VFA",
"IRT1",
"MP2RAGE",
"MPM",
"MTS",
"MTR",
])
}}

Below is an example file collection for `MP2RAGE`:

<!-- This block generates a file tree.
Expand Down Expand Up @@ -193,6 +236,28 @@ Explanation of the table:

#### Field maps

<!--
This block generates a suffix table.
The definitions of these fields can be found in
src/schema/rules/files/raw
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_suffix_table(
[
"TB1DAM",
"TB1EPI",
"TB1AFI",
"TB1TFL",
"TB1RFM",
"RB1COR",
"TB1SRGE",
"TB1map",
"RB1map",
]
)
}}

<!--
This block generates a filename templates.
The inputs for this macro can be found in the directory
Expand Down
190 changes: 131 additions & 59 deletions src/modality-specific-files/magnetic-resonance-imaging-data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,12 @@ MRI acquisition parameters are divided into several categories based on
[checklist](https://winnower-production.s3.amazonaws.com/papers/977/assets/993e199d-6bc3-4418-be3a-f620af1188b7-Parameter_Reporting_V1p3.pdf))
by Ben Inglis.

### Scanner Hardware
When adding additional metadata please use the CamelCase version of
[DICOM ontology terms](https://scicrunch.org/scicrunch/interlex/dashboard)
whenever possible. See also
[recommendations on JSON files](../common-principles.md#keyvalue-files-dictionaries).

### Hardware information

<!-- This block generates a metadata table.
These tables are defined in
Expand All @@ -20,7 +25,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("mri.MRIScannerHardware") }}
{{ MACROS___make_sidecar_table("mri.MRIHardware") }}

Example for `ReceiveCoilActiveElements`:

Expand All @@ -37,6 +42,18 @@ it is preferable for this field to be populated directly from the DICOM
for each individual scan, so that it can be used as a mechanism for checking
that a given scan was collected with the intended coil elements selected.

### Institution information

<!-- This block generates a metadata table.
These tables are defined in
src/schema/rules/sidecars
The definitions of the fields specified in these tables may be found in
src/schema/objects/metadata.yaml
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("mri.MRIInstitutionInformation") }}

### Sequence Specifics

<!-- This block generates a metadata table.
Expand Down Expand Up @@ -146,24 +163,21 @@ A guide for using macros can be found at
-->
{{ MACROS___make_sidecar_table("mri.MRIEchoPlanarImagingAndB0Mapping") }}

### Institution information
## Anatomy imaging data

<!-- This block generates a metadata table.
These tables are defined in
src/schema/rules/sidecars
The definitions of the fields specified in these tables may be found in
src/schema/objects/metadata.yaml
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("mri.MRIInstitutionInformation") }}
Anatomy MRI sequences measure static, structural features of the brain.

When adding additional metadata please use the CamelCase version of
[DICOM ontology terms](https://scicrunch.org/scicrunch/interlex/dashboard)
whenever possible. See also
[recommendations on JSON files](../common-principles.md#keyvalue-files-dictionaries).
This datatype is divided into two groups:
non-parametric and parametric.

## Anatomy imaging data
Non-parametric structural images have an arbitrary scale.
For example, T1w data are T1-weighted,
but the values do not correspond to actual T1 value estimates.

Parametric structural imaging, on the other hand, use a non-arbitrary scale.
For example, a T1map file contains T1 value estimates, in seconds.

### Non-parametric structural MR images

<!--
This block generates a filename templates.
Expand All @@ -172,9 +186,21 @@ The inputs for this macro can be found in the directory
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_filename_template("raw", datatypes=["anat"]) }}
{{ MACROS___make_filename_template("raw", datatypes=["anat"], suffixes=[
"T1w",
"T2w",
"PDw",
"T2starw",
"FLAIR",
"inplaneT1",
"inplaneT2",
"PDT2",
"UNIT1",
"angio",
])
}}

Currently supported non-parametric structural MR images include:
Currently supported non-parametric structural MR images include the following:

<!--
This block generates a suffix table.
Expand All @@ -199,41 +225,6 @@ and a guide for using macros can be found at
)
}}

If the structural images included in the dataset were defaced (to protect
identity of participants) one MAY provide the binary mask that was used to
remove facial features in the form of `_defacemask` files.
In such cases, the OPTIONAL [`mod-<label>`](../appendices/entities.md#mod)
entity corresponds to modality suffix,
such as `T1w` or `inplaneT1`, referenced by the defacemask image.
For example, `sub-01_mod-T1w_defacemask.nii.gz`.

The OPTIONAL [`task-<label>`](../appendices/entities.md#task) entity can be used
in order to allow tasks during structural MR acquisitions,
for example pre-described motion paradigms such as nodding, to be described.

<!-- This block generates a metadata table.
The definitions of these fields can be found in
src/schema/objects/metadata.yaml
and 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("anat.TaskMetadata") }}

Some meta information about the acquisition MAY be provided in an additional
JSON file. See [Common metadata fields](#common-metadata-fields) for a
list of terms and their definitions. There are also some OPTIONAL JSON
fields specific to anatomical scans:

<!-- This block generates a metadata table.
These tables are defined in
src/schema/rules/sidecars
The definitions of the fields specified in these tables may be found in
src/schema/objects/metadata.yaml
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("anat.MRIAnatomyCommonMetadataFields") }}

The [`part-<label>`](../appendices/entities.md#part) entity is
used to indicate which component of the complex representation of the MRI
signal is represented in voxel data.
Expand All @@ -258,7 +249,8 @@ A guide for using macros can be found at
},
}
}
) }}
)
}}

Phase images MAY be in radians or in arbitrary units.
The sidecar JSON file MUST include the units of the `phase` image.
Expand All @@ -274,12 +266,41 @@ For example, for `sub-01_part-phase_T1w.json`:

When there is only a magnitude image of a given type, the `part` entity MAY be omitted.

Similarly, the OPTIONAL [`rec-<label>`](../appendices/entities.md#rec)
entity can be used to distinguish
different reconstruction algorithms (for example ones using motion correction).
### Parametric structural MR images

Structural MR images whose intensity is represented in a non-arbitrary scale
constitute parametric maps. Currently supported parametric maps include:
constitute parametric maps.

<!--
This block generates a filename templates.
The inputs for this macro can be found in the directory
src/schema/rules/files/raw
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_filename_template("raw", datatypes=["anat"], suffixes=[
"T1map",
"R1map",
"T2map",
"R2map",
"T2starmap",
"R2starmap",
"PDmap",
"MTRmap",
"MTsat",
"T1rho",
"MWFmap",
"MTVmap",
"PDT2map",
"Chimap",
"TB1map",
"RB1map",
"S0map",
"M0map",
])
}}

Currently supported parametric maps include:

<!--
This block generates a suffix table.
Expand Down Expand Up @@ -322,6 +343,57 @@ recommended metadata fields, and the application specific entity or
metadata requirement levels of [file collections](../appendices/file-collections.md) that can generate
them, visit the [qMRI appendix](../appendices/qmri.md).

### Defacing masks

If the structural images included in the dataset were defaced (to protect
identity of participants) one MAY provide the binary mask that was used to
remove facial features in the form of `_defacemask` files.
In such cases, the OPTIONAL [`mod-<label>`](../appendices/entities.md#mod)
entity corresponds to modality suffix,
such as `T1w` or `inplaneT1`, referenced by the defacemask image.
For example, `sub-01_mod-T1w_defacemask.nii.gz`.

<!--
This block generates a filename templates.
The inputs for this macro can be found in the directory
src/schema/rules/files/raw
and a guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_filename_template("raw", datatypes=["anat"], suffixes=[
"defacemask",
])
}}

### Task metadata for anatomical scans

The OPTIONAL [`task-<label>`](../appendices/entities.md#task) entity can be used
in order to allow tasks during structural MR acquisitions,
for example pre-described motion paradigms such as nodding, to be described.

<!-- This block generates a metadata table.
The definitions of these fields can be found in
src/schema/objects/metadata.yaml
and 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("anat.TaskMetadata") }}

Some meta information about the acquisition MAY be provided in an additional
JSON file. See [Common metadata fields](#common-metadata-fields) for a
list of terms and their definitions. There are also some OPTIONAL JSON
fields specific to anatomical scans:

<!-- This block generates a metadata table.
These tables are defined in
src/schema/rules/sidecars
The definitions of the fields specified in these tables may be found in
src/schema/objects/metadata.yaml
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("anat.MRIAnatomyCommonMetadataFields") }}

### Deprecated suffixes

Some suffixes that were available in versions of the specification prior to
Expand Down
2 changes: 1 addition & 1 deletion src/schema/rules/sidecars/mri.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

---
# MRI Common metadata fields
MRIScannerHardware:
MRIHardware:
selectors:
- modality == "mri"
fields:
Expand Down