Usage

There are three primary inputs to the hbcd_motion_postproc tool.

In each case, the input is provided as a “study-wide” folder, such that the tool can be run on multiple subjects at once. These three inputs include the BIDS directory, the output directory, and the analysis level (e.g., participant).

At the time this application is run, there should be subject (and session, if desired) specific folders for each subject you want to process.

Processing will iterate through each subject in the BIDS directory, find associated sessions with the relevant data, and create the necessary folders and files in the output directory.

Processing is totally independent across subjects and sessions, so that the results will be the same if the subjects are processed in parallel or through a single call of this applcation.

The application assumes data prepared following motion-BIDS. For more details on the extension, see the linked documentation.

As described in the installation section, this tool is meant to be interacted with in containerized form. The example below shows the general layout for how you may want to interact with the container to conduct processing if you have the Singularity container:

bids_dir=/path/to/bids_dir
output_dir=/path/to/output_dir
container=/path/to/container
analysis_level=participant

singularity run -B $bids_dir:/bids \
-B $output_dir:/out \
$container /bids /out $analysis_level

If you use Docker instead, where you save the processing output will be limited. Use the following command to interactively run the container:

docker run -it -v $bids_dir:/bids_dir \
inclab/hbcd_motion_postproc:<version_num> \
/bids_dir /bids_dir/<output_dir_name> \
$analysis_level

where version_num is the specific tag of the image you pulled, and output_dir_name is the name of the folder where processing output will be stored. For both options, refer to Execute HBCD-motion to learn more.

To see more specific information about how this tool expects the inputs to be formatted (i.e. file naming conventions), see Data inputs to the container: raw BIDS files.

Command-Line Arguments

Data files (.tsv) in bids_dir will be analyzed and the outputs are stored in output_dir. participant_label and session_id can be provided to process specific participant / session data. For other arguments, unless a default value is set, all possible choices will be processed.

usage: hbcd_motion_postproc [-h] [--participant_label PARTICIPANT_LABEL]
                            [--session_id SESSION_ID]
                            [--interval {raw,corrected}]
                            [--pa_measure {acceleration,jerk}]
                            [--pa_side {Left,L,Right,R}]
                            [--entropy_type {SampEn,FuzzEn}]
                            [--entropy_measure {avgacc,pkacc}]
                            [--stop_on_error]
                            bids_dir output_dir analysis_level

Positional Arguments

bids_dir

The path to the BIDS directory for your study (this is the same for all subjects)

output_dir

The path to the folder where outputs will be stored (this is the same for all subjects)

analysis_level

Should always be participant

Named Arguments

--participant_label, --participant-label

(optional) The label of the subject to be processed (ex. sub-XXXXX)

--session_id, --session-id

(optional) The label of the session to be processed (ex. ses-V02)

--interval

Possible choices: raw, corrected

(optional) The label to correct or not the uneven sampling interval

Default: 'raw'

--pa_measure, --pa-measure

Possible choices: acceleration, jerk

(optional) The computedQttyOption value

--pa_side, --pa-side

Possible choices: Left, L, Right, R

(optional) which leg to calculate the physical activity level

--entropy_type, --entropy-type

Possible choices: SampEn, FuzzEn

(optional) Entropy type

--entropy_measure, --entropy-measure

Possible choices: avgacc, pkacc

(optional) Measure to calculate an entropy

--stop_on_error, --stop-on-error

(optional) If activated, the code will try to exit if an error is encountered.

Default: False

Prepared by Jinseok Oh, Ph.D.