ROI Extraction

Overview

clpipe comes with a variety of functional and anatomical atlases, which can be used to extract ROI time series data from functional scans.

By default, ROIs are calculated with respect an image’s fMRIPrep brain mask. ROIs with a with a percentage of voxels outside of this mask exceeding “PropVoxels” will be set to “nan”. If any ROI has no voxels in the brain mask, then all ROIs will be extracted without respect to the brain mask, and then ROIs with fewer than “PropVoxels” voxels will be set to “nan”. This is a workaround for the limitations on Nilearn’s ROI extractor functions.

To view the available built-in atlases, you can use the roi atlases command.

Configuration

class clpipe.config.options.ROIExtractOptions

Options for ROI extraction.

target_directory: str = ''

Target folder for processing - usually an fMRIPrep output directory.

target_suffix: str = 'desc-postproc_bold.nii.gz'

Narrow down the images to use by specifying the path’s suffix. Use ‘desc-preproc_bold.nii.gz’ if targeting the fMRIPrep dir.

output_directory: str = 'data_ROI_ts'

Location of this command’s output. Defaults to data_ROI_ts.

atlases: list

List of atlases to use. Use ‘clpipe roi atlases’ to show available atlases.

require_mask: bool = True

Choose whether or not an accompanying mask for each image is required in the target directory.

prop_voxels: float = 0.5

ROIs with less than this proportion of voxels within the mask area are set to nan.

overlap_ok: bool = False

Are overlapping ROIs allowed?

Commands

clpipe roi extract

Extract ROIs with a given atlas.

clpipe roi extract [OPTIONS] [SUBJECTS]...

Options

-config_file, -c <config_file>

Use a given configuration file. If left blank, uses the default config file, requiring definition of BIDS, working and output directories. This will extract all ROI sets specified in the configuration file.

-target_dir, -i <target_dir>

Which postprocessed directory to process. If a configuration file is provided with a target directory, this argument is not necessary.

-target_suffix <target_suffix>

Which target suffix to process. If a configuration file is provided with a target suffix, this argument is not necessary.

-output_dir, -o <output_dir>

Where to put the ROI extracted data. If a configuration file is provided with a output directory, this argument is not necessary.

-task <task>

Which task to process. If none, then all tasks are processed.

-atlas_name <atlas_name>

What atlas to use. Use the command ‘clpipe roi atlases’ to see which are available. When specified for a custom atlas, this is what the output files will be named.

-custom_atlas <custom_atlas>

A custom atlas image, in .nii or .nii.gz for label or maps, or a .txt tab delimited set of ROI coordinates if for a sphere atlas. Not needed if specified in config.

-custom_label <custom_label>

A custom atlas label file. Not needed if specified in config.

-custom_type <custom_type>

What type of atlas? (label, maps, or spheres). Not needed if specified in config.

-sphere_radius <sphere_radius>

Sphere radius in mm. Only applies to sphere atlases.

-overlap_ok

Are overlapping ROIs allowed?

-overwrite

Overwrite existing ROI timeseries?

-log_output_dir <log_output_dir>

Where to put HPC output files (such as SLURM output files). If not specified, defaults to <outputDir>/batchOutput.

-submit, -s

Flag to submit commands to the HPC

-single

Flag to directly run command. Used internally.

-debug, -d

Flag to enable detailed error messages and traceback

Arguments

SUBJECTS

Optional argument(s)

clpipe roi atlases

Display all available atlases.

clpipe roi atlases [OPTIONS]