[SCHEMA] Add derivatives entities to the schema (#645)

* Add derivatives entities.

* Apply suggestions from code review

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

* Differentiate derivative entities from raw entities.

* Update entities page.

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

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
 
@@ -160,20 +162,26 @@ 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
 
 Full name: Space
 
 Format: `space-<label>`
 
-Definition: The space label (`*[_space-<label>]_electrodes.tsv`) can be used
-to indicate the way in which electrode positions are interpreted.
+Definition: The space entity can be used to indicate
+the way in which electrode positions are interpreted
+(for EEG/MEG/iEEG data) or
+the spatial reference to which a file has been aligned (for MRI data).
 The space label needs to be taken from the list in Appendix VIII.
 
+For EEG/MEG/iEEG data, this entity can be applied to raw data, but
+for other data types, it is restricted to derivative data.
+
 ## split
 
 Full name: Split
@@ -191,3 +199,50 @@ new names with dedicated tools like MNE, which will ensure that not only
 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.
+
+## res
+
+Full name: Resolution
+
+Format: `res-<label>`
+
+Definition: Resolution of regularly sampled N-dimensional data.
+MUST have a corresponding `Resolution` metadata field to provide
+interpretation.
+
+This entity is only applicable to derivative data.
+
+## den
+
+Full name: Density
+
+Format: `den-<label>`
+
+Definition: Density of non-parametric surfaces.
+MUST have a corresponding `Density` metadata field to provide
+interpretation.
+
+This entity is only applicable to derivative data.
+
+## label
+
+Full name: Label
+
+Format: `label-<label>`
+
+Definition: Tissue-type label, following a prescribed vocabulary.
+Applies to binary masks and probabilistic/partial volume segmentations
+that describe a single tissue type.
+
+This entity is only applicable to derivative data.
+
+## desc
+
+Full name: Description
+
+Format: `desc-<label>`
+
+Definition: When necessary to distinguish two files that do not otherwise have a
+distinguishing entity, the `_desc-<label>` keyword-value SHOULD be used.
+
+This entity is only applicable to derivative data.

src/schema/entities.yaml

@@ -134,9 +134,14 @@ space:
   name: Space
   entity: space
   description: |
-    The space label (`*[_space-<label>]_electrodes.tsv`) can be used
-    to indicate the way in which electrode positions are interpreted.
+    The space entity can be used to indicate
+    the way in which electrode positions are interpreted
+    (for EEG/MEG/iEEG data) or
+    the spatial reference to which a file has been aligned (for MRI data).
     The space label needs to be taken from the list in Appendix VIII.
+
+    For EEG/MEG/iEEG data, this entity can be applied to raw data, but
+    for other data types, it is restricted to derivative data.
   format: label
 split:
   name: Split
@@ -154,3 +159,42 @@ split:
     It is RECOMMENDED that .fif files with multiple parts use the
     `split-<index>` entity to indicate each part.
   format: index
+res:
+  name: Resolution
+  entity: res
+  description: |
+    Resolution of regularly sampled N-dimensional data.
+    MUST have a corresponding `Resolution` metadata field to provide
+    interpretation.
+
+    This entity is only applicable to derivative data.
+  format: label
+den:
+  name: Density
+  entity: den
+  description: |
+    Density of non-parametric surfaces.
+    MUST have a corresponding `Density` metadata field to provide
+    interpretation.
+
+    This entity is only applicable to derivative data.
+  format: label
+label:
+  name: Label
+  entity: label
+  description: |
+    Tissue-type label, following a prescribed vocabulary.
+    Applies to binary masks and probabilistic/partial volume segmentations
+    that describe a single tissue type.
+
+    This entity is only applicable to derivative data.
+  format: label
+desc:
+  name: Description
+  entity: desc
+  description: |
+    When necessary to distinguish two files that do not otherwise have a
+    distinguishing entity, the `_desc-<label>` keyword-value SHOULD be used.
+
+    This entity is only applicable to derivative data.
+  format: label

tools/bids_schema.py

@@ -224,7 +224,8 @@ 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']))