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

[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 4 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
158 changes: 114 additions & 44 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 @@ -165,16 +165,21 @@ whenever possible. See also

## Anatomy imaging data

<!--
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"]) }}
Anatomy MRI sequences measure static, structural features of the brain.

This datatype is divided into two groups:
non-parametric and parametric.

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.

Currently supported non-parametric structural MR images include:
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

Currently supported non-parametric structural MR images include the following:
Remi-Gau marked this conversation as resolved.
Show resolved Hide resolved

<!--
This block generates a suffix table.
Expand All @@ -199,40 +204,26 @@ 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
<!--
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_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") }}
{{ MACROS___make_filename_template("raw", datatypes=["anat"], suffixes=[
"T1w",
"T2w",
"PDw",
"T2starw",
"FLAIR",
"inplaneT1",
"inplaneT2",
"PDT2",
"UNIT1",
"angio",
])
}}

The [`part-<label>`](../appendices/entities.md#part) entity is
used to indicate which component of the complex representation of the MRI
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,9 +266,7 @@ 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:
Expand Down Expand Up @@ -312,6 +302,35 @@ and a guide for using macros can be found at
)
}}

<!--
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",
])
}}

Parametric images listed in the table above are typically generated by
processing a [file collection](../common-principles.md#entity-linked-file-collections).
Please visit the [file collections appendix](../appendices/file-collections.md) to see the
Expand All @@ -322,6 +341,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