From af6fe73133a6427fa195f071b187195f601d4111 Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Fri, 7 Apr 2023 21:10:19 +0200
Subject: [PATCH] [MISC] consistently list filename templates; `ext` -->
 `extension`; `_photo.jpg` --> `_photo.<extension>` (#1458)

* try file template fix

* <ext> -> <extension>; photo.jpg -> photo.<extension>

* suffix name template consistency

* add MEG appendix link crosstalk+calibration

* add physi+stim to motion in schema

* tracksys required for physi/stim

* tracksys is optional events+timeseries; fix inline filename template
---
 src/derivatives/common-data-types.md               |  2 +-
 src/derivatives/imaging.md                         |  2 +-
 src/derivatives/introduction.md                    |  2 +-
 .../electroencephalography.md                      |  4 ++--
 .../intracranial-electroencephalography.md         | 12 ++++++------
 .../magnetoencephalography.md                      | 14 ++++++++++----
 src/modality-specific-files/motion.md              |  5 +++--
 .../near-infrared-spectroscopy.md                  |  2 +-
 src/schema/rules/files/raw/task.yaml               | 10 +++++++++-
 9 files changed, 34 insertions(+), 19 deletions(-)

diff --git a/src/derivatives/common-data-types.md b/src/derivatives/common-data-types.md
index ea3c6a2e6e..cf149c42b6 100644
--- a/src/derivatives/common-data-types.md
+++ b/src/derivatives/common-data-types.md
@@ -181,7 +181,7 @@ Template:
 <pipeline_name>/
     sub-<label>/
         <datatype>/
-            <source_entities>[_space-<space>][_desc-<label>]_<suffix>.<ext>
+            <source_entities>[_space-<space>][_desc-<label>]_<suffix>.<extension>
 ```
 
 Data is considered to be *preprocessed* or *cleaned* if the data type of the input,
diff --git a/src/derivatives/imaging.md b/src/derivatives/imaging.md
index b80ab2c70b..b802d6c309 100644
--- a/src/derivatives/imaging.md
+++ b/src/derivatives/imaging.md
@@ -11,7 +11,7 @@ Template:
 <pipeline_name>/
     sub-<label>/
         <datatype>/
-            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<ext>
+            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
 ```
 
 Volumetric preprocessing does not modify the number of dimensions, and so
diff --git a/src/derivatives/introduction.md b/src/derivatives/introduction.md
index 9f1d66d436..fd103519cf 100644
--- a/src/derivatives/introduction.md
+++ b/src/derivatives/introduction.md
@@ -39,7 +39,7 @@ in [Derived dataset and pipeline description][derived-dataset-description].
     copy of that raw file.
 
 -   Each Derivatives filename MUST be of the form:
-    `<source_entities>[_keyword-<value>]_<suffix>.<ext>`
+    `<source_entities>[_keyword-<value>]_<suffix>.<extension>`
     (where `<value>` could either be an `<index>` or a `<label>` depending on
     the keyword; see [Definitions][definitions])
 
diff --git a/src/modality-specific-files/electroencephalography.md b/src/modality-specific-files/electroencephalography.md
index f2ede709b3..cf02e58fe2 100644
--- a/src/modality-specific-files/electroencephalography.md
+++ b/src/modality-specific-files/electroencephalography.md
@@ -421,7 +421,7 @@ voxels (starting from `[0, 0, 0]`).
 }
 ```
 
-## Landmark photos (`*_photo.jpg`)
+## Landmark photos (`*_photo.<extension>`)
 
 Photos of the anatomical landmarks and/or fiducials.
 
@@ -444,7 +444,7 @@ indicate acquisition of different photos of
 the same face (or other body part in different angles to show, for example, the
 location of the nasion (NAS) as opposed to the right periauricular point (RPA).
 
-### Example `*_photo.jpg`
+### Example `*_photo.<extension>`
 
 Picture of a NAS fiducial placed between the eyebrows, rather than at the
 actual anatomical nasion: `sub-0001_ses-001_acq-NAS_photo.jpg`
diff --git a/src/modality-specific-files/intracranial-electroencephalography.md b/src/modality-specific-files/intracranial-electroencephalography.md
index 41a05aea15..42d264464f 100644
--- a/src/modality-specific-files/intracranial-electroencephalography.md
+++ b/src/modality-specific-files/intracranial-electroencephalography.md
@@ -430,7 +430,7 @@ data.
 }
 ```
 
-## Photos of the electrode positions (`*_photo.jpg`)
+## Photos of the electrode positions (`*_photo.<extension>`)
 
 <!--
 This block generates a filename templates.
@@ -451,18 +451,18 @@ or entirely omitted prior to sharing, depending on obtained consent.
 If there are photos of the electrodes, the [`acq-<label>`](../appendices/entities.md#acq) entity should be specified
 with:
 
--   `*_photo.jpg` in case of an operative photo
+-   `*_photo.<extension>` in case of an operative photo
 
--   `*_acq-xray#_photo.jpg` in case of an x-ray picture
+-   `*_acq-xray#_photo.<extension>` in case of an x-ray picture
 
--   `*_acq-drawing#_photo.jpg` in case of a drawing or sketch of electrode
+-   `*_acq-drawing#_photo.<extension>` in case of a drawing or sketch of electrode
     placements
 
--   `*_acq-render#_photo.jpg` in case of a rendering
+-   `*_acq-render#_photo.<extension>` in case of a rendering
 
 The [`ses-<label>`](../appendices/entities.md#ses) entity may be used to specify when the photo was taken.
 
-### Example `*_photo.jpg`
+### Example `*_photo.<extension>`
 
 Example of the operative photo of ECoG electrodes (here is an annotated example in
 which electrodes and vasculature are marked, taken from Hermes et al.,
diff --git a/src/modality-specific-files/magnetoencephalography.md b/src/modality-specific-files/magnetoencephalography.md
index 9548f84ee3..c9826dc265 100644
--- a/src/modality-specific-files/magnetoencephalography.md
+++ b/src/modality-specific-files/magnetoencephalography.md
@@ -66,6 +66,12 @@ remember to list all files separately in `scans.tsv` and that the entries for th
 `acq_time` column in `scans.tsv` MUST all be identical, as described in
 [Scans file](../modality-agnostic-files.md#scans-file).
 
+The Neuromag/Elekta/Megin system may also produce datasets that require a set of
+`crosstalk` and `calibration` files to be used properly (see also filename templates above).
+Please refer to
+[Cross-talk and fine-calibration files](../appendices/meg-file-formats.md#cross-talk-and-fine-calibration-files)
+for more information on this detail.
+
 Another manufacturer-specific detail pertains to the KIT/Yokogawa/Ricoh system,
 which saves the MEG sensor coil positions in a separate file with two possible filename extensions  (`.sqd`, `.mrk`).
 For these files, the `markers` suffix MUST be used.
@@ -391,10 +397,10 @@ For more information on typical coordinate systems for MEG-MRI coregistration:
 or:
 [http://neuroimage.usc.edu/brainstorm/CoordinateSystems](http://neuroimage.usc.edu/brainstorm/CoordinateSystems)
 
-## Landmark photos (`*_photo.jpg`)
+## Landmark photos (`*_photo.<extension>`)
 
 Photos of the anatomical landmarks and/or head localization coils
-(`*_photo.jpg`)
+(`*_photo.<extension>`)
 
 <!--
 This block generates a filename templates.
@@ -416,14 +422,14 @@ The [`acq-<label>`](../appendices/entities.md#acq) entity can be used to indicat
 the same face (or other body part in different angles to show, for example, the
 location of the nasion (NAS) as opposed to the right periauricular point (RPA)).
 
-### Example `*_photo.jpg`
+### Example `*_photo.<extension>`
 
 Example of the NAS fiducial placed between the eyebrows, rather than at the
 actual anatomical nasion: `sub-0001_ses-001_acq-NAS_photo.jpg`
 
 ![placement of NAS fiducial](images/sub-0001_ses-001_acq-NAS_photo.jpg "placement of NAS fiducial")
 
-## Head shape and electrode description (`*_headshape.<ext>`)
+## Head shape and electrode description (`*_headshape.<extension>`)
 
 <!--
 This block generates a filename templates.
diff --git a/src/modality-specific-files/motion.md b/src/modality-specific-files/motion.md
index d72dc6e3b4..c10e4e8748 100644
--- a/src/modality-specific-files/motion.md
+++ b/src/modality-specific-files/motion.md
@@ -11,7 +11,7 @@ and can be used as helpful guidance when curating new datasets.
 {{ MACROS___make_filename_template(
 "raw",
 datatypes=["motion"],
-suffixes=["motion", "channels", "events"])
+suffixes=["motion", "events", "physio", "stim"])
 }}
 
 A wide variety of motion capture systems are used in human research, resulting in different proprietary data formats.
@@ -63,7 +63,8 @@ these time information MAY be stored in form of latencies to recording onset (fi
 If a system has uneven sampling rate behavior, the `LATENCY` channel can be used to share these information.
 
 To store events alongside motion data when there are multiple tracking systems simultaneously in use, it is RECOMMENDED to designate a tracking system to the events file.
-Such an events file name SHOULD include the `tracksys` key and looks like `sub-<label>[_ses-<label>]_task-<label>[_acq-<label>]_tracksys-<label>[_run-<index>]_events.tsv`.
+Such an events file name SHOULD include the `tracksys` key and looks like
+`sub-<label>[_ses-<label>]_task-<label>[_tracksys-<label>][_acq-<label>][_run-<index>]_events.tsv`.
 Event latencies can then be related to motion samples of multiple tracking systems also by using `acq_time` column entries in the `*_scans.tsv`.
 The same principle applies when the events file is saved alongside a simultaneously recorded non-motion data (for example EEG).
 
diff --git a/src/modality-specific-files/near-infrared-spectroscopy.md b/src/modality-specific-files/near-infrared-spectroscopy.md
index c7d6c69a55..ab9bf645e8 100644
--- a/src/modality-specific-files/near-infrared-spectroscopy.md
+++ b/src/modality-specific-files/near-infrared-spectroscopy.md
@@ -14,7 +14,7 @@ have been formatted using this specification and can be used for practical guida
 {{ MACROS___make_filename_template(
    "raw",
    datatypes=["nirs"],
-   suffixes=["nirs", "events", "channels", "optodes", "coordsystem", "physio", "stim"])
+   suffixes=["nirs", "events", "physio", "stim"])
 }}
 
 Only the *Shared Near Infrared Spectroscopy Format* ([SNIRF](https://github.com/fNIRS/snirf))
diff --git a/src/schema/rules/files/raw/task.yaml b/src/schema/rules/files/raw/task.yaml
index e68b6cc8b9..cda1e45dec 100644
--- a/src/schema/rules/files/raw/task.yaml
+++ b/src/schema/rules/files/raw/task.yaml
@@ -57,7 +57,7 @@ events__motion:
     - motion
   entities:
     $ref: rules.files.raw.task.events.entities
-    tracksys: required
+    tracksys: optional
 
 events__pet:
   $ref: rules.files.raw.task.events
@@ -98,6 +98,14 @@ timeseries__meg:
     $ref: rules.files.raw.task.timeseries.entities
     processing: optional
 
+timeseries__motion:
+  $ref: rules.files.raw.task.timeseries
+  datatypes:
+    - motion
+  entities:
+    $ref: rules.files.raw.task.timeseries.entities
+    tracksys: optional
+
 timeseries__pet:
   $ref: rules.files.raw.task.timeseries
   datatypes: