AFNI program: afni_refacer2

Output of -help


OVERVIEW ~1~

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 ~1~

  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 ~1~

Modes for running ~2~

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 ~2~

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 ~2~

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 ~2~

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 ~1~

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
This page auto-generated on Mon Jul 6 11:27:04 PM EDT 2026