From e211dafa9c3b4ff660262f5fdf5cfee86125677e Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Fri, 16 Oct 2020 15:48:22 -0400
Subject: [PATCH 1/4] Add derivatives entities.

---
 src/99-appendices/09-entities.md | 60 ++++++++++++++++++++++++++------
 src/schema/entities.yaml         | 31 +++++++++++++++--
 tools/bids_schema.py             |  3 +-
 3 files changed, 80 insertions(+), 14 deletions(-)

diff --git a/src/99-appendices/09-entities.md b/src/99-appendices/09-entities.md
index 32acf9fbe3..bc451b28db 100644
--- a/src/99-appendices/09-entities.md
+++ b/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,9 +162,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
 
@@ -170,8 +173,10 @@ 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.
 
 ## split
@@ -191,3 +196,36 @@ 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-D data.
+
+## den
+
+Full name: Density
+
+Format: `den-<label>`
+
+Definition: Density of non-parametric surfaces.
+
+## label
+
+Full name: Label
+
+Format: `label-<label>`
+
+Definition: Tissue-type label, following a prescribed vocabulary.
+
+## 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.
diff --git a/src/schema/entities.yaml b/src/schema/entities.yaml
index ae609b49e3..569189f556 100644
--- a/src/schema/entities.yaml
+++ b/src/schema/entities.yaml
@@ -133,8 +133,10 @@ 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.
   format: label
 split:
@@ -153,3 +155,28 @@ 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-D data.
+  format: label
+den:
+  name: Density
+  entity: den
+  description: |
+    Density of non-parametric surfaces.
+  format: label
+label:
+  name: Label
+  entity: label
+  description: |
+    Tissue-type label, following a prescribed vocabulary.
+  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.
+  format: label
diff --git a/tools/bids_schema.py b/tools/bids_schema.py
index fa139c8e44..a0dd90fda5 100755
--- a/tools/bids_schema.py
+++ b/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']))
 

From 6fc364580414ae6b9de68e75edd5455890b9204d Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Mon, 19 Oct 2020 16:28:53 -0400
Subject: [PATCH 2/4] Apply suggestions from code review

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 src/schema/entities.yaml | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/schema/entities.yaml b/src/schema/entities.yaml
index 569189f556..8169f25264 100644
--- a/src/schema/entities.yaml
+++ b/src/schema/entities.yaml
@@ -159,19 +159,23 @@ res:
   name: Resolution
   entity: res
   description: |
-    Resolution of regularly sampled N-D data.
+    Resolution of regularly sampled N-dimensional data.
+    MUST have a corresponding `Resolution` metadata field to provide interpretation.
   format: label
 den:
   name: Density
   entity: den
   description: |
     Density of non-parametric surfaces.
+    MUST have a corresponding `Density` metadata field to provide interpretation.
   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.
   format: label
 desc:
   name: Description

From edfda60b4737fe82313478758ecc1a3213d7e9c0 Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Sat, 24 Oct 2020 13:03:47 -0400
Subject: [PATCH 3/4] Differentiate derivative entities from raw entities.

---
 src/schema/entities.yaml | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/src/schema/entities.yaml b/src/schema/entities.yaml
index 8169f25264..a780f295ad 100644
--- a/src/schema/entities.yaml
+++ b/src/schema/entities.yaml
@@ -138,6 +138,9 @@ space:
     (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
@@ -160,22 +163,30 @@ res:
   entity: res
   description: |
     Resolution of regularly sampled N-dimensional data.
-    MUST have a corresponding `Resolution` metadata field to provide interpretation.
+    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.
+    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.
+    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
@@ -183,4 +194,6 @@ 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

From ffa3af31fa217cc11431abc85cb1f4c0813fb6dd Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Sat, 24 Oct 2020 13:04:37 -0400
Subject: [PATCH 4/4] Update entities page.

---
 src/99-appendices/09-entities.md | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/99-appendices/09-entities.md b/src/99-appendices/09-entities.md
index bc451b28db..cd009c71d4 100644
--- a/src/99-appendices/09-entities.md
+++ b/src/99-appendices/09-entities.md
@@ -179,6 +179,9 @@ the way in which electrode positions are interpreted
 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
@@ -203,7 +206,11 @@ Full name: Resolution
 
 Format: `res-<label>`
 
-Definition: Resolution of regularly sampled N-D data.
+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
 
@@ -212,6 +219,10 @@ 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
 
@@ -220,6 +231,10 @@ 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
 
@@ -229,3 +244,5 @@ 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.