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.defacing.brainprep_defacing

brainprep.workflow.defacing.brainprep_defacing(anatomical_file, output_dir, keep_intermediate=False, **kwargs)

Defacing pre-processing workflow for anatomical images.

Applies FSL’s fsl_deface tool [1] with default settings to remove facial features (face and ears) from an input T1-weighted MRI image. Apply defacing mask to T2-weighted or FLAIR MRI images. This includes:

1. Reorient the anatomical image to standard MNI152 template space.

2. Compute a brain mask using a skull-stripping tool.

3. Deface the T1w image or apply defacing to T2w and FLAIR images using coregistration.

4. Compute brain mask and defacing mask intersection.

5. Generate a mosaic image of the defaced anatomical image.

Parameters:

anatomical_fileFile

Path to the input image file: T1w, T2w or FLAIR.

output_dirDirectory

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

keep_intermediatebool

If True, retains intermediate results (e.g., reoriented image); useful for debugging. Default False.

**kwargsdict

entities: dict

Dictionary of parsed BIDS entities.

Returns:

Bunch

A dictionary-like object containing:

• deface_anatomical_file : File - path to the defaced image.

• mask_file : File - path to the defacing mask.

• mosaic_file : File - path to defacing snapshots.

• maskdiff_file : File - a TSV file containing voxel counts and physical volumes (in mm³) for the brain/defacing masks and their intersection.

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

• transform_file : File - path to the 12 dof (T1w) or 6 dof (T2w and FLAIR coregistration) affine transformation.

Raises:

ValueError

If the input anatomical file do not follow BIDS convention. If the input modality is not supported. If a T1w image in the same session has not already been faced for T2w or FLAIR processings.

Notes

This workflow assumes a T1w image in the same session has already been defaced for T2w or FLAIR processings.

References

[1]

Fidel Alfaro-Almagro, Mark Jenkinson, Neal K Bangerter, Jesper L R Andersson, Ludovica Griffanti, Gwenaëlle Douaud, Stamatios N Sotiropoulos, Saad Jbabdi, Moises Hernandez-Fernandez, Emmanuel Vallee, Diego Vidaurre, Matthew Webster, Paul McCarthy, Christopher Rorden, Alessandro Daducci, Daniel C Alexander, Hui Zhang, Iulius Dragonu, Paul M Matthews, Karla L Miller, and Stephen M Smith. Image processing and quality control for the first 10,000 brain imaging datasets from UK biobank. Neuroimage, 166:400–424, February 2018.

Examples

>>> from brainprep.config import Config
>>> from brainprep.workflow import brainprep_defacing
>>>
>>> with Config(dryrun=True, verbose=False):
...     outputs = brainprep_defacing(
...         anatomical_file=(
...             "/tmp/dataset/rawdata/sub-01/ses-01/anat/"
...             "sub-01_ses-01_run-01_T1w.nii.gz"
...         ),
...         output_dir="/tmp/dataset/derivatives",
...     )
>>> outputs
Bunch(
  deface_anatomical_file: PosixPath('...')
  mask_file: PosixPath('...')
  mosaic_file: PosixPath('...')
  maskdiff_file: PosixPath('...')
  correlation_file: PosixPath('...')
  transform_file: PosixPath('...')
)