[ENH] BEP001 - New entity: flip

src/99-appendices/09-entities.md

@@ -40,7 +40,8 @@ several visits (for example fMRI on one day followed by DWI the day after)
 those can be grouped in one session.
 Defining multiple sessions is appropriate when several identical or similar
 data acquisitions are planned and performed on all -or most- subjects,
-often in the case of some intervention between sessions (for example, training).
+often in the case of some intervention between sessions
+(for example, training).
 
 ## task
 
@@ -69,11 +70,12 @@ In such case two files could have the following names:
 `sub-01_acq-highres_T1w.nii.gz` and `sub-01_acq-lowres_T1w.nii.gz`, however
 the user is free to choose any other label than highres and lowres as long
 as they are consistent across subjects and sessions.
-In case different sequences are used to record the same modality (for example, RARE
-and FLASH for T1w) this field can also be used to make that distinction.
-At what level of detail to make the distinction (for example, just between RARE and
-FLASH, or between RARE, FLASH, and FLASHsubsampled) remains at the
-discretion of the researcher.
+In case different sequences are used to record the same modality
+(for example, RARE and FLASH for T1w)
+this field can also be used to make that distinction.
+At what level of detail to make the distinction (for example,
+just between RARE and FLASH, or between RARE, FLASH, and FLASHsubsampled)
+remains at the discretion of the researcher.
 
 ## ce
 
@@ -104,7 +106,8 @@ Full name: Phase-Encoding Direction
 Format: `dir-<label>`
 
 Definition: The `dir-<label>` key/value can be set to an arbitrary alphanumeric label
-(for example, `dir-LR` or `dir-AP`) to distinguish different phase-encoding directions.
+(for example, `dir-LR` or `dir-AP`) to distinguish different phase-encoding
+directions.
 
 ## run
 
@@ -133,13 +136,26 @@ Full name: Echo
 
 Format: `echo-<index>`
 
-Definition: Multi-echo data MUST be split into one file per echo.
-Each file shares the same name with the exception of the `_echo-<index>`
-key/value.
+Definition: If constituents of an entity-linked file collection differ as a
+function of `EchoTime` acquisition parameter, the `_echo-<index>` key/value
+pair MUST be used to distinguish individual files.
 Please note that the `<index>` denotes the number/index (in the form of a
 nonnegative integer) of the echo not the echo time value which needs to be
 stored in the field `EchoTime` of the separate JSON file.
 
+## flip
+
+Full name: Flip Angle
+
+Format: `flip-<index>`
+
+Definition: If constituents of an entity-linked file collection differ as a function of
+`FlipAngle` acquisition parameter, the `_flip-<index>` key/value pair MUST
+be used to distinguish individual files.
+Please note that the `<index>` denotes the number/index (in the form of a
+nonnegative integer), not the `FlipAngle` value which needs to be stored in
+the field `FlipAngle` of the separate JSON file.
+
 ## recording
 
 Full name: Recording
@@ -160,9 +176,10 @@ Format: `proc-<label>`
 Definition: The proc label is analogous to rec for MR and denotes a variant of a file
 that was a result of particular processing performed on the device.
 This is useful for files produced in particular by Elekta’s MaxFilter
-(for example, sss, tsss, trans, quat or mc), which some installations impose to
-be run on raw data because of active shielding software corrections before
-the MEG data can actually be exploited.
+(for example, sss, tsss, trans, quat or mc),
+which some installations impose to be run on raw data because of active
+shielding software corrections before the MEG data can actually be
+exploited.
 
 ## space
 

src/schema/entities.yaml

@@ -102,13 +102,24 @@ echo:
   name: Echo
   entity: echo
   description: |
-    Multi-echo data MUST be split into one file per echo.
-    Each file shares the same name with the exception of the `_echo-<index>`
-    key/value.
+    If constituents of an entity-linked file collection differ as a
+    function of `EchoTime` acquisition parameter, the `_echo-<index>` key/value
+    pair MUST be used to distinguish individual files.
     Please note that the `<index>` denotes the number/index (in the form of a
     nonnegative integer) of the echo not the echo time value which needs to be
     stored in the field `EchoTime` of the separate JSON file.
   format: index
+flip:
+  name: Flip Angle
+  entity: flip 
+  description: |
+    If constituents of an entity-linked file collection differ as a function of
+    `FlipAngle` acquisition parameter, the `_flip-<index>` key/value pair MUST
+    be used to distinguish individual files.
+    Please note that the `<index>` denotes the number/index (in the form of a
+    nonnegative integer), not the `FlipAngle` value which needs to be stored in
+    the field `FlipAngle` of the separate JSON file.
+  format: index  
 recording:
   name: Recording
   entity: recording
@@ -153,4 +164,4 @@ split:
     the file names, but also the internal file pointers will be updated.
     It is RECOMMENDED that .fif files with multiple parts use the
     `split-<index>` entity to indicate each part.
-  format: index
+  format: index

tools/bids_schema.py

@@ -224,7 +224,7 @@ def save_entities(schema_path, out_file):
             fo.write('\n\n')
             fo.write('Full name: {}'.format(entity_info['name']))
             fo.write('\n\n')
-            fo.write('Format: `{}-<{}>`'.format(entity, entity_info['format']))
+            fo.write('Format: `{}-<{}>`'.format(entity_info['entity'], entity_info['format']))
             fo.write('\n\n')
             fo.write('Definition: {}'.format(entity_info['description']))