Skip to content

Commit 429a107

Browse files
effigieseffigies
authored
Merge pull request #2183 from tsalo/fieldmap-organization
[ENH] Expand fieldmaps section to include B1 maps, including qMRI maps
2 parents 5e68e07 + 33996c3 commit 429a107

File tree

2 files changed

+278
-250
lines changed

2 files changed

+278
-250
lines changed

‎src/appendices/qmri.md‎

Lines changed: 0 additions & 239 deletions
Original file line numberDiff line numberDiff line change
@@ -252,65 +252,6 @@ Explanation of the table:
252252
See [deriving the intended qMRI application from an ambiguous file collection](#deriving-the-intended-qmri-application-from-an-ambiguous-file-collection)
253253
for details.
254254

255-
#### Field maps
256-
257-
<!--
258-
This block generates a suffix table.
259-
The definitions of these fields can be found in
260-
src/schema/rules/files/raw
261-
and a guide for using macros can be found at
262-
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
263-
-->
264-
{{ MACROS___make_suffix_table(
265-
[
266-
"TB1DAM",
267-
"TB1EPI",
268-
"TB1AFI",
269-
"TB1TFL",
270-
"TB1RFM",
271-
"RB1COR",
272-
"TB1SRGE",
273-
"TB1map",
274-
"RB1map",
275-
]
276-
)
277-
}}
278-
279-
<!--
280-
This block generates a filename templates.
281-
The inputs for this macro can be found in the directory
282-
src/schema/rules/files/raw
283-
and a guide for using macros can be found at
284-
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
285-
-->
286-
{{ MACROS___make_filename_template(
287-
"raw",
288-
datatypes=["fmap"],
289-
suffixes=[
290-
"TB1DAM",
291-
"TB1EPI",
292-
"TB1AFI",
293-
"TB1TFL",
294-
"TB1RFM",
295-
"RB1COR",
296-
"TB1SRGE",
297-
"TB1map",
298-
"RB1map",
299-
])
300-
}}
301-
302-
| **File collection** | **REQUIRED metadata** |
303-
| -------------------- | ---------------------------------------------------------------------------------------------------- |
304-
| TB1DAM | `FlipAngle` |
305-
| TB1EPI | `EchoTime`, `FlipAngle`, `TotalReadoutTime`, `MixingTime` |
306-
| TB1AFI | `RepetitionTimeExcitation` |
307-
| TB1TFL | |
308-
| TB1RFM | |
309-
| TB1SRGE<sup>\*</sup> | `FlipAngle`, `InversionTime`, `RepetitionTimeExcitation`, `RepetitionTimePreperation`, `NumberShots` |
310-
| RB1COR | |
311-
312-
<sup>\*</sup> Please see TB1SRGE-specific notes for the calculation of `NumberShots`.
313-
314255
### Metadata requirements for qMRI maps
315256

316257
As qMRI maps are stored as derivatives, they are subjected to the metadata requirements of
@@ -584,183 +525,3 @@ When not accessible, `2 X EchoTime` can be used as a surrogate.
584525

585526
Further information about other `MP2RAGE` qMRI protocol fields can be found in the
586527
[qMRLab documentation](https://qmrlab.readthedocs.io/en/master/protocols.html#mp2rage).
587-
588-
#### `TB1SRGE` specific notes
589-
590-
Calculation of `before` and `after` entries for `NumberShots` metadata field of `TB1SRGE` is more involved than that of `MP2RAGE`.
591-
The formula can be found in a
592-
[reference implementation](https://github.com/JosePMarques/MP2RAGE-related-scripts/blob/a405df30ac2c617d29d8b1b16025aaa911e86370/DemoForR1Correction.m#L17),
593-
which requires information about `BaseResolution` (that is, image matrix size in PE direction),
594-
partial Fourier fraction in the PE direction, number of reference lines for parallel imaging acceleration,
595-
and the parallel imaging acceleration factor in PE direction.
596-
597-
### Radiofrequency (RF) field mapping
598-
599-
Some RF file collections call for the use of special notations that cannot be resolved by
600-
by entities that can generalize to other applications.
601-
Instead of introducing an entity that is exclusive to a single application,
602-
method developers who commonly use these file collections for the `MPM` application reached
603-
the consensus on the use of `acq` entity to distinguish individual files.
604-
These suffixes include: `TB1AFI`, `TB1TFL`, `TB1RFM`, and `RB1COR`.
605-
606-
#### `TB1EPI` specific notes
607-
608-
The `flip` and `echo` entities MUST be used to distinguish images with this suffix.
609-
The use of `flip` follows the default convention. However, this suffix defines a
610-
specific use case for the `echo` entity:
611-
612-
| **`echo-1`** | **`echo-2`** |
613-
| -------------------- | --------------------------- |
614-
| Lower `EchoTime` | Higher `EchoTime` |
615-
| Spin Echo (SE) image | Stimulated Echo (STE) image |
616-
617-
At each `FlipAngle`, the `TB1EPI` suffix lists two images acquired at two echo times.
618-
The first echo is a spin echo (SE) formed by the pulses alpha-2alpha. However, the
619-
second echo in this method is generated in a different fashion compared to a typical
620-
MESE acquisition. The second echo is a stimulated echo (STE) that is formed by an
621-
additional alpha pulse (that is, alpha-2alpha-alpha).
622-
623-
The `FlipAngle` value corresponds to the nominal flip angle value of the STE pulse.
624-
The nominal FA value of the SE pulse is twice this value.
625-
626-
Note that the following metadata fields MUST be defined in the accompanying JSON
627-
files:
628-
629-
<!-- This block generates a metadata table.
630-
These tables are defined in
631-
src/schema/rules/sidecars
632-
The definitions of the fields specified in these tables may be found in
633-
src/schema/objects/metadata.yaml
634-
A guide for using macros can be found at
635-
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
636-
-->
637-
{{ MACROS___make_sidecar_table("fmap.TB1EPI") }}
638-
639-
To properly identify constituents of this particular method, values of the `echo`
640-
entity MUST index the images as follows:
641-
642-
<!-- This block generates a file tree.
643-
A guide for using macros can be found at
644-
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
645-
-->
646-
{{ MACROS___make_filetree_example(
647-
{
648-
"sub-01": {
649-
"fmap": {
650-
"sub-01_echo-1_flip-1_TB1EPI.nii.gz": "# SE",
651-
"sub-01_echo-1_flip-1_TB1EPI.json": "",
652-
"sub-01_echo-2_flip-1_TB1EPI.nii.gz": "# STE",
653-
"sub-01_echo-2_flip-1_TB1EPI.json": "",
654-
"sub-01_echo-1_flip-2_TB1EPI.nii.gz": "# SE",
655-
"sub-01_echo-1_flip_2_TB1EPI.json": "",
656-
"sub-01_echo-2_flip-2_TB1EPI.nii.gz": "# STE",
657-
"sub-01_echo-2_flip-2_TB1EPI.json": "",
658-
},
659-
},
660-
}
661-
) }}
662-
663-
#### `TB1AFI` specific notes
664-
665-
This method calculates a B1<sup>+</sup> map from two images acquired at two interleaved excitation repetition times (TR).
666-
Note that there is no entity for the TR that can be used to label the files corresponding to the two
667-
repetition times and the definition of repetition time depends on the modality
668-
(`functional` or `anatomical`) in the specification.
669-
670-
Therefore, to properly identify constituents of this particular method,
671-
values of the `acq` entity SHOULD begin with either `tr1` (lower TR) or `tr2` (higher TR)
672-
and MAY be followed by freeform entries:
673-
674-
| **First `TR`** | **Second `TR`** | **Use case** |
675-
| ---------------- | ---------------- | -------------------- |
676-
| `_acq-tr1` | `_acq-tr2` | Single acquisition |
677-
| `_acq-tr1Test` | `_acq-tr2Test` | Acquisition `Test` |
678-
| `_acq-tr1Retest` | `_acq-tr2Retest` | Acquisition `Retest` |
679-
680-
<!-- This block generates a file tree.
681-
A guide for using macros can be found at
682-
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
683-
-->
684-
{{ MACROS___make_filetree_example(
685-
{
686-
"sub-01": {
687-
"fmap": {
688-
"sub-01_acq-tr1_TB1AFI.nii.gz": "",
689-
"sub-01_acq-tr1_TB1AFI.json": "",
690-
"sub-01_acq-tr2_TB1AFI.nii.gz": "",
691-
"sub-01_acq-tr2_TB1AFI.json": "",
692-
},
693-
},
694-
}
695-
) }}
696-
697-
#### `TB1TFL` and `TB1RFM` specific notes
698-
699-
These suffixes describe two outputs generated by Siemens `tfl_b1_map` and `rf_map` product sequences, respectively.
700-
Both sequences output two images.
701-
The first image appears like an anatomical image and the second output is a scaled flip angle map.
702-
703-
To properly identify files of this particular file collection,
704-
values of the `acq` entity SHOULD begin with either `anat` or `famp` and MAY be followed by freeform entries:
705-
706-
| **Anatomical (like) image** | **Scaled flip angle map** | **Use case** |
707-
| --------------------------- | ------------------------- | -------------------- |
708-
| `_acq-anat` | `_acq-famp` | Single acquisition |
709-
| `_acq-anatTest` | `_acq-fampTest` | Acquisition `Test` |
710-
| `_acq-anatRetest` | `_acq-fampRetest` | Acquisition `Retest` |
711-
712-
<!-- This block generates a file tree.
713-
A guide for using macros can be found at
714-
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
715-
-->
716-
{{ MACROS___make_filetree_example(
717-
{
718-
"sub-01": {
719-
"fmap": {
720-
"sub-01_acq-anat_TB1TFL.nii.gz": "",
721-
"sub-01_acq-anat_TB1TFL.json": "",
722-
"sub-01_acq-famp_TB1TFL.nii.gz": "",
723-
"sub-01_acq-famp_TB1TFL.json": "",
724-
},
725-
},
726-
}
727-
) }}
728-
729-
The example above applies to the `TB1RFM` suffix as well.
730-
731-
#### `RB1COR` specific notes
732-
733-
This method generates a receive sensitivity map by combining two low resolution images
734-
collected sequentially by two different RF coils in receive mode (the body and the head coil)
735-
with otherwise identical acquisition parameters.
736-
To correct for dynamic changes in the receive sensitivity over time due to, for example,
737-
subject motion, separate receive sensitivity maps may be acquired for each anatomical
738-
acquisition in a file collection.
739-
740-
To properly identify constituents of this particular method, values of the `acq`
741-
entity SHOULD begin with either `body` or `head` and MAY be followed by freeform
742-
entries:
743-
744-
| **Body coil** | **Head coil** | **Use case** |
745-
| -------------- | -------------- | ------------------ |
746-
| `_acq-body` | `_acq-head` | Single acquisition |
747-
| `_acq-bodyMTw` | `_acq-headMTw` | `MTw` for `MPM` |
748-
| `_acq-bodyPDw` | `_acq-headPDw` | `PDw` for `MPM` |
749-
| `_acq-bodyT1w` | `_acq-headT1w` | `T1w` for `MPM` |
750-
751-
<!-- This block generates a file tree.
752-
A guide for using macros can be found at
753-
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
754-
-->
755-
{{ MACROS___make_filetree_example(
756-
{
757-
"sub-01": {
758-
"fmap": {
759-
"sub-01_acq-body_RB1COR.nii.gz": "# Body coil",
760-
"sub-01_acq-body_RB1COR.json": "",
761-
"sub-01_acq-head_RB1COR.nii.gz": "# Head coil",
762-
"sub-01_acq-head_RB1COR.json": "",
763-
},
764-
},
765-
}
766-
) }}

0 commit comments

Comments
 (0)