From 932a3714c1dc7fd902ff704258ee42bce5c557b4 Mon Sep 17 00:00:00 2001
From: melanieganz <melanieganz@users.noreply.github.com>
Date: Thu, 1 Dec 2022 20:19:27 +0100
Subject: [PATCH] [ENH] Adding an OPTIONAL _task-<label> to structural MRI
 acquisitions (#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 #1185

As discussed in the  [PR #1185](https://github.com/bids-standard/bids-specification/pull/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](https://github.com/bids-standard/bids-specification/issues/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](https://github.com/bids-standard/bids-specification/pull/1185#discussion_r990039927), 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](https://github.com/bids-standard/bids-specification/pull/1185#discussion_r990036321)

Co-authored-by: Remi Gau <remi_gau@hotmail.com>
Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 .../magnetic-resonance-imaging-data.md            | 12 ++++++++++++
 src/schema/objects/metadata.yaml                  |  4 ++--
 src/schema/rules/files/raw/anat.yaml              |  9 +++++++++
 src/schema/rules/sidecars/anat.yaml               | 15 +++++++++++++++
 4 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-imaging-data.md b/src/modality-specific-files/magnetic-resonance-imaging-data.md
index 4c88c4bdef..b323822e97 100644
--- a/src/modality-specific-files/magnetic-resonance-imaging-data.md
+++ b/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
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 4e9466e9ae..56ca9ae0cb 100644
--- a/src/schema/objects/metadata.yaml
+++ b/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
diff --git a/src/schema/rules/files/raw/anat.yaml b/src/schema/rules/files/raw/anat.yaml
index df15bd69e2..54edaccc22 100644
--- a/src/schema/rules/files/raw/anat.yaml
+++ b/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
diff --git a/src/schema/rules/sidecars/anat.yaml b/src/schema/rules/sidecars/anat.yaml
index 61958ef461..0bd1527d80 100644
--- a/src/schema/rules/sidecars/anat.yaml
+++ b/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