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(t1_file, output_dir, keep_intermediate=False, **kwargs)

Defacing pre-processing workflow for anatomical T1-weighted images.

Applies FSL’s fsl_deface tool [1] with default settings to remove facial features (face and ears) from the input image. This includes:

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

2. Deface the T1w image.

3. Generate a mosaic image of the defaced T1w image.

Parameters:

t1_fileFile

Path to the input T1w anatomical image file.

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_t1_file : File - path to the defaced image.

• mask_file : File - path to the defacing mask.

• mosaic_file : File - path to defacing snapshots.

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

Raises:

ValueError

If the T1w file do not follow BIDS convention.

Notes

This workflow assumes the input image is a valid T1-weighted anatomical scan.

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.reporting import RSTReport
>>> from brainprep.workflow import brainprep_defacing
>>>
>>> with Config(dryrun=True, verbose=False):
...     report = RSTReport()
...     outputs = brainprep_defacing(
...         t1_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_t1_file: PosixPath('...')
  mask_file: PosixPath('...')
  mosaic_file: PosixPath('...')
  summary_file: PosixPath('...')
)