From ad73668c00eb90b186a8b66a615d5b349642cddd Mon Sep 17 00:00:00 2001
From: Agah <agahkarakuzu@gmail.com>
Date: Tue, 1 Dec 2020 15:21:20 -0500
Subject: [PATCH] [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 <effigies@gmail.com>

* 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 <effigies@gmail.com>

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

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>
---
 .../01-magnetic-resonance-imaging-data.md      | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 50a6761980..658988e8fb 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -197,9 +197,11 @@ 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:
 
-| **Key name**            | **Requirement level** | **Data type** | **Description**                                                                                                                          |
-| ----------------------- | --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| ContrastBolusIngredient | OPTIONAL              | [string][]    | Active ingredient of agent. Values MUST be one of: IODINE, GADOLINIUM, CARBON DIOXIDE, BARIUM, XENON Corresponds to DICOM Tag 0018,1048. |
+| **Key name**            | **Requirement level** | **Data type**                          | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ----------------------- | --------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ContrastBolusIngredient | OPTIONAL              | [string][]                             | Active ingredient of agent. Values MUST be one of: IODINE, GADOLINIUM, CARBON DIOXIDE, BARIUM, XENON Corresponds to DICOM Tag 0018,1048.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| RepetitionTimeExcitation | OPTIONAL             | [number][] | The interval, in seconds, between two successive excitations. The DICOM tag that best refers to this parameter is [(0018, 0080)](http://dicomlookup.com/lookup.asp?sw=Tnumber&q=(0018,0080)). This field may be used together with the `RepetitionTimePreparation` for certain use cases, such as [MP2RAGE](https://doi.org/10.1016/j.neuroimage.2009.10.002). Use `RepetitionTimeExcitation` (in combination with `RepetitionTimePreparation` if needed) for anatomy imaging data rather than `RepetitionTime` as it is already defined as the amount of time that it takes to acquire a single volume in the [task imaging data](#task-including-resting-state-imaging-data) section. |
+| RepetitionTimePreparation | OPTIONAL            | [number][] or [array][] of [numbers][] | The interval, in seconds, that it takes a preparation pulse block to re-appear at the beginning of the succeeding (essentially identical) pulse sequence block. The data type number may apply to files from any MRI modality concerned with a single value for this field. The data type array provides a value for each volume in a 4D dataset and should only be used when the volume timing is critical for interpretation of the data, such as in [ASL](#arterial-spin-labeling-perfusion-data).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 The [`part-<label>`](../99-appendices/09-entities.md#part) key/value pair is
 used to indicate which component of the complex representation of the MRI
@@ -349,11 +351,11 @@ JSON file.
 
 ### Required fields
 
-| **Key name**   | **Requirement level** | **Data type**            | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| -------------- | --------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| RepetitionTime | REQUIRED              | [number][]               | The time in seconds between the beginning of an acquisition of one volume and the beginning of acquisition of the volume following it (TR). Please note that this definition includes time between scans (when no data has been acquired) in case of sparse acquisition schemes. This value needs to be consistent with the `pixdim[4]` field (after accounting for units stored in `xyzt_units` field) in the NIfTI header. This field is mutually exclusive with `VolumeTiming` and is derived from DICOM Tag 0018, 0080 and converted to seconds. |
-| VolumeTiming   | REQUIRED              | [array][] of [numbers][] | The time at which each volume was acquired during the acquisition. It is described using a list of times referring to the onset of each volume in the BOLD series. The list must have the same length as the BOLD series, and the values must be non-negative and monotonically increasing. This field is mutually exclusive with `RepetitionTime` and `DelayTime`. If defined, this requires acquisition time (TA) be defined via either `SliceTiming` or `AcquisitionDuration` be defined.                                                         |
-| TaskName       | REQUIRED              | [string][]               | Name of the task. No two tasks should have the same name. The task label included in the file name is derived from this TaskName field by removing all non-alphanumeric (`[a-zA-Z0-9]`) characters. For example TaskName `faces n-back` will correspond to task label `facesnback`. A RECOMMENDED convention is to name resting state task using labels beginning with `rest`.                                                                                                                                                                       |
+| **Key name**   | **Requirement level** | **Data type**            | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| -------------- | --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| RepetitionTime | REQUIRED              | [number][]               | The time in seconds between the beginning of an acquisition of one volume and the beginning of acquisition of the volume following it (TR). When used in the context of functional acquisitions this parameter best corresponds to [DICOM Tag 0020,0110](http://dicomlookup.com/lookup.asp?sw=Tnumber&q=(0020,0110)): the "time delta between images in a dynamic of functional set of images" but may also be found in [DICOM Tag 0018, 0080](http://dicomlookup.com/lookup.asp?sw=Tnumber&q=(0018,0080)): "the period of time in msec between the beginning of a pulse sequence and the beginning of the succeeding (essentially identical) pulse sequence". This definition includes time between scans (when no data has been acquired) in case of sparse acquisition schemes. This value MUST be consistent with the '`pixdim[4]`' field (after accounting for units stored in '`xyzt_units`' field) in the NIfTI header. This field is mutually exclusive with `VolumeTiming`. |
+| VolumeTiming   | REQUIRED              | [array][] of [numbers][] | The time at which each volume was acquired during the acquisition. It is described using a list of times referring to the onset of each volume in the BOLD series. The list must have the same length as the BOLD series, and the values must be non-negative and monotonically increasing. This field is mutually exclusive with `RepetitionTime` and `DelayTime`. If defined, this requires acquisition time (TA) be defined via either `SliceTiming` or `AcquisitionDuration` be defined.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| TaskName       | REQUIRED              | [string][]               | Name of the task. No two tasks should have the same name. The task label included in the file name is derived from this TaskName field by removing all non-alphanumeric (`[a-zA-Z0-9]`) characters. For example TaskName `faces n-back` will correspond to task label `facesnback`. A RECOMMENDED convention is to name resting state task using labels beginning with `rest`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 
 For the fields described above and in the following section, the term "Volume"
 refers to a reconstruction of the object being imaged (for example, brain or part of a