[ENH] Adding an OPTIONAL _task-<label> to structural MRI acquisitions (…

…bids-standard#1185)

* Added _task label to MR spec text

Modified the text in MR markdown as well as added task to anat.yaml file under rules so it appears in the tables

* removed additional white space

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

I agree with Remi's reasoning here.

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

* To fulfill requests in PR bids-standard#1185

As discussed in the  [PR bids-standard#1185](bids-standard#1185)  I added this recommended meta information for structural tasks as well. Note the descriptions differ slightly from the ones for task.

* Updated TaskName example

In order to make the TaskName example more general, I suggest to replace the reference to `"faces n-back"` with `"task x-x"`, sicne this is only meant to showcase what name formatting should look like.

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

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

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

markdonw fix

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

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

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

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

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

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

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

* Apply suggestions from code review

* Reorganized sorting of entities 

As was pointed out by Remi with reference to [issue 1017](bids-standard#1071) the entities should be sorted. I have now put task in front of acquisition in order in all of anat.

* Remove duplication of infor with appendix

Removed the sentence "Task labels MUST be consistent across subjects and sessions." under task since this is part of the definition in the appendices already.

* Update src/schema/objects/metadata.yaml

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

* Added TaskMetaData

As requested [here](bids-standard#1185 (comment)), I am adding TaskMetadata into the anat.yaml.

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

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

* Fixing trailing white spaces

* Removed subheading 

Removed subheading "RECOMMENDED metadata for tasks in anatomical imaging" as suggested [here](bids-standard#1185 (comment))

Co-authored-by: Remi Gau <remi_gau@hotmail.com>
Co-authored-by: Chris Markiewicz <effigies@gmail.com>

src/modality-specific-files/magnetic-resonance-imaging-data.md

@@ -207,6 +207,18 @@ entity corresponds to modality suffix,
 such as `T1w` or `inplaneT1`, referenced by the defacemask image.
 For example, `sub-01_mod-T1w_defacemask.nii.gz`.
 
+The OPTIONAL [`task-<label>`](../appendices/entities.md#task) entity can be used
+in order to allow tasks during structural MR acquisitions,
+for example pre-described motion paradigms such as nodding, to be described.
+
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table("anat.TaskMetadata") }}
+
 Some meta information about the acquisition MAY be provided in an additional
 JSON file. See [Common metadata fields](#common-metadata-fields) for a
 list of terms and their definitions. There are also some OPTIONAL JSON

src/schema/objects/metadata.yaml

@@ -3180,8 +3180,8 @@ TaskName:
     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 characters (that is, all except those matching `[0-9a-zA-Z]`).
-    For example `"TaskName"` `"faces n-back"` will correspond to task label
-    `facesnback`.
+    For example `"TaskName"` `"faces n-back"` or `"head nodding" will correspond to task labels
+    `facesnback` and `headnodding`, respectively.
   type: string
 TermURL:
   name: TermURL

src/schema/rules/files/raw/anat.yaml

@@ -22,6 +22,7 @@ nonparametric:
   entities:
     subject: required
     session: optional
+    task: optional
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -56,6 +57,7 @@ parametric:
   entities:
     subject: required
     session: optional
+    task: optional
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -73,6 +75,7 @@ defacemask:
   entities:
     subject: required
     session: optional
+    task: optional
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -92,6 +95,7 @@ multiecho:
   entities:
     subject: required
     session: optional
+    task: optional
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -111,6 +115,7 @@ multiflip:
   entities:
     subject: required
     session: optional
+    task: optional
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -131,6 +136,7 @@ multiinversion:
   entities:
     subject: required
     session: optional
+    task: optional
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -150,6 +156,7 @@ mp2rage:
   entities:
     subject: required
     session: optional
+    task: optional
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -172,6 +179,7 @@ vfamt:
   entities:
     subject: required
     session: optional
+    task: optional
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -193,6 +201,7 @@ mtr:
   entities:
     subject: required
     session: optional
+    task: optional
     acquisition: optional
     ceagent: optional
     reconstruction: optional

src/schema/rules/sidecars/anat.yaml

@@ -31,3 +31,18 @@ PhaseSuffixUnits:
     - suffix == "phase"
   fields:
     Units: required
+
+TaskMetadata:
+  selectors:
+    - datatype == "anat"
+    - entity.task != null
+  fields:
+    TaskName:
+      level: recommended
+      level_addendum: if `task` entity is present
+    TaskDescription:
+      level: recommended
+      level_addendum: if `task` entity is present
+    Instructions:
+      level: recommended
+      level_addendum: if `task` entity is present