Usage Notes

Execution and the BIDS format

The bidsMReye workflow takes as principal input the path of the dataset that is to be processed.

The common parts of the command follow the BIDS-Apps definition. Example:

bidsmreye data/bids_root/ out/ participant

Further information about BIDS and BIDS-Apps can be found at the NiPreps portal.

Command-Line Arguments

BIDS app using deepMReye to decode eye motion for fMRI time series data.

usage: bidsmreye [-h] [--version]
                 bids_dir output_dir {participant,group}
                 {prepare,generalize,all,qc} ...

Positional Arguments

bids_dir

Fullpath to the directory with the input dataset formatted according to the BIDS standard. The dataset should contain ‘minimally processed’ (meaning at least ‘realigned’). The output of fMRIprep or bidspm should be acceptable inputs.

For “qc”, this lust be the fullpath to the directory with the output generated by bidsmreye that should be quality controlled.

output_dir

Fullpath to the directory where the output files will be stored.

analysis_level

Possible choices: participant, group

Level of the analysis that will be performed. Multiple participant level analyses can be run independently (in parallel) using the same output_dir.

Default: 'participant'

command

Possible choices: prepare, generalize, all, qc

Choose a subcommand

Named Arguments

--version: show program’s version number and exit

Sub-commands

prepare

Preprocessing data for classification. Extract the data coming from the eyes from the fMRI images. If your data is not in MNI space, bidsmreye will also register the data to MNI.

bidsmreye prepare [-h]
                  [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                  [--task TASK [TASK ...]] [--run RUN [RUN ...]]
                  [--space SPACE [SPACE ...]] [-v] [--debug]
                  [--reset_database] [--bids_filter_file BIDS_FILTER_FILE]
                  [--force] [--linear_coreg]

Named Arguments

--participant_label

The label(s) of the participant(s) that should be analyzed. The label corresponds to sub-<participant_label> from the BIDS spec (so it does not include “sub-“).

If this parameter is not provided, all subjects will be analyzed. Multiple participants can be specified with a space separated list.

--task

The label of the task that will be analyzed.

The label corresponds to task-<task_label> from the BIDS spec so it does not include “task-“).

--run

The label of the run that will be analyzed.

The label corresponds to run-<task_label> from the BIDS spec so it does not include “run-“).

--space

The label of the space that will be analyzed.

The label corresponds to space-<space_label> from the BIDS spec (so it does not include “space-“).

-v, --verbose

--debug

Switch to debug mode

Default: False

--reset_database

Resets the database of the input dataset.

Default: False

--bids_filter_file

A JSON file describing custom BIDS input filters using PyBIDS. For further details, please check out TBD.

--force

Overwrite previous output.

Default: False

--linear_coreg

Uses a less aggressive (and linear) alignment procedure to the deepmreye template.

May lead to worse results so check your outputs.

Default: False

generalize

Run classification. Use the extracted timeseries to predict the eye movements using the default pre-trained model of deepmreye.

bidsmreye generalize [-h]
                     [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                     [--task TASK [TASK ...]] [--run RUN [RUN ...]]
                     [--space SPACE [SPACE ...]] [-v] [--debug]
                     [--reset_database] [--bids_filter_file BIDS_FILTER_FILE]
                     [--force]
                     [--model {1_guided_fixations,2_pursuit,3_openclosed,3_pursuit,4_pursuit,5_free_viewing,1to5,1to6}]

Named Arguments

--participant_label

The label(s) of the participant(s) that should be analyzed. The label corresponds to sub-<participant_label> from the BIDS spec (so it does not include “sub-“).

If this parameter is not provided, all subjects will be analyzed. Multiple participants can be specified with a space separated list.

--task

The label of the task that will be analyzed.

The label corresponds to task-<task_label> from the BIDS spec so it does not include “task-“).

--run

The label of the run that will be analyzed.

The label corresponds to run-<task_label> from the BIDS spec so it does not include “run-“).

--space

The label of the space that will be analyzed.

The label corresponds to space-<space_label> from the BIDS spec (so it does not include “space-“).

-v, --verbose

--debug

Switch to debug mode

Default: False

--reset_database

Resets the database of the input dataset.

Default: False

--bids_filter_file

A JSON file describing custom BIDS input filters using PyBIDS. For further details, please check out TBD.

--force

Overwrite previous output.

Default: False

--model

Possible choices: 1_guided_fixations, 2_pursuit, 3_openclosed, 3_pursuit, 4_pursuit, 5_free_viewing, 1to5, 1to6

Model to use. Default model: 1to6.

Default: '1to6'

all

Run prepare, generalize.

bidsmreye all [-h]
              [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
              [--task TASK [TASK ...]] [--run RUN [RUN ...]]
              [--space SPACE [SPACE ...]] [-v] [--debug] [--reset_database]
              [--bids_filter_file BIDS_FILTER_FILE] [--force] [--linear_coreg]
              [--model {1_guided_fixations,2_pursuit,3_openclosed,3_pursuit,4_pursuit,5_free_viewing,1to5,1to6}]

Named Arguments

--participant_label

The label(s) of the participant(s) that should be analyzed. The label corresponds to sub-<participant_label> from the BIDS spec (so it does not include “sub-“).

If this parameter is not provided, all subjects will be analyzed. Multiple participants can be specified with a space separated list.

--task

The label of the task that will be analyzed.

The label corresponds to task-<task_label> from the BIDS spec so it does not include “task-“).

--run

The label of the run that will be analyzed.

The label corresponds to run-<task_label> from the BIDS spec so it does not include “run-“).

--space

The label of the space that will be analyzed.

The label corresponds to space-<space_label> from the BIDS spec (so it does not include “space-“).

-v, --verbose

--debug

Switch to debug mode

Default: False

--reset_database

Resets the database of the input dataset.

Default: False

--bids_filter_file

A JSON file describing custom BIDS input filters using PyBIDS. For further details, please check out TBD.

--force

Overwrite previous output.

Default: False

--linear_coreg

Uses a less aggressive (and linear) alignment procedure to the deepmreye template.

May lead to worse results so check your outputs.

Default: False

--model

Possible choices: 1_guided_fixations, 2_pursuit, 3_openclosed, 3_pursuit, 4_pursuit, 5_free_viewing, 1to5, 1to6

Model to use. Default model: 1to6.

Default: '1to6'

qc

Run quality control on output.

bidsmreye qc [-h]
             [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
             [--task TASK [TASK ...]] [--run RUN [RUN ...]]
             [--space SPACE [SPACE ...]] [-v] [--debug] [--reset_database]
             [--bids_filter_file BIDS_FILTER_FILE] [--force]

Named Arguments

--participant_label

The label(s) of the participant(s) that should be analyzed. The label corresponds to sub-<participant_label> from the BIDS spec (so it does not include “sub-“).

If this parameter is not provided, all subjects will be analyzed. Multiple participants can be specified with a space separated list.

--task

The label of the task that will be analyzed.

The label corresponds to task-<task_label> from the BIDS spec so it does not include “task-“).

--run

The label of the run that will be analyzed.

The label corresponds to run-<task_label> from the BIDS spec so it does not include “run-“).

--space

The label of the space that will be analyzed.

The label corresponds to space-<space_label> from the BIDS spec (so it does not include “space-“).

-v, --verbose

--debug

Switch to debug mode

Default: False

--reset_database

Resets the database of the input dataset.

Default: False

--bids_filter_file

A JSON file describing custom BIDS input filters using PyBIDS. For further details, please check out TBD.

--force

Overwrite previous output.

Default: False

For a more readable version of this help section, see the online https://bidsmreye.readthedocs.io/.