Usage Notes

usage: physprep [workflow_strategy WORKFLOW_STRATEGY] [indir_bids INDIR_BIDS] [--sub SUB]
                [--ses SES] [--derivatives_dir DERIVATIVES_DIR] [--save_report]
                [--track_carbon] [--country_code] [--help]

Preprocess raw physiological data acquired in MRI, extract features, and
generate quality report.

Required:
  workflow strategy        Name of the workflow_strategy if using a preset.
                           It is also possible to use a custom file by
                           providing the path to a JSON file containing
                           workflow strategy. In that case, please check
                           Physprep documentation to make sure your file is
                           properly formatted.
  indir_bids               Path to the directory containing the BIDS-like
                           dataset.

Options:
  --sub TEXT               Subject label (e.g., `01`).
  --ses TEXT               Session label (e.g., `001`).
  --derivatives_dir PATH   Path to the derivatives directory. If not specified,
                           derivatives will be save in the `indir_bids` directory.
  --save_report            If specified, an quality report will be generated and
                           saved for each run.
  --track_carbon           If specified, carbon tracker will be used to track power
                           use of the pipeline.
  --country_code           Country ISO code used by carbon trackers. Will only be
                           used if --track_carbon flag is specified.
  --help                   Show this message and exit.

Using configuration files

Physprep pipeline uses configuration files to define the preprocessing steps for each modality (presets can be found in physprep/data). The configuration files are organized in two levels:

• physprep/data/workflow_strategy defining the type of physiological signal to process and the preprocessing strategy for each type of signal.

• physprep/data/preprocessing_strategy defining the preprocessing steps and parameters related to them.

Workflow strategy

The workflow configuration file is defined as the following:

{
    "<name_of_the_physiological_signal>": {
        "id": "<signal id>",
        "Description": "description of the signal",
        "Units": "recording units",
        "Channel": "<name_of_the_channel>",
        "preprocessing_strategy": "<name_of_the_preprocessing_strategy>",
        "qa_strategy": "<name_of_the_qa_strategy>",
    },
}

See example in physprep/data/workflow_strategy.

Every item within the file corresponds to a supported physiological signal, such as “ECG”, “PPG”, “EDA”, or “RSP”. For each modality to (pre-)process, users have the possibility to specify the channel name in the acquisition file, the filename/directory of the preprocessing strategy, and the filename/directory of the qa strategy.

An helper function is provided in the utils module to create a customized workflow configuration file:

from physprep.utils import create_config_workflow

# Check the function documentation
help(create_config_workflow)

# Call the function specifying the parameters value. You will be asked to enter different
# parameters from a set of currently supported values.
create_config_workflow(
    "/path/to/your/config/file",
    "your_amazing_workflow_strategy.json",
    overwrite=True
)

Preprocessing strategy

[
    {
        "step": "<name_of_the_step>",
        "parameters": {
            "<step_parameters>": "<value>",
            ...
        },
        "reference": {
            "<reference_parameters>": "value",
            ...
        }
    },
]

See presets in physprep/data/preprocessing_strategy.

Users also have the possibility to create their own preprocessing configuration file using the create_config_preprocessing function from the utils module:

from physprep.utils import create_config_preprocessing

# Check the function documentation
help(create_config_preprocessing)

# Call the function specifying the parameters value. You will be asked to enter different
# parameters from a set of currently supported values.
create_config_preprocessing(
    "/path/to/your/config/file",
    "your_amazing_preprocessing_strategy.json",
    overwrite=True
)

QA strategy

[
    {
        "sliding": {
            "duration": <duration_in_seconds>,
            "step": <duration_in_seconds>
        }
    },
    {
        "metric": "<metric>",
        "feature": "<feature_name>"
    },
    {
        "metric": "Quality",
        "feature": "<feature_name>",
        "threshold": {"feature": "criterion"}
    }
]

See presets in physprep/data/qa_strategy.

Users also have the possibility to create their own qa configuration file using the create_config_qa function from the utils module:

from physprep.utils import create_config_qa

# Check the function documentation
help(create_config_qa)

# Call the function specifying the parameters value. You will be asked to enter different
# parameters from a set of currently supported values.
create_config_qa(
    "/path/to/your/config/file",
    "your_amazing_qa.json",
    "ECG",
    overwrite=True
)

Carbon tracker

physprep workflow integrates codecarbon to track the energy usage and carbon emissions related to the preprocessing of your physiological data. The carbon emissions are estimated based on the energy consumption and the carbon intensity of electricity for the country specified in the --country_code parameter (default to “CAN” - Canada). However, since the carbon intensity of the electricity is based on the national average, a more precise estimate could be calculated by taking the carbon intensity value of a specific province/state/region (see electricitymaps). To track the energy consumption with physprep, specify the flag --track_carbon in the CLI. The codecarbon output will be saved under code/emissions.csv.