Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[ENH] Add Level objects to channels.json for motion #1591

Merged
merged 18 commits into from
Oct 25, 2023
Merged

[ENH] Add Level objects to channels.json for motion #1591

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
7417741
[FIX] move coordsys info to `channels.json`
JuliusWelzel Jun 8, 2023
94bcab6
Merge branch 'bids-standard:master' into master
JuliusWelzel Jun 8, 2023
40875ea
[FIX] naming of field in `channels.json`
JuliusWelzel Jun 23, 2023
8fa6e20
Merge branch 'bids-standard:master' into master
JuliusWelzel Jun 23, 2023
dcb450a
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Jun 23, 2023
86e3498
Merge branch 'master' into master
sappelhoff Jun 27, 2023
3ff382d
Merge branch 'bids-standard:master' into master
JuliusWelzel Jul 21, 2023
4b07b4b
fix linebreak
JuliusWelzel Jul 21, 2023
179c424
introduce `reference_frame` in channels chapter
JuliusWelzel Jul 21, 2023
c00d1c1
fix typo
JuliusWelzel Jul 21, 2023
950da0b
FIX: Escape asterisks
effigies Aug 22, 2023
d031fb5
FIX: Remove undefined fields from level descriptions
effigies Aug 22, 2023
7a0ef2e
ENH: Rewrite text paragraph as table
effigies Aug 22, 2023
ef1281e
ENH: Clean up wording about reference_frame
effigies Aug 22, 2023
3a59f6a
FIX: Drop "ReferenceFrame" from Description
effigies Aug 22, 2023
a0e2c18
FIX: Schema definition of reference_frame
effigies Aug 22, 2023
6ab3e00
STY: Satisfy linter
effigies Aug 22, 2023
4645fd1
Update src/schema/objects/columns.yaml
effigies Oct 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 67 additions & 28 deletions src/modality-specific-files/motion.md
View file
Open in desktop
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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -377,6 +377,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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions src/schema/rules/tabular_data/motion.yaml
View file
Open in desktop
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