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_vbm

brainprep.workflow.brainprep_group_vbm(output_dir, ncr_threshold=4.5, iqr_threshold=4.5, correlation_threshold=0.5, longitudinal=False, keep_intermediate=False)

Group-level VBM pre-processing.

Summarizes the generated ROI-based features and applies the quality control described in [1]. This includes:

1. Generate TSV tables of VBM GM, WM and CSF features for different atlases.

2. Generate a TSV file containing the mean correlation of each image to the template.

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

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

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

The following quality metrics are considered:

• Image Correlation Ratio (ICR) - Measures how well the subject’s image aligns with a reference template. High ICR suggests good registration quality.

• Noise to Contrast Ratio (NCR) - Assesses image clarity by comparing noise levels to tissue contrast. Lower NCR may indicate poor image quality.

• Image Quality Rating (IQR) - A composite score summarizing overall scan quality. Combines multiple metrics like noise, resolution, and bias field. Higher IQR = better quality.

Parameters:

output_dirDirectory

Working directory containing all the subjects.

ncr_thresholdfloat

Quality control threshold on the NCR scores. Default 4.5.

iqr_thresholdfloat

Quality control threshold on the IQR scores. Default 4.5.

correlation_thresholdfloat

Quality control threshold on the correlation score. Default 0.5.

longitudinalbool

If True, consider the longitudinal data as inputs. Default False.

keep_intermediatebool

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

Returns:

Bunch

A dictionary-like object containing:

• morphometry_files : list[File] - a TSV file containing ROI-based GM, WM and CSF features for different atlases, as well as a TSV file containing total intracranial volume (TIV) and absolute tissue volumes (GM, WM, CSF).

• correlations_file : File - a TSV file containing mean correlation of each input image to the atlas image quality check (QC) data.

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

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

Notes

This workflow assumes the subject-level or longitudinal 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.

References

[1]

Benoit Dufumier, Antoine Grigis, Julie Victor, Corentin Ambroise, Vincent Frouin, and Edouard Duchesnay. OpenBHB: a large-scale multi-site brain MRI data-set for age prediction and debiasing. Neuroimage, 263(119637):119637, November 2022.

Examples

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

Examples using brainprep.workflow.brainprep_group_vbm

VBM

VBM