From 04c624ac9c3774ecac641a8ee48256f6246bd004 Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Tue, 30 Aug 2022 14:09:18 -0400
Subject: [PATCH 1/7] Start removing redundant entity definitions.

---
 .../01-magnetic-resonance-imaging-data.md     | 31 +------------------
 1 file changed, 1 insertion(+), 30 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 8275f98165..2b7eac185b 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -35,7 +35,7 @@ vendor and coil to define the "active" coil elements.
 Since individual scans can sometimes not have the intended coil elements selected,
 it is preferable for this field to be populated directly from the DICOM
 for each individual scan, so that it can be used as a mechanism for checking
-that a given scan was collected with the intended coil elements selected
+that a given scan was collected with the intended coil elements selected.
 
 ### Sequence Specifics
 
@@ -405,8 +405,6 @@ based fMRI a corresponding task events file (see below) MUST be provided
 multiband acquisitions, one MAY also save the single-band reference image as
 type `sbref` (for example, `sub-control01_task-nback_sbref.nii.gz`).
 
-Each [`task-<label>`](../99-appendices/09-entities.md#task) MUST be consistent across subjects and sessions.
-
 If more than one run of the same task has been acquired the
 [`run-<index>`](../99-appendices/09-entities.md#run) entity MUST be used:
 `_run-1`, `_run-2`, `_run-3`, and so on. If only one run was acquired the
@@ -414,33 +412,6 @@ If more than one run of the same task has been acquired the
 defined as the same task, but in some cases it can mean different set of stimuli
 (for example randomized order) and participant responses.
 
-The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq)
-entity corresponds to a custom label one may
-use to distinguish different set of parameters used for acquiring the same task.
-For example this should be used when a study includes two resting state images -
-one single band and one multiband. In such case two files could have the
-following names: `sub-01_task-rest_acq-singleband_bold.nii.gz` and
-`sub-01_task-rest_acq-multiband_bold.nii.gz`, however the user is MAY choose any
-other label than `singleband` and `multiband` as long as they are consistent
-across subjects and sessions and consist only of the legal label characters.
-
-Similarly the OPTIONAL [`ce-<label>`](../99-appendices/09-entities.md#ce)
-entity can be used to distinguish
-sequences using different contrast enhanced images. The label is the name of the
-contrast agent. The key "`ContrastBolusIngredient`" MAY be also be added in the JSON
-file, with the same label.
-
-Similarly the OPTIONAL [`rec-<label>`](../99-appendices/09-entities.md#rec)
-entity can be used to distinguish
-different reconstruction algorithms (for example ones using motion correction).
-
-Similarly the OPTIONAL [`dir-<label>`](../99-appendices/09-entities.md#dir)
-and [`rec-<label>`](../99-appendices/09-entities.md#rec) entities
-can be used to distinguish different phase-encoding directions and
-reconstruction algorithms (for example ones using motion correction).
-See [`fmap` Case 4](01-magnetic-resonance-imaging-data.md#case-4-multiple-phase-encoded-directions-pepolar)
-for more information on `dir` field specification.
-
 Multi-echo data MUST be split into one file per echo using the
 [`echo-<index>`](../99-appendices/09-entities.md#echo) entity. For example:
 

From ddb292e73925717d2978ac55b0e53cbb45cd7d9c Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Tue, 30 Aug 2022 14:39:08 -0400
Subject: [PATCH 2/7] Mention filename template links in legend.

---
 tools/schemacode/bidsschematools/render.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/tools/schemacode/bidsschematools/render.py b/tools/schemacode/bidsschematools/render.py
index 1ee8e7cb95..70d88c648a 100644
--- a/tools/schemacode/bidsschematools/render.py
+++ b/tools/schemacode/bidsschematools/render.py
@@ -477,7 +477,10 @@ def make_filename_template(
 
 
 def append_filename_template_legend(text, pdf_format=False):
+    """Append a legend to filename templates."""
     legend = """
+- For more information about filename elements (for example, entities, suffixes, extensions),
+  follow the links embedded in the filename template.
 - Filename entities or folders between square brackets
   (for example, `[_ses-<label>]`) are OPTIONAL.
 - Some entities may only allow specific values,

From 8363869d7c69dab4f455690e1b60182e155ec7ed Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Tue, 30 Aug 2022 14:39:15 -0400
Subject: [PATCH 3/7] Keep removing stuff.

---
 .../01-magnetic-resonance-imaging-data.md              | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 2b7eac185b..fc32883515 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -405,13 +405,6 @@ based fMRI a corresponding task events file (see below) MUST be provided
 multiband acquisitions, one MAY also save the single-band reference image as
 type `sbref` (for example, `sub-control01_task-nback_sbref.nii.gz`).
 
-If more than one run of the same task has been acquired the
-[`run-<index>`](../99-appendices/09-entities.md#run) entity MUST be used:
-`_run-1`, `_run-2`, `_run-3`, and so on. If only one run was acquired the
-`run-<index>` can be omitted. In the context of functional imaging a run is
-defined as the same task, but in some cases it can mean different set of stimuli
-(for example randomized order) and participant responses.
-
 Multi-echo data MUST be split into one file per echo using the
 [`echo-<index>`](../99-appendices/09-entities.md#echo) entity. For example:
 
@@ -470,8 +463,7 @@ A guide for using macros can be found at
    }
 ) }}
 
-Some meta information about the acquisition MUST be provided in an additional
-JSON file.
+Some meta information about the acquisition MUST be provided in an additional JSON file.
 
 ### Required fields
 

From 8e5f7969ea4f2c094fe833c61079c8741f4f0b7f Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Tue, 30 Aug 2022 14:39:59 -0400
Subject: [PATCH 4/7] More cleanup.

---
 .../01-magnetic-resonance-imaging-data.md     | 42 +++----------------
 1 file changed, 5 insertions(+), 37 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index fc32883515..b0e2f07d1f 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -207,37 +207,6 @@ entity corresponds to modality suffix,
 such as `T1w` or `inplaneT1`, referenced by the defacemask image.
 For example, `sub-01_mod-T1w_defacemask.nii.gz`.
 
-If several scans with the same acquisition parameters are acquired in the same session,
-they MUST be indexed with the [`run-<index>`](../99-appendices/09-entities.md#run) entity:
-`_run-1`, `_run-2`, `_run-3`, and so on (only nonnegative integers are allowed as
-run labels).
-
-If different entities apply,
-such as a different session indicated by [`ses-<label>`](../99-appendices/09-entities.md#ses),
-or different acquisition parameters indicated by
-[`acq-<label>`](../99-appendices/09-entities.md#acq),
-then `run` is not needed to distinguish the scans and MAY be omitted.
-
-The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq)
-entity corresponds to a custom label the user
-MAY use to distinguish a different set of parameters used for acquiring the same
-modality. For example this should be used when a study includes two T1w images -
-one full brain low resolution and one restricted field of view but high
-resolution. 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.
-
-Similarly the OPTIONAL [`ce-<label>`](../99-appendices/09-entities.md#ce)
-entity can be used to distinguish
-sequences using different contrast enhanced images. The label is the name of the
-contrast agent. The key `ContrastBolusIngredient` MAY be also be added in the
-JSON file, with the same label.
-
 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
@@ -398,12 +367,11 @@ and a guide for using macros can be found at
 {{ MACROS___make_filename_template(datatypes=["func"]) }}
 
 Functional imaging consists of techniques that support rapid temporal repetition.
-This includes but is not limited to task based fMRI
-as well as resting state fMRI, which is treated like any other task. For task
-based fMRI a corresponding task events file (see below) MUST be provided
-(please note that this file is not necessary for resting state scans). For
-multiband acquisitions, one MAY also save the single-band reference image as
-type `sbref` (for example, `sub-control01_task-nback_sbref.nii.gz`).
+This includes, but is not limited to, task based fMRI, as well as resting state fMRI, which is treated like any other task.
+For task based fMRI, a corresponding task events file (see below) MUST be provided
+(please note that this file is not necessary for resting state scans).
+For multiband acquisitions, one MAY also save the single-band reference image with the `sbref` suffix
+(for example, `sub-control01_task-nback_sbref.nii.gz`).
 
 Multi-echo data MUST be split into one file per echo using the
 [`echo-<index>`](../99-appendices/09-entities.md#echo) entity. For example:

From 27b610b5da80e13356c63adfe4305c20a82a86a9 Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Tue, 30 Aug 2022 14:51:29 -0400
Subject: [PATCH 5/7] Keep removing extra entity mentions.

---
 .../01-magnetic-resonance-imaging-data.md     | 30 ++-----------------
 1 file changed, 3 insertions(+), 27 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index b0e2f07d1f..c71f7eb389 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -574,25 +574,9 @@ and a guide for using macros can be found at
 -->
 {{ MACROS___make_filename_template(datatypes=["dwi"]) }}
 
-If more than one run of the same acquisition and direction has been acquired, the
-[`run-<index>`](../99-appendices/09-entities.md#run) entity MUST be used:
-`_run-1`, `_run-2`, `_run-3` (and so forth.)
-When there is only one scan of a given acquisition and direction, the `run` entity MAY be
-omitted.
 The [`run-<index>`](../99-appendices/09-entities.md#run) entity is RECOMMENDED
-to encode the splits of multipart DWI scans (see [below](#multipart-split-dwi-schemes).)
-
-The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq)
-entity corresponds to a custom label the user may use to
-distinguish different sets of parameters.
-
-The OPTIONAL [`rec-<label>`](../99-appendices/09-entities.md#rec)
-key/value pair can be used to distinguish
-different pre-dicom reconstruction algorithms (for example one using sum of squares or another using a non-linear combination of the coils).
-
-The OPTIONAL [`dir-<label>`](../99-appendices/09-entities.md#dir)
-entity corresponds to a custom label the user may use to
-distinguish different sets of phase-encoding directions.
+to encode the splits of multipart DWI scans
+(see [below](#multipart-split-dwi-schemes) for more information on multipart DWI schemes).
 
 **Combining multi- and single-band acquisitions**.
 The single-band reference image MAY be stored with suffix `sbref` (for example,
@@ -968,15 +952,6 @@ and a guide for using macros can be found at
    )
 }}
 
-Two OPTIONAL entities, following more general rules of the specification,
-are allowed across all the four scenarios:
-
--   The OPTIONAL [`run-<index>`](../99-appendices/09-entities.md#run) entity corresponds to a one-based index
-    to distinguish multiple fieldmaps with the same parameters.
-
--   The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) entity corresponds to a custom label
-    the user may use to distinguish different set of parameters.
-
 ### Expressing the MR protocol intent for fieldmaps
 
 Fieldmaps are typically acquired with the purpose of correcting one or more EPI
@@ -1109,6 +1084,7 @@ For example, `sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.json`
 ```
 
 #### Case 3: Direct *field mapping*
+
 In some cases (for example GE), the scanner software will directly reconstruct a
 *B<sub>0</sub>* field map along with a magnitude image used for anatomical reference.
 

From d19ac33687a3040f6d2d5a7b381ff1bc8146ca1f Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Wed, 31 Aug 2022 11:48:03 -0400
Subject: [PATCH 6/7] Make element link info dependent on pdf build.

---
 tools/schemacode/bidsschematools/render.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/tools/schemacode/bidsschematools/render.py b/tools/schemacode/bidsschematools/render.py
index 70d88c648a..95c0bfc78d 100644
--- a/tools/schemacode/bidsschematools/render.py
+++ b/tools/schemacode/bidsschematools/render.py
@@ -478,9 +478,15 @@ def make_filename_template(
 
 def append_filename_template_legend(text, pdf_format=False):
     """Append a legend to filename templates."""
-    legend = """
+    if pdf_format:
+        info_str = ""
+    else:
+        info_str = """
 - For more information about filename elements (for example, entities, suffixes, extensions),
   follow the links embedded in the filename template.
+  """
+
+    legend = f"""{info_str}
 - Filename entities or folders between square brackets
   (for example, `[_ses-<label>]`) are OPTIONAL.
 - Some entities may only allow specific values,

From 8b0fc32d034c5d4b3a897556a6d117f66ec152d5 Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Wed, 31 Aug 2022 13:25:29 -0400
Subject: [PATCH 7/7] Update test_render.py

---
 tools/schemacode/bidsschematools/tests/test_render.py | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/tools/schemacode/bidsschematools/tests/test_render.py b/tools/schemacode/bidsschematools/tests/test_render.py
index cab6113f5b..a06f37b0f7 100644
--- a/tools/schemacode/bidsschematools/tests/test_render.py
+++ b/tools/schemacode/bidsschematools/tests/test_render.py
@@ -250,3 +250,14 @@ def test_define_common_principles(schema_obj):
     assert isinstance(common_principles_str, str)
     # Must be fairly long
     assert len(common_principles_str) > 100
+
+
+def test_append_filename_template_legend():
+    """Check contents of generated string."""
+    test_str = render.append_filename_template_legend("", pdf_format=False)
+    assert isinstance(test_str, str)
+    assert "follow the links" in test_str
+
+    test_str = render.append_filename_template_legend("", pdf_format=True)
+    assert isinstance(test_str, str)
+    assert "follow the links" not in test_str