Skip to content

Commit

Permalink
[ENH] Add Level objects to channels.json for motion (#1591)
Browse files Browse the repository at this point in the history 
* [FIX] move coordsys info to `channels.json`

* [FIX] naming of field in `channels.json`

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix linebreak

* introduce `reference_frame` in channels chapter

* fix typo

* FIX: Escape asterisks

* FIX: Remove undefined fields from level descriptions

* ENH: Rewrite text paragraph as table

* ENH: Clean up wording about reference_frame

* FIX: Drop "ReferenceFrame" from Description

* FIX: Schema definition of reference_frame

* STY: Satisfy linter

* Update src/schema/objects/columns.yaml

Co-authored-by: Stefan Appelhoff <[email protected]>

---------

Co-authored-by: Julius Welzel <[email protected]>
Co-authored-by: jwelzel <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Stefan Appelhoff <[email protected]>
  • Loading branch information
@effigies @JuliusWelzel
@pre-commit-ci @sappelhoff
5 people authored Oct 25, 2023
1 parent 405b053 commit efbe6ab
Show file tree
Hide file tree
Showing 4 changed files with 80 additions and 31 deletions.
95 changes: 67 additions & 28 deletions src/modality-specific-files/motion.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -142,6 +139,9 @@ 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 reference frames for a channel, the `reference_frame` column SHOULD
be used
(see [Reference frame description (`*_channels.json`)](#reference-frame-description-_channelsjson)).

The columns of the channels description table stored in `*_channels.tsv` are:

Expand Down Expand Up @@ -169,34 +169,73 @@ the axial components that corresponds to the three spatial axes MUST be specifie
Restricted keyword list for column `type` in alphabetic order.
Note that upper-case is REQUIRED:

| **Keyword** | **Description** |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ACCEL | Accelerometer channel, one channel for each spatial axis. Column component for the axis MUST be added to the *_channels.tsv file (x, y, or z). |
| ANGACCEL | Angular acceleration channel, one channel for each spatial axis. Column component for the axis MUST be added to the *_channels.tsv file (x, y, or z). |
| GYRO | Gyrometer channel, one channel for each spatial axis. Column component for the axis MUST be added to the *_channels.tsv file (x, y, or z). |
| JNTANG | Joint angle channel between two fixed axis belonging to two bodyparts. Angle SHOULD be defined between proximal and distal bodypart in deg. |
| LATENCY | Latency of samples in seconds from recording onset (see `acq_time` column of the respective `*_scans.tsv` file). MUST be in form of `s[.000000]`, where `s` reflects whole seconds, and `.000000` reflects OPTIONAL fractional seconds. |
| MAGN | Magnetic field strength, one channel for each spatial axis. Column component for the axis MUST be added to the *_channels.tsv file (x, y or z). |
| MISC | Miscellaneous channels. |
| ORNT | Orientation channel, one channel for each spatial axis or quaternion component. Column component for the axis or quaternion label MUST be added to the *_channels.tsv file (x, y, z, quat_x, quat_y, quat_z, or quat_w). |
| POS | Position in space, one channel for each spatial axis. Column component for the axis MUST be added to the *_channels.tsv file (x, y or z). |
| VEL | Velocity, one channel for each spatial axis. Column component for the axis MUST be added to the *_channels.tsv file (x, y or z). |
| **Keyword** | **Description** |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ACCEL | Accelerometer channel, one channel for each spatial axis. Column component for the axis MUST be added to the `*_channels.tsv` file (x, y, or z). |
| ANGACCEL | Angular acceleration channel, one channel for each spatial axis. Column component for the axis MUST be added to the `*_channels.tsv` file (x, y, or z). |
| GYRO | Gyrometer channel, one channel for each spatial axis. Column component for the axis MUST be added to the `*_channels.tsv` file (x, y, or z). |
| JNTANG | Joint angle channel between two fixed axis belonging to two bodyparts. Angle SHOULD be defined between proximal and distal bodypart in deg. |
| LATENCY | Latency of samples in seconds from recording onset (see `acq_time` column of the respective `*_scans.tsv` file). MUST be in form of `s[.000000]`, where `s` reflects whole seconds, and `.000000` reflects OPTIONAL fractional seconds. |
| MAGN | Magnetic field strength, one channel for each spatial axis. Column component for the axis MUST be added to the `*_channels.tsv` file (x, y or z). |
| MISC | Miscellaneous channels. |
| ORNT | Orientation channel, one channel for each spatial axis or quaternion component. Column component for the axis or quaternion label MUST be added to the `*_channels.tsv` file (`x`, `y`, `z`, `quat_x`, `quat_y`, `quat_z`, or `quat_w`). |
| POS | Position in space, one channel for each spatial axis. Column component for the axis MUST be added to the `*_channels.tsv` file (x, y or z). |
| VEL | Velocity, one channel for each spatial axis. Column component for the axis MUST be added to the `*_channels.tsv` file (x, y or z). |

### 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.
The description of the `reference_frame` column SHOULD use the `"Levels"`
field to describe the named field using [objects][object] with following fields.

| Key name | Requirement Level | Data type | Description |
|---------------|--------------------------------------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| RotationOrder | RECOMMENDED | [string][] | The sequence in which the extrinsic rotations are applied around the three axes. One of `"XYZ"`, `"XZY"`, `"YXZ"`, `"YZX"`, `"ZXY"`, or `"ZYX"`. |
| RotationRule | RECOMMENDED | [string][] | The direction of rotation around each axis. One of `"left-hand"` or `"right-hand"`. |
| SpatialAxes | RECOMMENDED | [string][] | The coordinate system in which the motion data are to be interpreted. A sequence of characters from the set `{'A', 'P', 'L', 'R', 'S', 'I', '_'}` indicating the direction of each axis. For example `"ARS"` indicates positive values in the X, Y, Z axes are respectively anterior, right, and superior of the origin, while `"PLI"` indicates positive values are posterior, left, and inferior of the origin. The `"_"` character may be used for unused axes. |
| Description | OPTIONAL, but RECOMMENDED if no other keys are present | [string][] | A description of the `reference_frame` |

### Example of `*_channels.json`

```json
{
"reference_frame": {
"Levels": {
"global": {
"SpatialAxes": "ALS",
"RotationOrder": "ZXY",
"RotationRule": "right-hand"
},
"local": {
"Description": "Joint angles are described following [...]"
}
}
}
}
```

<!-- Link Definitions -->

[object]: https://www.json.org/json-en.html

[string]: https://www.w3schools.com/js/js_json_datatypes.asp
12 changes: 12 additions & 0 deletions src/schema/objects/columns.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -378,6 +378,18 @@ reference__ieeg:
- type: string
enum:
- n/a
reference_frame:
name: reference_frame
display_name: Reference frame
description: |
Specification of a reference frame in which the motion data are to be interpreted.
The description of the levels in `*_channels.json` SHOULD use `RotationRule`,
`RotationOrder`, and `SpatialAxis`, and MAY use `Description` for the specification.
anyOf:
- type: string
- type: string
enum:
- n/a
respiratory:
name: respiratory
display_name: Respiratory measurement
Expand Down
3 changes: 0 additions & 3 deletions src/schema/rules/sidecars/motion.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions src/schema/rules/tabular_data/motion.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ motionChannels:
tracked_point__channels: required
units__motion: required
placement__motion: recommended
reference_frame: recommended
description: optional
sampling_frequency: optional
status: optional
Expand Down

0 comments on commit efbe6ab

Please sign in to comment.