[ENH] Propose to use *_channels.json for the description of coordinate systems

src/modality-specific-files/motion.md

@@ -105,9 +105,6 @@ Motion specific fields SHOULD be present:
  "InstitutionName": "Fictive Institution",
  "MotionChannelCount": 18,
  "RecordingDuration": 4667.641106,
- "RotationRule": "right-hand",
- "RotationOrder": "ZXY",
- "SpatialAxes": "FRU",
  "SubjectArtefactDescription": "n/a",
  "TrackedPointsCount" : 2,
  "ACCELChannelCount": 6,
@@ -142,6 +139,8 @@ The REQUIRED columns are channel `name`, `component`, `type`, `tracked_point` an
 Any number of additional columns MAY be added to provide additional information about the channels.
 The `*_tracksys-<label>_channels.tsv` file SHOULD give additional information about individual recorded channel,
 some of which my not be found summarized in `*_motion.json`.
+To store information about specific coordinate system information for a channel, we RECOMMEND to use the `reference_frame` column.
+A detailed description about the reference frame in which the data is to be interpreted, is described [here](./motion.md#reference-frame-description-_channelsjson).
 
 The columns of the channels description table stored in `*_channels.tsv` are:
 
@@ -185,18 +184,59 @@ Note that upper-case is REQUIRED:
 ### Example `*_channels.tsv`
 
 ```Text
-name        component   type   tracked_point   units
-t1_acc_x    x           ACCEL  LeftFoot        m/s^2
-t1_acc_y    y           ACCEL  LeftFoot        m/s^2
-t1_acc_z    z           ACCEL  LeftFoot        m/s^2
-t1_gyro_x   x           GYRO   LeftFoot        rad/s
-t1_gyro_y   y           GYRO   LeftFoot        rad/s
-t1_gyro_z   z           GYRO   LeftFoot        rad/s
+name        component   type   tracked_point   units    reference_frame
+t1_acc_x    x           ACCEL  LeftFoot        m/s^2    global
+t1_acc_y    y           ACCEL  LeftFoot        m/s^2    global
+t1_acc_z    z           ACCEL  LeftFoot        m/s^2    global
+t1_gyro_x   x           GYRO   LeftFoot        rad/s    global
+t1_gyro_y   y           GYRO   LeftFoot        rad/s    global
+t1_gyro_z   z           GYRO   LeftFoot        rad/s    global
 …
-t2_acc_x    x           ACCEL  RightWrist      m/s^2
-t2_acc_y    y           ACCEL  RightWrist      m/s^2
-t2_acc_z    z           ACCEL  RightWrist      m/s^2
-t2_gyro_x   x           GYRO   RightWrist      rad/s
-t2_gyro_y   y           GYRO   RightWrist      rad/s
-t2_gyro_z   z           GYRO   RightWrist      rad/s
+t2_acc_x    x           ACCEL  RightWrist      m/s^2    global
+t2_acc_y    y           ACCEL  RightWrist      m/s^2    global
+t2_acc_z    z           ACCEL  RightWrist      m/s^2    global
+t2_gyro_x   x           GYRO   RightWrist      rad/s    global
+t2_gyro_y   y           GYRO   RightWrist      rad/s    global
+t2_gyro_z   z           GYRO   RightWrist      rad/s    global
+```
+
+## Reference frame description (`*_channels.json`)
+
+A reference frame specifies the origin and orientation of the spatial axes with respect to which motion data is to be interpreted.
+In case the information is available, sharing this can immensely boost the usability of shared data.
+It is RECOMMENDED that the `*_channels.json` file contains information about the reference frames used for motion channels.
+When shared, it SHOULD be stored in field `reference_frame`.
+The defined levels are specified as user-defined keywords, which MUST match a value in the `reference_frame` colunm in the matching `*_channels.tsv` file.
+Nested under each level of `reference_frame` are three RECOMMENDED fields, namely `RotationRule`, `RotationOrder` and `SpatialAxes`.
+Field `RotationOrder` specifies the sequence in which the elemental 3D extrinsic rotations are applied around the three distinct axes.
+The value MUST be one of: "XYZ", "XZY", "YXZ", "YZX", "ZXY", "ZYX", or "n/a".
+Field `RotationRule` indicates whether rotations are applied clockwise around an axis when seen from the positive direction (left-hand rule) or counter-clockwise (right-hand rule). The value MUST be one of: "left-hand", "right-hand", or "n/a".
+Lastly, field `SpatialAxis` refers to the coordinate system in which the motion data are to be interpreted, if the recorded data can be mapped to a fixed reference frame.
+A sequence of characters A/P (anterior-posterior, indicating forward-backward), L/R (left-right), and S/I (superior-inferior, indicating up-down).
+The position of a character in the sequence determines which of the X,Y,Z axes it maps to. For example, "ARS" for X-anterior, Y-right, Z-superior.
+For 1D or 2D cases, only specify the used axes and use the character "_" for unused axes ("A_R" when the Y axis is not used, for instance).
+If non of these principals apply, a free-form field `Description` MAY be used for the definition.
+
+### Example of `*_channels.json`
+
+```json
+"reference_frame": {
+        "Levels": {
+            "global": {
+                "Description": "n/a",
+                "SpatialAxes": "ALS",
+                "RotationOrder": "ZXY",
+                "RotationRule": "right-hand"
+            },
+            "local": {
+                "Description": "Joint angles are described following the ISB-based coordinate system,
+                                                with a local reference frame attached to the body segment.
+                                                See Wu and Cavanagh (1995), Wu et al. (2002), Wu et al. (2005),
+                                                and the Xsens MVN Awinda user manual for more information.",
+                "SpatialAxes": "n/a",
+                "RotationOrder": "n/a",
+                "RotationRule": "n/a"
+            }
+        }
+    }
 ```

src/schema/objects/columns.yaml

@@ -380,6 +380,21 @@ reference__ieeg:
     - type: string
       enum:
         - n/a
+# reference frame column for channels.tsv files for motion data
+reference_frame__motion:
+  name: reference
+  display_name: Reference frame
+  description: |
+    Specification of a reference frame in which the motion data are to be interpreted.
+    The value MUST match any of used key-value pair in the `*_channels.json` file in the motion directory.
+    It is RECOMMENDED to use a meanigful combination of `RotationRule`, `RotationOrder`
+    and `SpatialAxis` for the specification.
+    If a channel is not to be interpreted in a reference frame use `n/a`.
+  anyOf:
+    - type: string
+    - type: string
+      enum:
+        - n/a
 respiratory:
   name: respiratory
   display_name: Respiratory measurement

src/schema/rules/sidecars/motion.yaml

@@ -66,13 +66,10 @@ motionRecommended:
     MotionChannelCount: recommended
     ORNTChannelCount: recommended
     POSChannelCount: recommended
-    RotationOrder: recommended
-    RotationRule: recommended
     SamplingFrequencyEffective:
       level: recommended
       description_addendum: |
         If not available, the field takes value `n/a`.
-    SpatialAxes: recommended
     SubjectArtefactDescription: recommended
     TrackedPointsCount: recommended
     TrackingSystemName: optional

src/schema/rules/tabular_data/motion.yaml

@@ -13,6 +13,7 @@ motionChannels:
   columns:
     name__channels: required
     component: required
+    reference_frame__motion: recommended
     type__channels: required
     tracked_point__channels: required
     units__motion: required