PETdeface

Submodules

petdeface.mideface module

class petdeface.mideface.ApplyMideface(command=None, terminal_output=None, write_cmdline=False, **inputs)

Bases: CommandLine

Runs mideface with the --apply flag to apply a facemask to a volume, uses inputs and outputs definde in ApplyMidefaceInputSpec and ApplyMidefaceOutputSpec respectively.

This class is used to deface a pet image using a previously created facemask from an anatomical (T1w) image. Requires petdeface.Mideface to have been run previously run and an input PET image.

Parameters:: CommandLine (nipype.interfaces.base.CommandLine) – nipype CommandLine class

input_spec

apply mideface inputs defined as traits in ApplyMidefaceInputSpec

alias of ApplyMidefaceInputSpec

output_spec

apply mideface outputs defined as traits in ApplyMidefaceOutputSpec

alias of ApplyMidefaceOutputSpec

class petdeface.mideface.ApplyMidefaceInputSpec(**kwargs)

Bases: CommandLineInputSpec

nipype CommandLineInputSpec for running mideface with the --apply flag to apply a facemask to a volume.

Parameters:: CommandLineInputSpec (nipype.interfaces.base.CommandLineInputSpec) – nipype CommandLineInputSpec class to inherit from

facemask: facemask to apply to volume to deface, type(nipype.interfaces.base.File)

in_file: volume to deface, type(nipype.interfaces.base.File)

lta_file: registration matrix lta file, type(nipype.interfaces.base.File)

out_file: defaced input, --o, type(nipype.interfaces.base.File)

class petdeface.mideface.ApplyMidefaceOutputSpec(**kwargs)

Bases: TraitedSpec

nipype TraitedSpec class for ApplyMideface. Defines the output trait for ApplyMideface, which is the defaced image that a facemask has been applied to.

Parameters:: TraitedSpec (nipype.interfaces.base.TraitedSpec) – nipype TraitedSpec class to inherit from

class petdeface.mideface.Mideface(command=None, terminal_output=None, write_cmdline=False, **inputs)

Bases: CommandLine

nipype implementation of Freesurfer’s MiDeface command line tool. This class is used to deface an anatomical image. Inherits from a nipype CommandLine class and uses the MidefaceInputSpec and MidefaceOutputSpec traits as input and output.

Parameters:: CommandLine (nipype.interfaces.base.CommandLine) – Inherits from nipype CommandLine class

input_spec

mideface inputs defined as traits in MidefaceInputSpec

alias of MidefaceInputSpec

output_spec

mideface outputs defined as traits in MidefaceOutputSpec

alias of MidefaceOutputSpec

class petdeface.mideface.MidefaceInputSpec(**kwargs)

Bases: CommandLineInputSpec

Command line arguments for mideface defined as traits for nipype CommandLineInputSpec. Arguments are defined here and where necessary defaulted with string values to make subsequent steps in the pipeline possible. E.g. defaced output files are denoted with the ‘_defaced’ suffix to differentiate them from the original input files.

Parameters:: CommandLineInputSpec (nipype.interfaces.base.CommandLineInputSpec) – nipype CommandLineInputSpec

atlas: atlasdir, --atlas, type(nipype.interfaces.base.Directory)

back_of_head: include back of head in the defacing, --back-of-head, type(nipype.traits.Bool)

check: input defaced : check whether a volume has been defaced, --check, type(nipype.traits.Tuple)

code: codename : embed codename in pics, --code, type(nipype.traits.Str)

display: set Xvfb display number for taking pics, --display, type(nipype.traits.Int)

expert: expert options file, --expert, type(nipype.interfaces.base.File)

fill_const: constIn constOut, --fill-const, type(nipype.traits.Tuple)

fill_zero: fill with zero, --fill-zero, type(nipype.traits.Bool)

force: force reprocessing (not applicable if –odir has not been used), --force, type(nipype.traits.Bool)

forehead: include forehead in the defacing (risks removing brain), --forehead, type(nipype.traits.Bool)

imconvert: /path/to/convert : path to imagemagik convert binary (for pics), --imconvert, type(nipype.interfaces.base.File)

in_file: volume to deface, type(nipype.interfaces.base.File)

init_reg: initialize samseg with reg (good in case samseg reg fails), --init-reg reg.lta, type(nipype.interfaces.base.File)

mgz: use compressed mgh format as output (default), --mgz, type(nipype.traits.Bool)

nii: use nifti format as output (only when output files are not specified), --nii, type(nipype.traits.Bool)

nii_gz: use compressed nifti format as output (only when output files are not specified), --nii.gz, type(nipype.traits.Bool)

no_ears: do not include ears in the defacing, --no-ears, type(nipype.traits.Bool)

no_pics: do not take pics, --no-pics, type(nipype.traits.Bool)

no_post: do not make a head surface after defacing, --no-post, type(nipype.traits.Bool)

no_samseg_fast: do NOT configure samseg to run quickly, --no-samseg-fast, type(nipype.traits.Bool)

odir: output directory (turns on PostHeadSurf), --odir, type(nipype.interfaces.base.Directory)

out_facemask: facemask, --facemask, type(nipype.interfaces.base.File)

out_file: defaced input, --o, type(nipype.interfaces.base.File)

pics: take pics (–no-pics), --pics, type(nipype.traits.Bool)

samseg_fast: configure samseg to run quickly; sets ndil=1 (default), --samseg-fast, type(nipype.traits.Bool)

samseg_json: configure samseg --samseg-json, type(nipype.interfaces.base.File)

threads: number of threads, --threads, type(nipype.traits.Int)

xmask: xmask (exclusion mask), --xmask, type(nipype.interfaces.base.File)

xmask_samseg: ndilations segment input using samseg (14GB, +~20-40min) --xmask-samseg, type(nipype.traits.Int)

xmask_synthseg: ndilations : segment input using synthseg (35GB, +~20min), --xmask-synthseg, type(nipype.traits.Int)

class petdeface.mideface.MidefaceOutputSpec(**kwargs)

Bases: TraitedSpec

Set of traits corresponding to the desired mideface output files for this petdefacing pipeline.

Parameters:: TraitedSpec (nipype.interfaces.base.TraitedSpec) – nipype TraitedSpec class

out_after_pic: trait for after defacing picture

out_before_pic: trait for before defacing picture

out_facemask: trait for facemask, --facemask, type(nipype.interfaces.base.File)

out_file: trait for defaced input, --o, type(nipype.interfaces.base.File)

petdeface.pet module

class petdeface.pet.WeightedAverage(from_file=None, resource_monitor=None, ignore_exception=False, **inputs)

Bases: BaseInterface

Create a time-weighted average of dynamic PET data using mid-frames.

Parameters:: BaseInterface (nipype.interfaces.base.BaseInterface) – nipype BaseInterface class to inherit from
Returns:: none
Return type:: none

input_spec

nipype input specification for the interface

alias of WeightedAverageInputSpec

output_spec

nipype output specification for the interface

alias of WeightedAverageOutputSpec

class petdeface.pet.WeightedAverageInputSpec(**kwargs): Bases: BaseInterfaceInputSpec

class petdeface.pet.WeightedAverageOutputSpec(**kwargs): Bases: TraitedSpec

petdeface.petdeface module

class petdeface.petdeface.PetDeface(bids_dir, output_dir=None, anat_only=False, subject='', session='', n_procs=2, skip_bids_validator=True, remove_existing=True, placement='adjacent')

Bases: object

Defacing class used to collect inputs, out dirs, perform initial setup, and finally run the defacing workflow.

run(): Runs the defacing workflow given inputs from instiantiation and wraps up defacing by collecting output files and moving them to their final destination.

petdeface.petdeface.check_docker_image_exists(image_name, build=False)

Checks to see if a docker image exists, if it does not and build is set to True, it will attempt to build the image.

Parameters:

image_name (string) – name of docker image
build (bool, optional) – try to build a docker image if none is found, defaults to False

Returns:

status of whether or not the image exists

Return type:

bool

petdeface.petdeface.check_docker_installed()

Checks to see if docker is installed on the host system, raises exception if it is not.

Raises:: Exception – if docker is not installed
Returns:: status of docker installation
Return type:: bool

petdeface.petdeface.cli(): Argparse based cli for petdeface

petdeface.petdeface.deface(args: dict | Namespace) → None

Main function for the PET Deface workflow.

Parameters:: args (Union[dict, argparse.Namespace]) – given a dictionary or argparsed namespace, this function will run the defacing workflow
Raises:: Exception – if a valid FreeSurfer license is not found

petdeface.petdeface.determine_in_docker()

Determines if the script is running in a docker container, returns True if it is, False otherwise

Returns:: if running in docker container
Return type:: bool

petdeface.petdeface.init_single_subject_wf(subject_id: str, bids_data: [<class 'pathlib.Path'>, <class 'bids.layout.layout.BIDSLayout'>], output_dir: ~pathlib.Path = None) → LiterateWorkflow

Organize the preprocessing pipeline for a single subject.

Parameters:

subject_id (str) – _description_
bids_data (pathlib.Path, BIDSLayout]) – _description_
output_dir (pathlib.Path, optional) – _description_, defaults to None

Raises:

FileNotFoundError – _description_

Returns:

_description_

Return type:

Workflow

petdeface.petdeface.locate_freesurfer_license()

Checks for freesurfer license on host system and returns path to license file if it exists. Raises error if $FREESURFER_HOME is not set or if license file does not exist at $FREESURFER_HOME/license.txt

Raises:

ValueError – if FREESURFER_HOME environment variable is not set
ValueError – if license file does not exist at FREESURFER_HOME/license.txt

Returns:

full path to Freesurfer license file

Return type:

pathlib.Path

petdeface.petdeface.main(): Main function for petdeface, uses argparse to collect inputs and then runs the defacing workflow and additionally performs steps required for running petdeface in docker if the –docker flag is passed. This includes mounting the input, output, and freesurfer license as well as creating the command to for docker run to execute the workflow.

petdeface.petdeface.move_defaced_images(mapping_dict: dict, final_destination: str | Path, move_files: bool = False)

Moves images created in defacing workflow to final destination given a dictionary mapping the defaced images to the original images.

Parameters:

mapping_dict (dict) – dictionary mapping defaced images to original images
final_destination (Union[str, pathlib.Path]) – final destination for defaced images
move_files (bool, optional) – delete defaced images in “working” directory, e.g. move them to the destination dir instead of copying them there, defaults to False

petdeface.petdeface.wrap_up_defacing(path_to_dataset, output_dir=None, placement='adjacent', remove_existing=True)

This function maps the output of this pipeline to the original dataset and depending on the flag/arg for placement either replaces the defaced images in the same directory as the original images, creates a copy of the original dataset at {path_to_dataset}_defaced and places the defaced images there along with the defacing masks and registration files at the copied dir in the deriviatives folder, or lastly leaves things well enough alone and just places the defaced images in the derivatives folder (does nothing).

path_to_dataset : path like object (str or pathlib.Path)

output_dirpath like object (str or pathib.Path), optional: Specific directory to place output, this seems redundant given placemnent, by default None
placementstr, optional: Can be one of three values - adjacent creates (but doesn’t overrwrite) a new dataset with only defaced images - inplace replaces original images with defaced versions (not recommended) - derivatives does nothing, defaced images exist only within the derivitives/petdeface dir by default “adjacent”

Parameters:

path_to_dataset (path like object (str or pathlib.Path)) – Path to original dataset
output_dir (path like object (str or pathlib.Path), optional) – Specific directory to place output, arguably redundant given placemnent, defaults to input_dir/derivatives/petdeface
placement (str, optional) – str, optional Can be one of three values - adjacent creates (but doesn’t overrwrite) a new dataset with only defaced images - inplace replaces original images with defaced versions (not recommended) - derivatives does nothing, defaced images exist only within the derivitives/petdeface dir by default “adjacent”
remove_existing (bool, optional) – _description_, defaults to True

Raises:

ValueError – _description_

petdeface.petdeface.write_out_dataset_description_json(input_bids_dir, output_bids_dir=None)

Writes an generic dataset_description.json file to the output directory.

Parameters:

input_bids_dir (Union[pathlib.Path, str]) – the input bids directory
output_bids_dir (Union[pathlib.Path, str]) – the output defaced directory, defaults to None