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_defacing

brainprep.workflow.brainprep_group_defacing(modality, output_dir, overlap_threshold=0.05, correlation_threshold=0.5, keep_intermediate=False)[source]

Group-level defacing pre-processing.

This function applies a quality control procedure to defaced images at the group level. It includes the following steps:

  1. Generate a TSV table containing the intersection between the brain and defacing masks. The optimal scenario is when there is no intersection.

  2. Generate a TSV file containing the mean correlation of each image to the reference image (MNI for T1w or T1w for T2w and FLAIR). The optimal scenario is when the correlation is maximized.

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

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

Parameters:
modalitystr

Modality: T1w, T2w or FLAIR.

output_dirDirectory

Directory where the defacing related outputs will be saved (i.e., the root of your dataset).

overlap_thresholdfloat

Quality control threshold on the overalp score. Default 0.05.

correlation_thresholdfloat

Quality control threshold on the correlation score. Default 0.5.

keep_intermediatebool

If True, retains intermediate results (no effect on this workflow). Default False.

Returns:
Bunch

A dictionary-like object containing:

  • correlations_file : File - a TSV file containing mean correlation of each input image to the reference image.

  • correlation_histogram_file : File - a PNG file containing the histogram of the computed mean correlations.

  • overalp_file : File - a TSV file containing brain/defacing masks intersections.

  • overalp_histogram_file : File - PNG file containing the histogram of the computed overlaps.

Raises:
ValueError

If the input modality is not supported.

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.workflow import brainprep_group_defacing
>>>
>>> with Config(dryrun=True, verbose=False):
...     outputs = brainprep_group_defacing(
...         modality="T1w",
...         output_dir="/tmp/dataset/derivatives",
...     )
>>> outputs
Bunch(
    correlations_file: PosixPath('...')
    correlation_histogram_file: PosixPath('...')
    overlap_file: PosixPath('...')
    overalp_histogram_file: PosixPath('...')
)

Examples using brainprep.workflow.brainprep_group_defacing

Defacing

Defacing