[ENH] Remove redundant entity definitions on MRI page (#1265)

* Start removing redundant entity definitions.

* Mention filename template links in legend.

* Keep removing stuff.

* More cleanup.

* Keep removing extra entity mentions.

* Make element link info dependent on pdf build.

* Update test_render.py

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
 
@@ -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,48 +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`).
-
-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
-`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.
-
-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.
+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:
@@ -499,8 +431,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
 
@@ -643,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,
@@ -1037,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
@@ -1178,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.
 

tools/schemacode/bidsschematools/render.py

@@ -479,7 +479,16 @@ def make_filename_template(
 
 
 def append_filename_template_legend(text, pdf_format=False):
- legend = """
+ """Append a legend to filename templates."""
+ 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,

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