From 741774106cc7a38cbc272e1504d76a1d80d5dca0 Mon Sep 17 00:00:00 2001 From: Julius Welzel Date: Thu, 8 Jun 2023 08:52:10 +0200 Subject: [PATCH 01/14] [FIX] move coordsys info to `channels.json` --- src/modality-specific-files/motion.md | 35 +++++++++++++++++++++-- src/schema/objects/columns.yaml | 14 +++++++++ src/schema/rules/sidecars/motion.yaml | 3 -- src/schema/rules/tabular_data/motion.yaml | 1 + 4 files changed, 47 insertions(+), 6 deletions(-) diff --git a/src/modality-specific-files/motion.md b/src/modality-specific-files/motion.md index 1c83de6fe0..cea2017c30 100644 --- a/src/modality-specific-files/motion.md +++ b/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, @@ -200,3 +197,35 @@ t2_gyro_x x GYRO RightWrist rad/s t2_gyro_y y GYRO RightWrist rad/s t2_gyro_z z GYRO RightWrist rad/s ``` + +## Reference frame description (`*_channels.json`) + +It is RECOMMENDED that the `*_channels.json` file contains additional metadata about channel which cannot be found in the `*_channels.tsv` or `*_motion.json` file. +One RECOMMENDED use case is the information about the reference frame the data is to be interpreted in. +The definition SHOULD be stored in a field called `reference_frame`, the defined level CAN be matched to a value in the `reference_frame` colunm in the `*_channels.tsv` file. +The use of a meanigful combination of `RotationRule`, `RotationOrder` and `SpatialAxis` for this definition is RECOMMENDED. +If non of these principals apply for the motion data, it is RECOMMENDED to use a free form field `CoordinateSystemDescription` for the definition. + +### Example of `*_channels.json` + +```json +"reference_frame": { + "Levels": { + "global": { + "CoordinateSystemDescription": "n/a", + "SpatialAxes": "ALS", + "RotationOrder": "ZXY", + "RotationRule": "right-hand" + }, + "local": { + "CoordinateSystemDescription": "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" + } + } + } +``` diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml index b4b32c41a5..1670ebbeb7 100644 --- a/src/schema/objects/columns.yaml +++ b/src/schema/objects/columns.yaml @@ -377,6 +377,20 @@ 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 diff --git a/src/schema/rules/sidecars/motion.yaml b/src/schema/rules/sidecars/motion.yaml index 981e0b3ad7..3746c3f5f0 100644 --- a/src/schema/rules/sidecars/motion.yaml +++ b/src/schema/rules/sidecars/motion.yaml @@ -71,13 +71,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 diff --git a/src/schema/rules/tabular_data/motion.yaml b/src/schema/rules/tabular_data/motion.yaml index 58fbec72f9..8f60e57527 100644 --- a/src/schema/rules/tabular_data/motion.yaml +++ b/src/schema/rules/tabular_data/motion.yaml @@ -13,6 +13,7 @@ motionChannels: columns: name__channels: required component: required + reference_frame__motion: recommended type__motion_channels: required tracked_point__channels: required units__motion: required From 40875eac9c4f34c1354ba0fe5e834f45567a9921 Mon Sep 17 00:00:00 2001 From: Julius Welzel Date: Fri, 23 Jun 2023 15:10:36 +0200 Subject: [PATCH 02/14] [FIX] naming of field in `channels.json` --- src/modality-specific-files/motion.md | 49 ++++++++++++++++----------- 1 file changed, 29 insertions(+), 20 deletions(-) diff --git a/src/modality-specific-files/motion.md b/src/modality-specific-files/motion.md index cea2017c30..5b9283ce62 100644 --- a/src/modality-specific-files/motion.md +++ b/src/modality-specific-files/motion.md @@ -182,29 +182,38 @@ 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`) -It is RECOMMENDED that the `*_channels.json` file contains additional metadata about channel which cannot be found in the `*_channels.tsv` or `*_motion.json` file. -One RECOMMENDED use case is the information about the reference frame the data is to be interpreted in. -The definition SHOULD be stored in a field called `reference_frame`, the defined level CAN be matched to a value in the `reference_frame` colunm in the `*_channels.tsv` file. -The use of a meanigful combination of `RotationRule`, `RotationOrder` and `SpatialAxis` for this definition is RECOMMENDED. -If non of these principals apply for the motion data, it is RECOMMENDED to use a free form field `CoordinateSystemDescription` for the definition. +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 `ReferenceFrameDescription` MAY be used for the definition. ### Example of `*_channels.json` @@ -212,13 +221,13 @@ If non of these principals apply for the motion data, it is RECOMMENDED to use a "reference_frame": { "Levels": { "global": { - "CoordinateSystemDescription": "n/a", + "ReferenceFrameDescription": "n/a", "SpatialAxes": "ALS", "RotationOrder": "ZXY", "RotationRule": "right-hand" }, "local": { - "CoordinateSystemDescription": "Joint angles are described following the ISB-based coordinate system, + "ReferenceFrameDescription": "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.", From dcb450abf8f248071b05ce6aa4293e153335309f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 23 Jun 2023 13:18:43 +0000 Subject: [PATCH 03/14] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- src/modality-specific-files/motion.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/modality-specific-files/motion.md b/src/modality-specific-files/motion.md index 5b9283ce62..1f4213ac96 100644 --- a/src/modality-specific-files/motion.md +++ b/src/modality-specific-files/motion.md @@ -227,9 +227,9 @@ If non of these principals apply, a free-form field `ReferenceFrameDescription` "RotationRule": "right-hand" }, "local": { - "ReferenceFrameDescription": "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), + "ReferenceFrameDescription": "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", From 4b07b4b4bba61f74feb5533eb8de947b7793e958 Mon Sep 17 00:00:00 2001 From: Julius Welzel Date: Fri, 21 Jul 2023 14:48:27 +0200 Subject: [PATCH 04/14] fix linebreak --- src/schema/objects/columns.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml index 136f169949..b96b4dff35 100644 --- a/src/schema/objects/columns.yaml +++ b/src/schema/objects/columns.yaml @@ -384,7 +384,8 @@ reference_frame__motion: 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. + 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 From 179c4248206958a612f259b51bf0f21c5e0e326b Mon Sep 17 00:00:00 2001 From: Julius Welzel Date: Fri, 21 Jul 2023 15:21:01 +0200 Subject: [PATCH 05/14] introduce `reference_frame` in channels chapter --- src/modality-specific-files/motion.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/modality-specific-files/motion.md b/src/modality-specific-files/motion.md index ae6c6df2e0..fb5d4f7377 100644 --- a/src/modality-specific-files/motion.md +++ b/src/modality-specific-files/motion.md @@ -139,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-