Skip to content

Commit

Permalink
[ENH] Bep 005: Arterial Spin Labeling (#669)
Browse files Browse the repository at this point in the history
* [ENH] Bep 005: Arterial Spin Labeling (#652)



Co-authored-by: Patricia Clement <[email protected]>
Co-authored-by: Stefan Appelhoff <[email protected]>
Co-authored-by: Chris Markiewicz <[email protected]>
Co-authored-by: Julia Guiomar Niso Galán <[email protected]>
Co-authored-by: Remi Gau <[email protected]>

* Update table errors

* correction for table issues 'common metadata for PCASL/PASL'

* correction latin phrases

* Corrections tables

* correction tables Cases

* added link pepolar

* deleted 'don't discriminate between types of labeling

based on comment Thijs Van Osch

* Moved MagneticFieldStrenght asl requirement to common

* removed scaling factor info based on comment gllmflndn

Removed:
all ancillary scaling factors should be taken into account in the conversion to BIDS, which is why BIDS does not provide a separate scaling factor field other than the NIfTI header.

* added MRAcquisitionType

added in the common - sequence specifics table
Reason: for ASL, defining 2D and 3D is required. This used to be added in the PulseSequenceType field, but this should stay a free text field. Therefore, the MRAcquisitionType field is added (based on DicomTag).

* removed PulseSequenceType from the ASL part

The 2D/3D information needed for ASL, is now moved to the new MRAcquisitionType field.

* added required common fields sentence

Some Common fields are required for ASL. To stress this out, we added a sentence for the *_as.json and the *_m0scan.json.

* adaptation requirements for m0scan.json

* adapted requirement level common fields for m0scan

* update sentence required common fields for asl.json

* Update common field EchoTime

* Removed EchoTime from ASL-table

* update FlipAngle in common RF and Contrasts

* remove FlipAngle from ASL fields

* update Dependency table ASL for MRAcquisitionType

* update SliceTiming in common fields

* remove SliceTiming from ASL tables

* added (FA) for FlipAngle

* update common RF and Contrast for table check

* LabelingPulseDuration and LabelingPulseInterval in ms instead of s

* required common metadatafields update

RepetitionTime or VolumeTiming to RepetitionTimePreparation

* update flipangle for timeseries versus file collections

* update echotime for timeseries

* update timing table (fence)

* update definition BackgroundSuppressionPulseTime

* removed common metadata fields from asl table

MagneticFieldStrenght, EchoTime, SliceTiming, VolumeTiming, RepetitionTime, FlipAngle, PulseSequenceType

* update scaling of asl and m0 files

- update scaling description for nifti files
- created separate scaling section (to highlight this important quantification factor), and M0 section
- moved scaling section and M0 section after aslcontext section

* update broken link in EchoTime (Timing Parameters)

* update broken link (2) EchoTime

* Update broken links FlipAngle

* LabelingType changed to ArterialSpinLabelingType

- changed in fields
- Changed in dependency table
- Dependency table: additionally removed repetitiontime/volumetiming parts

* Update dependency table based on new M0Type and M0Estimate fields

* Update new M0 field strategy

M0 field becomes M0Type, with addition field M0Estimate.
Also corrected IntendedFor description in m0 specific fields

* TEMPORARY: disable 'strict' docs build

this allows the build to proceed despite broken links

* changed fail_on_warning to true 

Intermediate solution to get BEP005 build untill the missing link is available

* see previous commit

* update bep005 with latest master + resolve conflict (#689)

* [DOC] Auto-generate changelog entry for PR #677

* [ENH] BEP001 - New entities: inv & mt (#681)

* add entity inv

* add mt:

* add MT specific metadata

* Generate entity.md

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Stefan Appelhoff <[email protected]>

* Update src/schema/entities.yaml

Co-authored-by: Stefan Appelhoff <[email protected]>

* table fix by @sappelhoff

* Conditional requirement

Co-authored-by: Stefan Appelhoff <[email protected]>

* [ENH] BEP001 - Entity-linked file collections (#688)

* Squashed commit of the following:

commit 8e1ac5f
Author: Stefan Appelhoff <[email protected]>
Date:   Fri Nov 27 11:09:24 2020 +0100

    fix links and latin

commit 27c9b41
Author: Stefan Appelhoff <[email protected]>
Date:   Fri Nov 27 10:03:51 2020 +0100

    remove latin

    Co-authored-by: Chris Markiewicz <[email protected]>

commit 7d87070
Author: Agah <[email protected]>
Date:   Mon Nov 23 08:46:47 2020 -0500

    Update src/99-appendices/10-file-collections.md

    Co-authored-by: Chris Markiewicz <[email protected]>

commit b137a9e
Author: Agah <[email protected]>
Date:   Mon Nov 23 08:45:19 2020 -0500

    Update src/02-common-principles.md

    Co-authored-by: Chris Markiewicz <[email protected]>

commit d7897b8
Author: Agah <[email protected]>
Date:   Mon Nov 23 08:44:40 2020 -0500

    Update src/02-common-principles.md

    Co-authored-by: Chris Markiewicz <[email protected]>

commit 09e9d32
Author: Agah <[email protected]>
Date:   Mon Nov 23 08:44:15 2020 -0500

    Commit suggestion

    Co-authored-by: Chris Markiewicz <[email protected]>

commit 009a9ab
Author: Agah Karakuzu <[email protected]>
Date:   Mon Nov 23 08:43:00 2020 -0500

    Add file-collecitons appendix to the TOC

commit 8f6c4df
Author: Agah Karakuzu <[email protected]>
Date:   Mon Nov 23 08:41:13 2020 -0500

    Address suggestion by @tsalo

commit 45210a9
Author: Agah Karakuzu <[email protected]>
Date:   Wed Nov 11 14:32:20 2020 -0500

    Wording

commit 66ba5a5
Author: Agah Karakuzu <[email protected]>
Date:   Wed Nov 11 14:31:40 2020 -0500

    RECOMMENDED --> MUST for adding an application def to the appdx

commit 5611fac
Author: Agah Karakuzu <[email protected]>
Date:   Wed Nov 11 14:29:21 2020 -0500

    Improve the appendix

commit 6d3bbea
Author: Agah Karakuzu <[email protected]>
Date:   Mon Nov 2 16:12:04 2020 -0500

    Address suggestions by @tsalo

commit bcb0223
Author: Agah Karakuzu <[email protected]>
Date:   Tue Oct 27 21:37:26 2020 -0400

    [ADD] Link to the appendix

commit 44e760f
Author: Agah Karakuzu <[email protected]>
Date:   Tue Oct 27 21:28:38 2020 -0400

    [ADD] Appendix - File collections

    - For parametrically linked file collections

commit 523b1c1
Author: Agah Karakuzu <[email protected]>
Date:   Tue Oct 27 21:27:52 2020 -0400

    [ADD] Parametrically linked file collections

    - Description

* ENH: Link to all BEP-001 entities

* STY: Escape asterisk, adjust table widths

* Add suggestions by @sappelhoff

* Update src/02-common-principles.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/02-common-principles.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/02-common-principles.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/99-appendices/10-file-collections.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/02-common-principles.md

Thank you @effigies!

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/02-common-principles.md

Co-authored-by: Chris Markiewicz <[email protected]>

Co-authored-by: Agah Karakuzu <[email protected]>

* [ENH] BEP001 - RepetitionTimeExcitation and RepetitionTimePreparation (#671)

* [ENH] Improve TR definitions

- Include RepetitionTimePreparation
- Include RepetitionTimeExcitation
- Add explanation on the former RepetitionTime field.

* Typo

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Chris Markiewicz <[email protected]>

* ENH: Allow for variable RTE/P

* STY: Update table widths

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

* Change ref to DOI @Remi-Gau

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Chris Markiewicz <[email protected]>

Co-authored-by: Chris Markiewicz <[email protected]>
Co-authored-by: Chris Markiewicz <[email protected]>

* Update config.yml

* Update readthedocs.yml

Co-authored-by: bids-maintenance <[email protected]>
Co-authored-by: Agah <[email protected]>
Co-authored-by: Chris Markiewicz <[email protected]>
Co-authored-by: Chris Markiewicz <[email protected]>

* update required common fields for m0scan.json

added EchoTime and FlipAngle in case LookLocker is true

* update dependency table

if PCASL : LabelingDuration is required
if PCASL: LabelingDuration should not be filled in

* update depedency table

removed 'PASL' LAbelingDuration should not be filled in

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Chris Markiewicz <[email protected]>

* update description aslcontext

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Chris Markiewicz <[email protected]>

* update PCASLType and CASLType

Co-authored-by: Chris Markiewicz <[email protected]>

* updated required into REQUIRED

for asl.json and m0scan.json (common fields

* Added SummaryImages

Added images:
asl_pasl_boluscutoff_false.png
asl_pasl_boluscutoff_true_q2tips.png
asl_pasl_boluscutoff_true_quipssII.png
asl_pcasl_labeling_pulses.png
asl_pcasl_sequence.png

* create Appendix 11 for ASL

* Added asl_flowchart.png

* added subtitles for linking from main specification

* Added appendix link for control and label

* added appendix for asl sequences in general

* added appendix for (P)CASL

* added appendix for PASL

* added appendix for dependency table (flowcharts)

* MNT: Add ASL appendix to TOC

* TYPO: correct ASL appendix entry in tocwq

* fix md style

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Chris Markiewicz <[email protected]>

* update table RF and Contrast

* update link Appendix XI to Appendix XI - ASL

* corrected link to appendix for PASL

* Update aslcontext cases

Case 1:
changed asl.json to asl.nii[.gz`]
Removed:  The optional deltam or cbf volumes should be stored and specified as derivative.

Case 2:
Removed: The optional cbf volumes should be stored and specified as derivative.

* Added aslcontext.tsv cases

this is moved from main spec bep005 to appendix XI - ASL

* Update aslcontext cases

- moved three cases to appendix XI - ASL
- added link to appendix XI
- added: Note that the raw images, including the m0scan, may also be used for quality control.

* corrected subtitles cases

* improve linebreaks in ASL appendix

* fix VascularCrushingVENC link

Based on comment of Stefan Appelhof, the Data Type for VascularChrushingVENC was fixed:
[number][] or \[array][] of [numbers][] 
to
[number][] or [array][] of [numbers][]

* added single column requirement for aslcontext.tsv

based on comment of Stefan Appelhof, the need for a single column was added in the introductory text for aslcontext.tsv, before the 3 cases.

* Changed VascularCrushingVENC to VascularCrushingVenc

* [SCHEMA] Add ASL to schema (#703)

* Add ASL to schema files and regenerate entity table.

* Fix style issue.

* Add fmap-format m0scan to schema.

* update M0Estimate fields

Added 'Referring to the M0 of blood'

* update LabelingDuration

Added additional information for LabelingDuration

* update labeling.jpg into *_asllabeling.jpg

* Change labeling to asllabeling. (#709)

* RF: Renumber ASL appendix to XII

Co-authored-by: Henk Mutsaerts <[email protected]>
Co-authored-by: Patricia Clement <[email protected]>
Co-authored-by: Chris Markiewicz <[email protected]>
Co-authored-by: Julia Guiomar Niso Galán <[email protected]>
Co-authored-by: Remi Gau <[email protected]>
Co-authored-by: bids-maintenance <[email protected]>
Co-authored-by: Agah <[email protected]>
Co-authored-by: Chris Markiewicz <[email protected]>
Co-authored-by: Taylor Salo <[email protected]>
  • Loading branch information
10 people authored Jan 15, 2021
1 parent c7751c7 commit d794736
Show file tree
Hide file tree
Showing 15 changed files with 374 additions and 30 deletions.
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ nav:
- Entities: 99-appendices/09-entities.md
- File collections: 99-appendices/10-file-collections.md
- Quantitative MRI: 99-appendices/11-qmri.md
- Arterial Spin Labeling: 99-appendices/12-arterial-spin-labeling.md
- Changelog: CHANGES.md
- The BIDS Starter Kit:
- GitHub repository: https://github.com/bids-standard/bids-starter-kit
Expand Down
200 changes: 173 additions & 27 deletions src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Large diffs are not rendered by default.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
25 changes: 24 additions & 1 deletion src/99-appendices/01-contributors.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,10 @@ The following individuals have contributed to the Brain Imaging Data Structure
ecosystem (in alphabetical order).
If you contributed to the BIDS ecosystem and your name is not listed, please add it.

- Eric Achten 📖🔣📓
- Azeez Adebimpe 📖
- Fidel Alfaro Almagro 💬📖💡🔌
- David Alsop 📖
- Stefan Appelhoff 📖💬🤔🐛💡💻👀⚠️📢✅🔧🔌📝🚧🔣
- Tibor Auer 💬📖💡🔧📢
- Sylvain Baillet 📖🔍
Expand All @@ -48,8 +51,12 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
- Teon L. Brooks 📖💻⚠️💬👀🤔🔧🐛📢
- Suyash Bhogawar 📖💡⚠️🔧💬
- Vince D. Calhoun 📖
- Marco Castellaro 💬🐛💻📖💡⚠️📢🚇
- Michael Chappell 📖🔣📆
- Patricia Clement 💬🐛💻📖🔣💡📋🤔📆⚠️📢
- Alexander L. Cohen 🐛💻📖💬
- R. Cameron Craddock 📖📢
- Martin Craig 🔣
- Sasha D'Ambrosio 📖
- Samir Das 📖
- Olivier David 📖
Expand All @@ -67,6 +74,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
- Guillaume Flandin 📖💻
- Adeen Flinker 📖
- Brett L. Foster 📖
- Ana Fouto 📓
- Remi Gau 📖💻💬📢🐛💻🚇👀🔧🤔
- Satrajit S. Ghosh 📖💻
- Tristan Glatard 📖💻
Expand All @@ -77,27 +85,34 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
- Iris Groen 📖
- David Groppe 📖
- Aysegul Gunduz 📖
- Matthias Günther 📖
- Yaroslav O. Halchenko 📖📢🔧💬🐛
- Liberty Hamilton 📖
- Tom Hampshire 📖
- Daniel A. Handwerker 📖
- Michael Hanke 📖🤔🔧🐛📢
- Michael P. Harms 📖⚠️🔧
- Richard N. Henson 📖
- Peer Herholz 💬📖👀🔧✅📢
- Dora Hermes 📖💻✅🔍🤔
- Luis Hernandez-Garcia 📖📓
- Katja Heuer 🔧
- Richard Höchenberger 📖
- Chris Holdgraf 📖🤔
- Christopher J. Honey 📖
- Jean-Christophe Houde 📖
- International Neuroinformatics Coordinating Facility 💵📋
- Andrew Jahn 📓
- Andrew Janke 📖💻
- Mainak Jas 📖💻
- Alexander Jones 💻🐛
- Tamás Józsa 📓
- David Keator 📖
- James Kent 💬💻
- Gregory Kiar 📖💻🎨🔧
- Thomas Kirk 📖
- Robert Knight 📖
- Joost Kuijer 📖
- Jean-Philippe Lachaux 📖
- Marc Lalancette 📖
- Pamela LaMontagne 📖💡
Expand All @@ -118,7 +133,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
- Zachary Michael 📖
- Ezequiel Mikulan 📖💻
- Michael P. Milham 💡🔍
- Henk Mutsaerts 📖
- Henk Mutsaerts 💬🐛💻📖💡📋🤔📆📢📓
- National Institute of Mental Health 💵
- Mikael Naveau 🐛
- B. Nolan Nichols 📖
Expand All @@ -127,13 +142,17 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
- Guiomar Niso 📖💡📢
- Michael P. Notter 💬📝✅📢📖
- Jeffrey G. Ojemann 📖
- Thomas Okell 📖
- Aaron Oliver-Taylor 📖
- Robert Oostenveld 📖🔧📢💡✅⚠️🤔
- Dimitri Papadopoulos Orfanos 📖💡🤔💬
- Patrick Park 📖💡💬
- Maurice Pasternak 📓
- Dianne Patterson 📖
- John Pellman 📖
- Cyril Pernet 💬📝📖🎨💡📋🤔📢
- Franco Pestilli 📖💻🎨💡🤔👀🔧
- Jan Petr 💬🐛💻📖🔣💡📋🤔📆⚠️📢
- Natalia Petridou 📖
- Dmitry Petrov 📖💻
- Christophe Phillips 📖
Expand All @@ -149,6 +168,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
- Kay Robbins 💻📖🐛
- Alex Rockhill 📖🔧
- Ariel Rokem 📖
- Chris Rorden 📖💻
- Taylor Salo 💬📖🔌
- Matt Sanderson 📖💻
- Gunnar Schaefer 📖
Expand All @@ -158,11 +178,14 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
- Arjen Stolk 📖
- Nicole C. Swann 📖
- François Tadel 📖🔌💡
- David Thomas 📖🔣
- Roberto Toro 🔧
- Sébastien Tourbier 🤔👀📢🐛💻📖
- William Triplett 📖
- Jessica A. Turner 📖
- Pieter Vandemaele 📖💻
- Max A. van den Boom 💻👀📖
- Matthias Van Osch 📖
- Bradley Voytek 📖
- Brian A. Wandell 📖
- Joseph Wexler 📖💡
Expand Down
4 changes: 3 additions & 1 deletion src/99-appendices/04-entity-table.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,14 @@ while entity definitions are in [Appendix IX](09-entities.md).
| anat<br>(MTR) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | | | | | REQUIRED | OPTIONAL | |
| dwi<br>(dwi sbref) | REQUIRED | OPTIONAL | | OPTIONAL | | | OPTIONAL | OPTIONAL | | | | | | OPTIONAL | |
| fmap<br>(phasediff phase1 phase2 magnitude1 magnitude2 magnitude fieldmap) | REQUIRED | OPTIONAL | | OPTIONAL | | | | OPTIONAL | | | | | | | |
| fmap<br>(epi) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | | REQUIRED | OPTIONAL | | | | | | | |
| fmap<br>(epi m0scan) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | | REQUIRED | OPTIONAL | | | | | | | |
| fmap<br>(TB1DAM) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | | | REQUIRED | | | OPTIONAL | |
| fmap<br>(TB1EPI) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | | REQUIRED | REQUIRED | | | OPTIONAL | |
| func<br>(bold cbv sbref) | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | | | | OPTIONAL | |
| func<br>(phase events) | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | | | | | |
| func<br>(physio stim) | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | | OPTIONAL | | OPTIONAL | | | | | | | OPTIONAL |
| perf<br>(asl m0scan aslcontext) | REQUIRED | OPTIONAL | | OPTIONAL | | OPTIONAL | OPTIONAL | OPTIONAL | | | | | | | |
| perf<br>(asllabeling) | REQUIRED | OPTIONAL | | OPTIONAL | | OPTIONAL | | OPTIONAL | | | | | | | |

## Encephalography (EEG, iEEG, and MEG)

Expand Down
130 changes: 130 additions & 0 deletions src/99-appendices/12-arterial-spin-labeling.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
# Appendix XI: Arterial Spin Labeling

These sections provide additional clarification for some specific topics within the BIDS specification for Arterial Spin Labeling.

## Which image is `control` and which is `label`?

The `control` and `label` images are acquired with identical acquisition parameters,
except that the blood magnetization flowing into the imaging region is effectively inverted
in the `label` image compared to the `control` image.
In case of doubt, an easy rule of thumb is that the `deltaM`=`control`-`label` subtraction
should result in a perfusion-weighted image with a positive sign.
For example, in the case of FAIR this would be selective inversion (`control`)
and non-selective inversion (`label`).

## `*_aslcontext.tsv`: three possible cases

The `*_aslcontext.tsv` table consists of a single column of labels identifying the `volume_type` of each volume in the corresponding `*_asl.nii[.gz]` file.
See below examples of the three `*_aslcontext.tsv` cases, in order of decreasing preference.

### Case 1: `*_asl.nii[.gz]` consists of volume_types `control`, `label`

In most cases, the ASL timeseries provided by the scanner consist of a series
of `control` and `label`, and optionally `m0scan` volumes.
In this case, only the `control`, `label`, and optionally `m0scan` volumes should be stored in the `*_asl.nii[.gz]`,
and the exact volume_type series should be specified in the `*_aslcontext.tsv`.

Example of `*_aslcontext.tsv`:

```Text
volume_type
control
label
control
label
m0scan
```

### Case 2: `*_asl.nii[.gz]` consists of volume_types `deltam` (scanner does not export `control` or `label` volumes)

In some cases, `control` and `label` volumes are lacking within the acquired ASL timeseries,
but the intermediate `deltam` - and optionally an `m0scan` -
volume is reconstructed/exported by the scanner.
In this case, the `deltam` should be included in the `*_asl.nii[.gz]` and specified in the `*_aslcontext.tsv`.

Example of `*_aslcontext.tsv`:

```Text
volume_type
deltam
m0scan
```

### Case 3: `*_asl.nii[.gz]` consists of volume_type `cbf` (scanner does not export `control`, `label`, or `deltaM` volumes)

If `control` and `label` or intermediate ASL volumes are not reconstructed or exported,
but a pre-calculated `cbf` - and optionally a `m0scan` - volume is provided by the scanner,
the `cbf` should be included in the `*_asl.nii[.gz]` and specified in the `*_aslcontext.tsv`.

Example of `*_aslcontext.tsv`:

```Text
volume_type
cbf
m0scan
```

## Summary Image of the most common ASL sequences

The following images illustrate the main BIDS metadata fields for three `ArterialSpinLabelingType`'s:
`CASL`, `PCASL`, and `PASL`.
Images are courtesy of, and adapted with permission from
Y. Suzuki and [OSIPI Task force 4.1: ASL lexicon milestone 1](https://www.osipi.org/task-force-4-1/).

### (P)CASL sequence

![PCASL](../04-modality-specific-files/images/asl_pcasl_sequence.png)

For (P)CASL, specifying the `LabelingDuration` and the `PostLabelingDelay` is required.
The `LabelingDuration` is defined as the total duration of the labeling pulse train in seconds.
`PostLabelingDelay` is the time in seconds after the end of the labeling until the middle of the excitation pulse applied
to the imaging slab (for 3D acquisition) or first slice (for 2D acquisition).
Additionally, the `BackgroundSuppressionPulseTime`'s is required in case `BackgroundSuppression` was applied.
This an array of numbers containing the timing in seconds of the background suppression pulses
with respect to the start of the labeling.
In the case of `PCASL`, the recommended `PCASLType` field defines the type of the gradient pulses
used in the `control` condition (`balanced` or `unbalanced`),
whereas in case of `CASL`,the recommended `CASLType` field describes if a separate coil is used for labeling
(`single-coil` or `double-coil`).

### (P)CASL Labeling Pulses

![PCASL Labeling Pulses](../04-modality-specific-files/images/asl_pcasl_labeling_pulses.png)

Several recommended metadata fields describe the labeling pulses of the labeling pulse train in PCASL.
The `LabelingPulseAverageGradient` and the `LabelingPulseMaximumGradient` are the average labeling gradient
and the maximum amplitude of the gradient switched on during the application of the labeling RF pulse(s),
in milliteslas per meter.
The `LabelingPulseAverageB1` is the average B1-field strength of the RF labeling pulses in microteslas.
The `LabelingPulseDuration` and `LabelingPulseInterval` are the duration of,
and the delay between the peaks of the individual labeling pulses in milliseconds.

### PASL sequence

![PASL without Bolus Cut-off](../04-modality-specific-files/images/asl_pasl_boluscutoff_false.png)

For PASL, specifying the `PostLabelingDelay` is required.
`PostLabelingDelay` is the time, in seconds, from the middle of the labeling pulse until the middle of
the excitation pulse applied to the imaging slab (for 3D acquisition) or first slice (for 2D acquisition).
Additionally, the `BolusCutOffFlag` field is required,
which is a boolean indicating if a bolus cut-off technique has been applied.

![PASL QUIPSSII](../04-modality-specific-files/images/asl_pasl_boluscutoff_true_quipssII.png)

When `BolusCutOffFlag` is set true for `PASL`, two additional metadata fields are required:
`BolusCutOffTechnique` and `BolusCutOffDelay`.
In this example, the `BolusCutOffTechnique`, which is the name of the technique used for applying a bolus cut-off,
is QUIPSS-II consisting of only one bolus cut-off pulse.
The `BolusCutOffDelay` is therefore a number, representing the duration between the end of the labeling and the start of the bolus cut-off saturation pulse, in seconds.

![PASL Q2TIPS](../04-modality-specific-files/images/asl_pasl_boluscutoff_true_q2tips.png)

In this example, the `BolusCutOffTechnique` applied is Q2TIPS, consisting of multiple bolus cut-off pulses.
In this case, only the duration of the first and last pulse should be specified in `BolusCutOffDelay`.

## Flowchart (based on dependency table)

The specification includes a dependency table, describing metadata field dependencies for ASL.
This flowchart is intended to further clarify that table.

![ASL Flowchart](../04-modality-specific-files/images/asl_flowchart.png)
1 change: 1 addition & 0 deletions src/schema/datatypes/fmap.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
# Second group
- suffixes:
- epi
- m0scan
extensions:
- .nii.gz
- .nii
Expand Down
Loading

0 comments on commit d794736

Please sign in to comment.