Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

brainprep.interfaces.func_vol_connectivity

brainprep.interfaces.func_vol_connectivity(fmri_rest_image_file, mask_file, counfounds_file, workspace_dir, output_dir, entities, low_pass=0.1, high_pass=0.01, scrub=5, fd_threshold=0.2, std_dvars_threshold=3, detrend=True, standardize='zscore_sample', remove_volumes=True, fwhm=0.0, dryrun=False)[source]

ROI-based functional connectivity from volumetric fMRI data.

This function uses Nilearn to extract ROI time series and compute functional connectivity based on the Schaefer 200 ROI atlas. It applies the Yeo et al. (2011) preprocessing pipeline, including detrending, filtering, confound regression, and standardization.

Connectivity is computed using Pearson correlation and saved as a TSV file following BIDS derivatives conventions. The output filename includes BIDS entities and specifies the atlas and metric used.

Preprocessing steps:

  1. Detrending

  2. Low-pass and high-pass filtering

  3. Confound regression

  4. Standardization

Filtering:

  • Low-pass removes high-frequency noise (> 0.1 Hz by default).

  • High-pass removes scanner drift and low-frequency fluctuations (< 0.01 Hz by default).

Confounds:

  • 1 global signal

  • 12 motion parameters + derivatives

  • 8 discrete cosine basis regressors

  • 2 tissue-based confounds (white matter and CSF)

Total: 23 base confound regressors

Scrubbing:

  • Volumes with excessive motion (FD > 0.2 mm or standardized DVARS > 3) are removed.

  • Segments shorter than scrub frames are discarded.

  • One-hot regressors are added for scrubbed volumes.

Parameters:
fmri_rest_image_fileFile

Pre-processed resting-state fMRI volumes.

mask_fileFile

Brain mask used to restrict signal cleaning.

counfounds_fileFile

Confounds file from fMRIPrep.

workspace_dir: Directory

Working directory with the workspace of the current processing.

output_dirDirectory

Output directory for generated files.

entitiesdict

A dictionary of parsed BIDS entities including modality.

low_passfloat

Low-pass filter cutoff frequency in Hz. Set to None to disable. Default 0.1.

high_passfloat

High-pass filter cutoff frequency in Hz. Set to None to disable. Default 0.01

scrubint

After accounting for time frames with excessive motion, further remove segments shorter than the given number. The default value is 5. When the value is 0, remove time frames based on excessive framewise displacement and DVARS only. One-hot encoding vectors are added as regressors for each scrubbed frame. Default 5

fd_thresholdfloat

Framewise displacement threshold for scrub. This value is typically between 0 and 1 mm. Default 0.2

std_dvars_thresholdint

Standardized DVARS threshold for scrub. DVARs is defined as root mean squared intensity difference of volume N to volume N + 1. D refers to temporal derivative of timecourses, VARS referring to root mean squared variance over voxels. Default 3.

detrendbool

Detrend data prior to confound removal. Default True

standardizestr | None

Strategy to standardize the signal: ‘zscore_sample’, ‘psc’, or None . Default ‘zscore_sample’.

remove_volumesbool

This flag determines whether contaminated volumes should be removed from the output data. Default True.

fwhmfloat | list[float]

Smoothing strength, expressed as as Full-Width at Half Maximum (fwhm), in millimeters. Can be a single number fwhm=8, the width is identical along x, y and z or fwhm=0, no smoothing is performed. Can be three consecutive numbers, fwhm=[1,1.5,2.5], giving the fwhm along each axis. Default 0.

dryrunbool

If True, skip actual computation and file writing. Default False.

Returns:
connectivity_fileFile

Path to the TSV file containing the ROI-to-ROI connectivity matrix.

Notes

  • ROI atlas used: Schaefer 2018 (200 regions)

  • Connectivity metric: Pearson correlation