:orphan: .. _ahelp_afni_refacer2: ************* afni_refacer2 ************* .. contents:: :local: | OVERVIEW ======== .. code-block:: none This script re-faces or defaces one input dataset, using a reference shell dataset (which is mapped from template space) to write over the subject's 'face' region. The main input is the name of a T1-weighted dataset. This can be an important step in anonymizing anatomical datasets. For an independent comparison of methods that demonstrates the strong performance of this defacing/refacing program, see: Multisite Comparison of MRI Defacing Software Across Multiple Cohorts by Theyers et al. (2021) https://pmc.ncbi.nlm.nih.gov/articles/PMC7943842/ ver = 2.7 Author - The Face of Imperial Zhark, Who is Terrible to Behold! Modifier - PA Taylor # ========================================================================== USAGE ===== .. code-block:: none afni_refacer2 \ -input DSET \ -mode_{reface|reface_plus|deface|all} \ -mode2_{cubeface|all} \ -prefix PPP \ {-anonymize_output} \ {-cost CC} \ {-overwrite} \ {-no_clean} \ {-no_images} \ {-echo} \ {-verb_allin} where: -input DSET : (req) name of input dset; can contain path information. -prefix PPP : (req) name of output dset (see NOTES for info about about file names, particularly when "-mode_all" is used). ... and at least one '-mode*' option MUST be chosen (any combination of these can be used; the union of modes will be output): -mode_deface : replace the computed face+ears voxels with all zeros instead of the artificial face (ears are also removed) -mode_reface : replace the subject's face+ears with a scaled set of artificial values -mode_reface_plus : replace the subject's face+ears+skull with a scaled set of artificial values (i.e., like 'refacing', but replacing a more complete shell around the subject's brain) -mode_all : output three face-replaced volumes: one defaced, one refaced, and one reface_plused -mode2_cubeface : replace the subject's face+ears with values averaged across large cubes (see -cube_len, for controlling cube size) NB: this mode is NOT generally recommended; it exists primarily for testing/using within training a skullstripping program, simply because we saw it existed in The Wild. -mode2_all : output all the other '-mode2_* cases, which are not included in '-mode_all' NB: the '-mode2_*' cases are not recommended for general use, but instead exist for other special use cases -anonymize_output : (opt) use 3drefit and nifti_tool to anonymize the output dsets. **But always verify anonymization yourself, Dear User.** This option will not be able to help you if you choose a non-anonymizing output file name, for example. -cost CC : (opt) can specify any cost function that is allowed by 3dAllineate (def: lpa) -ref_shell RS : (opt) can specify which shell to use. At present, the available options for SH are: afni_refacer_shell_sym_1.1.nii.gz (earlier, shorter version) afni_refacer_shell_sym_2.1.nii.gz (remove more face/neck/ear) See NOTES about specific reference shell version numbers. (def: afni_refacer_shell_sym_2.1.nii.gz) -ref_dset RD : (opt) specify the reference template used, which must be consistent with the shell being used. See NOTES about specific reference datasets and partnering with reference shells. (def: MNI152_2009_template_SSW.nii.gz) -cube_len CL : (opt) when using "cubeface"-style refacing, users can control the number voxels along a cubeface side with this number; must be greater than 0 (def: 10) -no_clean : (opt) don't delete temp working dir (def: remove working dir) -no_images : (opt) don't make pretty images to automatically view the results of re/defacing; but why wouldn't you want those? This disables use of Xvfb. -overwrite : (opt) final two file outputs will overwrite any existing files of the same name (def: don't do this). NB: this option does not apply to the working directory -echo : (opt) run program very verbosely, echoing each command before executing it; likely only for debugging -verb_allin : (opt) run the 3dAllineate part herein with '-verb' (for verbosity) -help : see helpfile (here, in fact) -hview : popup help # ========================================================================== NOTES ===== Modes for running +++++++++++++++++ .. code-block:: none There are different modes available for defacing/refacing. Users can pick and choose which one(s) they want from an available list. When running with '-mode_all', then 5 datasets will be output, all in the same space as the input volume: + Three versions of the input anatomical with refacing/defacing, which we consider a reasonable/mainstream way of hiding the original face: 1) a "defaced" volume (face+ears replaced with zeros) 2) a "refaced" volume (face+ears replaced with artificial values) 3) a "reface_plus"ed volume (face+ears+skull replaced with artificial values) + Two volumes of just the face-replacing datasets, for reference: 4) the face+ears used to replace or remove subject data 5) the face+ears+skull used to replace subject data Note that there are other methods of defacing/refacing. While these are not very common, they are available here (if for no other reason than we have tested them and used them in other applications). These mode(s) can also be run individually or as a group. These are not included in the '-mode_all' output, but can be run with '-mode_all_extras' or the individual names. At present, these are: A) a "cubefaced" volume (face+ears replaced with average across big cubes) In all cases, automatic images of the re/defaced volume(s) will be created with @chauffeur_afni, so the user can quickly evaluate results visually. A temporary working directory is also created. This will be cleaned (=deleted) by default, but the user can choose to save it. Output file names +++++++++++++++++ .. code-block:: none If the user implements one of the individual modes for refacing, reface_plusing or defacing, then the main output file of interest is simply specified by their "-prefix .." choice. Additionally, the replacement volume in subject space will be output, with the same name plus a suffix (either 'face' or 'face_plus'). If the user instead implements '-mode_all', then three output volumes are created, each with the same prefix specified by their "-prefix .." choice, with identifying suffixes and *.nii.gz extensions: PREFIX.deface.nii.gz PREFIX.reface.nii.gz PREFIX.reface_plus.nii.gz Additionally, both replacement volumes will be output, having the same prefix and relevant suffix: PREFIX.face.nii.gz PREFIX.face_plus.nii.gz Finally, there is another set of less-common modes available, which can be output with '-mode_all_extras'. These might be primarily useful for testing or other applications, and includes: PREFIX.cubeface.nii.gz A directory of QC images will be made by default, called: PREFIX_QC/ This will contain images of each of the new anatomical volumes and the replacement volumes over the original anatomical. Requisite data sets +++++++++++++++++++ .. code-block:: none This script relies on having datasets that should already be included with AFNI binaries: MNI152_2009_template_SSW.nii.gz = MNI skull strip/warp template afni_refacer_shell_sym_*.nii.gz = dataset to replace face region The latter dataset(s) have been made by a combination of the @afni_refacer_make_master and @afni_refacer_make_master_addendum2 scripts. If you are missing these datasets for some reason (e.g., you build your own AFNI binaries on your computer), you can download these from the current/atlases directory. Or just ask for more info on the Message Board. Reference shells and template datasets ++++++++++++++++++++++++++++++++++++++ .. code-block:: none Different degrees of face-hiding have been preferred over time. Typically, it is recommended to remove more face (and ears) nowadays. The default masks here will do that. # ========================================================================== EXAMPLES ======== .. code-block:: none 1) deface (= replace face+ears with zeros) afni_refacer2 \ -input anat+orig.HEAD \ -mode_deface \ -prefix anat_deface.nii.gz 2) reface (= replace face+ears with generic face) afni_refacer2 \ -input anat.nii.gz \ -mode_reface \ -prefix anat_reface.nii.gz 3) reface plus (= reface a larger area, including skull region) afni_refacer2 \ -input anat.nii.gz \ -mode_reface_plus \ -prefix anat_reface_plus.nii.gz 4) ALL = output all versions of vol: refaced, reface_plused, defaced afni_refacer2 \ -input anat.nii.gz \ -mode_all \ -prefix anat 5) ... and using different shell for replacement: afni_refacer2 \ -input anat+orig. \ -mode_all \ -ref_shell afni_refacer_shell_sym_1.1.nii.gz \ -prefix anat