Skip to content

Commit

Permalink
BEP029 Motion (spec) (#981)
Browse files Browse the repository at this point in the history 
* [ENH] init commit for the BEP029 specification

* [ENH] first complete draft of the BEP029 md

* [ENH] updated draft after discussion with Sein

* _tracksys key in _motion.tsv file name is required

* Modified initial section to match style of other extensions.

* Added field "MissingValues" in motion.json

* [FIX] 29-motion.md now checks

* 'STY: Fixed Markdown style'

* [FIX] typos

* [FIX] typos

* 'STY: Fixed Markdown style'

* 'STY: Fixed Markdown style'

* fetch upstream

* [ENH] init commit for the BEP029 specification

* [ENH] first complete draft of the BEP029 md

* [ENH] updated draft after discussion with Sein

* _tracksys key in _motion.tsv file name is required

* Modified initial section to match style of other extensions.

* Added field "MissingValues" in motion.json

* [FIX] 29-motion.md now checks

* 'STY: Fixed Markdown style'

* [FIX] Bring specification up to date with current BEP029 devs

* [STY] Fixed Markdown style

* [STY] Fixed Markdown Style

* [FIX] Bring specification up to date with current developments of BEP

* [FIX] adding latency and misc channel options

* [FIX] deleted *coordsys.json in example

* Update src/04-modality-specific-files/29-motion.md

Move SamplingFrequencyEffective closer to SamplingFrequency

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>

* Update src/04-modality-specific-files/29-motion.md

Delete SamplingFrequencyEffective from optional fields

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>

* [ADD] include review comments from @guiomar

* [FIX] minor updates after second review

* [ADD] Explanation for events file in motion data

* [FIX] include must be one of for various fields

* [STY] Fixed MD style

* [ENH] Bring BEP029 up to date

* [FIX] typo

* [STY & FIX] MD style and typos

* [STY] markdown style

* [STY] markdown style

* [FIX] minor changes

* [ADD] schema changes for MOTION-BEP

* Add quat_ prefix for quaternion components

For rotations represented in quaternions, use quat_ prefix for components for clarity

* Update quaternion components description

* Fix broken component table

* Added instruction for sharing quaternions.

* Modified text here and there

* [FIX] acceleration keyword in table

* [ADD] schema objects MOTION-BIDS

* [FIX] remove backslashes in MACRO object

* lint yml

* lint yml

* comment out entities with no definitions

* fix yml

* fix links

* use md and not html extension

* add motion page to config

* [ADD] channel objects for schema

* [ADD] POSChannelcount for motion sidecar

* Update src/modality-specific-files/motion.md

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>

* Update src/modality-specific-files/motion.md

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>

* Update src/modality-specific-files/motion.md

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>

* Update src/modality-specific-files/motion.md

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>

* Update src/modality-specific-files/motion.md

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>

* Update src/modality-specific-files/motion.md

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>

* whitespace, linebreaks, typos, et al

* [FIX] remove md tables and rely on schema objects

* [FIX] remove md tabels and fix schema objects

* [FIX] schema motion.yaml levels

* white spaces

* remove another whitespace

* [ENH] restructure sidecar according to @RemiGau

* fix false indent

* add new line at end of file

* fix schema key error

* fix false indent

* remove double entry and change name

* More detailed description of motion chantypes

* Remove double entry

* Capitalization & punctuation table content

* Wording change

* Correct text and refine time-synch paragraph

* Refine text

* More precise definition of term Euler angles

* Remove expression Tait-Bryan to avoid confusion

* Refine text

* component__channels->component

* fix typo

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

* add headings

* smaller fixes

* update channels example column order

* linting after merge

* fix backslashes

* more backslash fixes

* minor fixes

* Delete tables with redundant information

* Better define requirement levels

* Capitalize requirement keys

* Typo correction

* fix MD style (remark)

* Fix column order in text/table

* bring schema up to date to latest spec changes

* make TrackingSystemName optional

* remove hardcoded channels.tsv table

* fix typos

* Reorder entities in text

* each new sentence on new line

* Clarify TrackingSystemName json field usage

* Move tracksys entity up the file name

* Clarify multiple tracksys case

* Remove trailing space

* TMP: replace examples link (for community review)

* update syncronization paragraph

* fix typo

* fix wording

* Mention of BEP 029 changed to BIDS-motion

* Update src/modality-specific-files/near-infrared-spectroscopy.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* update contributor emojis

* Typo correction

* Update near-infrared-spectroscopy.md

* update channels type table

* misc fixes

---------

Co-authored-by: sjeung <seinjeung@gmail.com>
Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>
Co-authored-by: Remi Gau <remi_gau@hotmail.com>
Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
  • Loading branch information
@JuliusWelzel @sjeung
@guiomar @Remi-Gau @sappelhoff
5 people committed Mar 17, 2023
1 parent 8f21b45 commit 843f450
Show file tree
Hide file tree
Showing 22 changed files with 745 additions and 43 deletions.
1 change: 1 addition & 0 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ nav:
- Positron Emission Tomography: modality-specific-files/positron-emission-tomography.md
- Microscopy: modality-specific-files/microscopy.md
- Near-Infrared Spectroscopy: modality-specific-files/near-infrared-spectroscopy.md
- Motion: modality-specific-files/motion.md
- Derivatives:
- BIDS Derivatives: derivatives/introduction.md
- Common data types and metadata: derivatives/common-data-types.md
Expand Down
4 changes: 2 additions & 2 deletions src/appendices/contributors.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
- Andrew Jahn 📓
- Andrew Janke 📖💻
- Mainak Jas 📖💻
- Sein Jeung 📖
- Sein Jeung 📖💡
- Alexander Jones 💻🐛
- Tamás Józsa 📓
- Jakub Kaczmarzyk 📖🔧🚇
Expand Down Expand Up @@ -306,7 +306,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
- Brian A. Wandell 📖
- Hao Ting Wang 📖🐛
- Yuan Wang 💻
- Julius Welzel 📖
- Julius Welzel 📖💡
- Joseph Wexler 📖💡
- Kirstie Whitaker 📖💡🔍🤔📢💬
- Martin Wilson 📖
Expand Down
4 changes: 4 additions & 0 deletions src/introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,10 @@ For example:

- (publication forthcoming)

#### Motion

- (publication forthcoming)

### Research Resource Identifier (RRID)

BIDS has also a
Expand Down
202 changes: 202 additions & 0 deletions src/modality-specific-files/motion.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
# Motion

For information on how to cite this extension when referencing it in the context of the academic literature, please read [Citing BIDS](../introduction.md#citing-bids).

Motion datasets formatted using this specification are available on the
[BIDS examples repository](https://github.com/bids-standard/bids-examples#motion-datasets)
and can be used as helpful guidance when curating new datasets.

## Motion recording data

{{ MACROS___make_filename_template(
"raw",
datatypes=["motion"],
suffixes=["motion", "channels", "events"])
}}

A wide variety of motion capture systems are used in human research, resulting in different proprietary data formats.

This BIDS extension deals with common outputs from motion capture systems such as positions, orientations, or their time derivatives.

The extension is not limited to motion data in physical space but also encompasses simulated movement in virtual space, as far as these are comparable to movements in physical space.
Other dynamic objects than human body parts whose motion is tracked may as well be included as tracked objects.
This specification does not include raw camera footages (from camera-based or optical motion capture recordings), but includes the positions or orientations computed using such data.

In this specification, positions (and their time derivatives) are represented as Cartesian coordinates along up to three spatial axes,
and orientations (and their time derivatives) are represented as Euler angles.
However, to cover recordings from computer graphics applications (for example, virtual 3D motion or immersive virtual reality recording in physical space),
orientations are also allowed to be represented as [quaternions](https://en.wikipedia.org/wiki/Quaternion).

In this case, the quaternion channels can be distinguished from channels containing Euler angles based on the entries in columns `component` and `units` in the `*_channels.tsv` file.
See subsection on `Channels description` for further details.

Motion data from one tracking system MUST be stored in a single `*_motion.tsv` file.
A tracking system is defined as a group of motion channels that share hardware properties (the recording device) and software properties (the recording duration and number of samples).
For example, if the position time series of multiple optical markers is processed via one recording unit, this MAY be defined as a single tracking system.
Note that it is not uncommon to have multiple tracking systems to record at the same time.

Each tracking system MUST have its own `*_tracksys-<label>_motion.tsv` file, where `<label>` is a user-defined keyword to be used to identify each file belonging to a tracking system.
This is especially helpful when more than one tracking system is used.
Data from different tracking systems MUST be stored in different `*_tracksys-<label>_motion.tsv` files,
each of which is accompanied by `*_tracksys-<label>_motion.json` and `*_tracksys-<label>_channels.tsv` files.
Between `tracksys-<label>` entity and `*_motion.tsv`, `*_motion.json`, or `*_channels.tsv` suffixes, optional [`acq-<label>`](../appendices/entities.md#acq) or [`run-<index>`](../appendices/entities.md#run) entity MAY be inserted.

One column in the `*_tracksys-<label>_motion.tsv` file represents one data channel.
The ordering of columns MUST match the order of rows in the `*_channels.tsv` file for unambiguous assignment.
All relevant metadata about a tracking systems is stored in accompanying sidecar `*_tracksys-<label>_motion.json` file.

The source data from each tracking system in their original format, if different from `.tsv`,
can be stored in the [`/sourcedata` directory](../common-principles.md#source-vs-raw-vs-derived-data).
The original data format MAY hold more metadata than currently specified in the `*_motion.json` file.

When multiple tracking systems are used to record motion or motion capture is used alongside the recording of other BIDS modalities and recordings should be interpreted together,
it is adviced to provide a possibility to synchronize recordings.
The prefered way to do so is to use the acquisition time of the first data point of recordings and
to store this information in the `acq_time` column of the [`*_scans.tsv`](../modality-agnostic-files.md#scans-file) file.
The Note that the [BIDS date time format](../common-principles.md#units) allows optional fractional seconds, which SHOULD be used to maximize the precision of the syncronization.
Only if the precision of the synchronization is not high enough, the `*_events.tsv` file SHOULD be used to syncronize recordings.
In this file, the start- and stop time of the recording of a system are specified in relation to a system to synchronize with.
If more than two systems are to be synchronized, it is up to the user to indntify the "main" system.

In case a tracking system provides time information with every recorded sample,
these time information MAY be stored in form of latencies to recording onset (first sample) in the `*_motion.tsv` file.
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 simulatenously 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`.
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).

### Sidecar JSON (`*_motion.json`)

#### Task information

{{ MACROS___make_sidecar_table("motion.motionTaskInformation") }}

#### Hardware information

{{ MACROS___make_sidecar_table("motion.motionHardware") }}

#### Insitution information

{{ MACROS___make_sidecar_table("motion.motionInstitutionInformation") }}

#### Motion specific fields

Motion specific fields MUST be present:

{{ MACROS___make_sidecar_table("motion.motionRequired") }}

Motion specific fields SHOULD be present:

{{ MACROS___make_sidecar_table("motion.motionRecommended") }}

#### Example `*_tracksys-<label>_motion.json`

```JSON
{
"SamplingFrequency": 60,
"SamplingFrequencyEffective": 60.00197437,
"TaskName": "BIDS Motion fictive example",
"TrackingSystemName": "IMU Right Hand",
"TaskDescription": "walking and talking",
"InstitutionAddress": "Fictive address",
"InstitutionName": "Fictive Institution",
"MotionChannelCount": 18,
"RecordingDuration": 4667.641106,
"RotationRule": "right-hand",
"RotationOrder": "ZXY",
"SpatialAxes": "FRU",
"SubjectArtefactDescription": "n/a",
"TrackedPointsCount" : 2,
"ACCELChannelCount": 6,
"GYROChannelCount": 6,
"MAGNChannelCount": 6,
"Manufacturer": "BWSensing",
"ManufacturersModelName": "BW-IMU600",
}
```

In this example, the `*_motion.json` contains data from one tracking system consisting of two
[inertial measurement units (imu)](https://en.wikipedia.org/wiki/Motion_capture#Inertial_systems).
If there are additional tracking systems (for example [optical motion capture](https://en.wikipedia.org/wiki/Motion_capture#Optical_systems)),
data from these MUST be stored as separate files like `*_tracksys-omcA_motion.tsv` and `*_tracksys-omcB_motion.tsv`.
All specified tracking systems MAY share `tracked_point` defined in `*_channels.tsv`, when tracking devices are placed on the same object or body part.

Note that the onsets of the recordings SHOULD be stored in the study key file [(`scans.tsv`)](../modality-agnostic-files.md#scans-file).
Here, date-time information MUST be expressed as indicated in [Units](../common-principles.md#units).
The [`scans.tsv`](../modality-agnostic-files.md#scans-file) file contains the filename and the acquisition time of a recording,
which MAY be used to synchronize multiple recordings.

## Channels description (`*_channels.tsv`)

{{ MACROS___make_filename_template(
"raw",
datatypes=["motion"],
suffixes=["channels"])
}}

This file is REQUIRED as it makes it easy to browse or query over larger collections of datasets.
The REQUIRED columns are channel `name`, `component`, `type`, `tracked_point` and `units`.
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`.

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

{{ MACROS___make_columns_table("motion.motionChannels") }}

### Restricted keyword list for channel component

Restricted keyword list for column `component`.
When using quaternions to represent orientations,
the axial components that corresponds to the three spatial axes MUST be specified as "quat_x", "quat_y", "quat_z", and the non-axial component as "quat_w".

| **Keyword** | **Description** |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| x | Position along the X-axis, or rotation about the X-axis among the Euler angles that represent the orientation, or magnetic field strength along the X-axis. |
| y | Position along the Y-axis or rotation about the Y-axis among the Euler angles that represent the orientation, or magnetic field strength along the Y-axis. |
| z | Position along the Z-axis or rotation about the Z-axis among the Euler angles that represent the orientation, or magnetic field strength along the Z-axis. |
| quat_x | Quaternion component associated with the X-axis. |
| quat_y | Quaternion component associated with the Y-axis. |
| quat_z | Quaternion component associated with the Z-axis. |
| quat_w | Non-axial quaternion component. |
| n/a | Channels that have no corresponding spatial axis. |

### Restricted keyword list for channel type

Restricted keyword list for column `type` in alphabetic order.
Note that upper-case is REQUIRED:

| **Keyword** | **Description** | **Modalities to be shared with** |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 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). | [fNIRS](./near-infrared-spectroscopy.md#near-infrared-spectroscopy) |
| ANGACC | 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). | NONE |
| ANGVEL | Angular velocity channel, one channel for each spatial axis. Column `component` for the axis MUST be added to the `*_channels.tsv` file (x, y, or z). | None |
| 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). | [fNIRS](./near-infrared-spectroscopy.md#near-infrared-spectroscopy) |
| JNTANG | Joint angle channel between two fixed axis belonging to two bodyparts. Angle SHOULD be defined between proximal and distal bodypart in `deg`. | NONE |
| LATENCY | Latency of samples in seconds from recording onset. MUST be in form of `ss[.000000]` , where [.000000] is an optional subsecond resolution between 1 and 6 decimal points. | ALL |
| 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). | [fNIRS](./near-infrared-spectroscopy.md#near-infrared-spectroscopy) |
| MISC | Miscellaneous channels. | ALL |
| 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). | [fNIRS](./near-infrared-spectroscopy.md#near-infrared-spectroscopy) |
| 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). | NONE |
| 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). | NONE |

### 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
…
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
```
4 changes: 2 additions & 2 deletions src/modality-specific-files/near-infrared-spectroscopy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -197,10 +197,10 @@ and a guide for using macros can be found at
All NIRS channels types MUST correspond to a [valid SNIRF data type](https://github.com/fNIRS/snirf/blob/master/snirf_specification.md#appendix).
Additional channels that are recorded simultaneously with the NIRS
device and stored in the same data file SHOULD be included as well.
However, additional channels that are simultaneously recorded with a different device
However, additional channels that are simultaneously recorded with a different device
SHOULD be stored according to their appropriate modality specification.
For example, motion data that was simultaneously recorded with a different device should be specified
according to BEP029 and not according to the NIRS data type.
according to the [Motion](../modality-specific-files/motion.md) and not according to the NIRS data type.
Whereas, if the motion data was acquired in with the NIRS device itself, it should be included here with the NIRS data.
Any of the channel types defined in other BIDS specification MAY be used here as well such as `ACCEL` or `MAGN`.
As several of these data types are commonly acquired using NIRS devices they are included as an example at the base of the table.
Expand Down

0 comments on commit 843f450

Please sign in to comment.