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.workflow.brainprep_group_fmriprep

brainprep.workflow.brainprep_group_fmriprep(output_dir, fd_mean_threshold=0.2, dvars_std_threshold=1.5, entropy_threshold=12, keep_intermediate=False)[source]

Group level functional MRI pre-processing.

  1. Generate a TSV file containing the quality metrics described below.

  2. Apply threshold-based quality checks on the selected quality metrics.

  3. Generate a histogram showing the distribution of these quality metrics.

The following quality metrics are considered:

  • fd_mean : mean framewise displacement (mm), a measure of head motion across the time series.

  • dvars_std : mean standardized DVARS, quantifying the rate of change in BOLD signal intensity between consecutive volumes.

  • entropy : network entropy, quantifying whether a connectivity matrix exhibits meaningful structure.

Parameters:
output_dirDirectory

Working directory containing all the subjects.

fd_mean_thresholdfloat

Quality control threshold applied on the mean framewise displacement. Default 0.2.

dvars_std_thresholdfloat

Quality control threshold applied on the standardized DVARS. Default 1.5.

entropy_thresholdfloat

Quality control threshold applied on the network entropy. Default 12.

keep_intermediatebool

If True, retains intermediate results (i.e., the workspace); useful for debugging. Default False.

Returns:
Bunch

A dictionary-like object containing:

  • group_stats_file : File - a TSV file containing quality check (QC) metrics.

  • entropy_file : File - a TSV file network entropy quality check (QC) metric.

  • histogram_files : list[File] - PNG files containing histograms of selected important information.

Notes

This workflow assumes the subject-level analyses have already been performed.

A qc column is added to the TSV QC output table. It contains a binary flag indicating whether the produced results should be kept: qc = 1 if the result passes the thresholds, otherwise qc = 0.

The associated PNG histograms help verify that the chosen thresholds are neither too restrictive nor too permissive.

Examples

>>> from brainprep.config import Config
>>> from brainprep.reporting import RSTReport
>>> from brainprep.workflow import brainprep_group_fmriprep
>>>
>>> with Config(dryrun=True, verbose=False):
...     report = RSTReport()
...     outputs = brainprep_group_fmriprep(
...         output_dir="/tmp/dataset/derivatives",
...     ) 
>>> outputs 
Bunch(
    group_stats_file=PosixPath('...')
    entropy_file=PosixPath('...')
    histogram_files=[PosixPath('...'),...,PosixPath('...')]
)