Programs · AFNI

3dAutomask

Original
AFNI 26.3.05
Command line
larmorx afni 3dAutomask
Python
lx.afni.automask
Ports
  • replica larmorx Apache-2.0 AND CC-BY-4.0 validated
  • clean room larmorx Apache-2.0 validated
Evidence
every comparison with AFNI
Source
made from docs/api/afni-automask.md and the code

What it does

3dAutomask makes a brain mask from an EPI series or a skull-stripped anatomical image.

Command line

text
larmorx afni 3dAutomask [options] dataset

Everything after larmorx afni 3dAutomask is the original’s command line: the arguments of AFNI 26.3.05’s 3dAutomask, as AFNI takes them. LARMORX’s own options stand between larmorx and the family afni, so they never meet the original’s (below):

text
larmorx
        [--n-threads N]
        [--implementation auto|replica|clean-room]
        [--upstream-defects fix|reproduce]
        afni 3dAutomask ...

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

3dAutomask's usage text, as the clean room prints it
text
Usage: 3dAutomask [options] dataset   (larmorx, clean-room re-implementation of AFNI 3dAutomask)

Makes a brain mask (1 inside, 0 outside) from an EPI time series or a skull-stripped anatomical
NIfTI dataset: a clip level that varies gradually across the image, the largest connected
cluster, peeled and restored, its holes filled.

Options (they must come before the dataset):
  -prefix ppp        the mask (NIfTI: .nii or .nii.gz)
  -apply_prefix ppp  the input with every voxel outside the mask 0
  -depth ppp         how many erosions remove each mask voxel
  -clfrac cc         clip level fraction, 0.1 to 0.9 [0.5] (also -mfrac)
  -nograd            one clip level for the whole image
  -peels pp          peel and restore the mask pp times [1]; 0 turns it off
  -nbhrs nn          neighbours (of 18) a voxel needs not to be peeled, 6 to 26 [17]
  -NN1 -NN2 -NN3     neighbourhood of -dilate, -erode and -depth [NN2]; also sets -nbhrs
  -eclip             remove exterior voxels below the clip level
  -dilate nd         dilate the mask nd times
  -erode ne          erode the mask ne times
  -SI hh             clear everything more than hh mm inferior to the most superior voxel
  -q                 no progress messages

AFNI's global options may stand anywhere: -overwrite, -Dname=value, -ok_1D_text, -skip_afnirc.

Python

python
lx.afni.automask(
    image: Any,
    *,
    clfrac: float = 0.5,
    gradual: bool = True,
    peels: int = 1,
    neighbours: int = 17,
    nn: Literal[1, 2, 3] | None = None,
    exterior_clip: bool = False,
    dilate: int = 0,
    erode: int = 0,
    si: float | None = None,
    apply: bool = False,
    depth: bool = False,
    n_threads: int = 1,
    implementation: ImplementationName = "auto",
    upstream_defects: UpstreamDefectsName = "fix",
    afni_settings: Mapping[str, str] | None = None,
) -> AutomaskResult

Where ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room"); UpstreamDefectsName is one of "fix", "reproduce".

A brain mask, as AFNI’s 3dAutomask makes it.

Returns an AutomaskResult: mask (uint8, 3D; 2D for a plane), masked (with apply=True; the input’s storage type, its values as lx.load reads them) and depth (with depth=True; int16). image is a path (read with AFNI’s NIfTI rules) or an in-memory image (2D, 3D or 4D; uint8, int16 and float32 kept, other types float32). The arguments are checked before anything runs (ValueError); with the clean room, AFNI’s fatal errors (no mask of a plane smaller than 16 × 16, an empty mask) are ValueErrors too. AFNI’s variables are settings of the call (afni_settings, as for lx.afni.tshift); the process environment is never read.

python
import larmorx as lx

# As fMRIPrep calls 3dAutomask on its unifized BOLD reference.
r = lx.afni.automask("uni_xform.nii.gz", dilate=1, apply=True)
r.mask      # uint8, 1 inside the brain
r.masked    # the input, 0 outside the mask
r.mask.implementation   # Implementation(kind='replica', package='larmorx', ...)

Its result, AutomaskResult, holds what automask computed.

Field Type What it holds
mask Image The brain mask: uint8, 1 inside and 0 outside, on the input’s grid (3D).
masked Image | None With apply=True: the input with every voxel outside the mask 0, in the input’s storage type (-apply_prefix); else None.
depth Image | None With depth=True: int16, how many erosions it takes to reach each mask voxel (-depth); else None.

Options

Each row joins an option of the original’s command line with the Python argument that does the same. The rows are checked against the code at every test run: the options 3dAutomask accepts (crates/larmorx-afni/src/cli/automask.rs) and the arguments of lx.afni.automask (python/larmorx/afni/automask.py), whose defaults and descriptions are taken from it. Under each option, in grey, its line of the usage text the clean room prints, in the clean room’s own words.

AFNI option Python Default Notes
the last word (dataset) image the input: a path, or an in-memory image in Python
-prefix p the result its mask; the command line writes NIfTI only (.nii, .nii.gz); AFNI’s default automask is its own format, refusedThe clean room’s usage: “the mask (NIfTI: .nii or .nii.gz)”
-apply_prefix p apply=True False the result’s masked; alone (no -prefix) it is the only outputThe clean room’s usage: “the input with every voxel outside the mask 0”
-depth p depth=True False the result’s depth, from the mask before -dilate, -erode and -SIThe clean room’s usage: “how many erosions remove each mask voxel”
-clfrac c, -mfrac c clfrac 0.5 0.1 to 0.9The clean room’s usage: “clip level fraction, 0.1 to 0.9 [0.5] (also -mfrac)”
-nograd gradual=False True any option starting with -nogrThe clean room’s usage: “one clip level for the whole image”
-peels p peels 1 0 turns the peeling off (AFNI-43; AFNI peels once)The clean room’s usage: “peel and restore the mask pp times [1]; 0 turns it off”
-nbhrs n neighbours 17 6 to 26 (19 to 26 act as 18); outside it an error by default (AFNI-41)The clean room’s usage: “neighbours (of 18) a voxel needs not to be peeled, 6 to 26 [17]”
-NN1, -NN2, -NN3 nn=1, 2, 3 None also set neighbours to 6, 18, 26 (AFNI-42, kept)The clean room’s usage: “-NN2 -NN3 neighbourhood of -dilate, -erode and -depth [NN2]; also sets -nbhrs”
-eclip exterior_clip=True False -eclip: remove exterior voxels below the clip level.The clean room’s usage: “remove exterior voxels below the clip level”
-dilate nd, -erode ne dilate, erode dilate=0, erode=0 dilations need 3 neighbours; each is followed by filling holesThe clean room’s usage: “dilate the mask nd times”The clean room’s usage: “erode the mask ne times”
-SI hh si None millimetres, along the superior axisThe clean room’s usage: “clear everything more than hh mm inferior to the most superior voxel”
-q (always) the Python wrapper runs quietly; its warnings become Python warningsThe clean room’s usage: “no progress messages”
-overwrite, -Dname=value, -ok_1D_text, -skip_afnirc afni_settings None AFNI’s global options, anywhere on the command line
OMP_NUM_THREADS n_threads 1 the result does not depend on it (AFNI’s 3dAutomask is single-threaded; the clean room runs its passes in parallel)
LARMORX_UPSTREAM_DEFECTS upstream_defects "fix" fix (default) or reproduce
LARMORX_IMPLEMENTATION implementation "auto" auto, replica or clean-room (--implementation before the family)

LARMORX’s own options

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

They stand between larmorx and afni on the command line (larmorx --n-threads 4 afni 3dAutomask ...) and are arguments of lx.afni.automask. Each one given wins over its environment variable, which keeps working.

Command line, then Python What it does
--n-threads N
n_threads=1
Threads (0 = all); the result does not depend on it. Default: every logical CPU on the command line (0), 1 in Python. The variable OMP_NUM_THREADS in 0.1.0rc1.
--implementation auto|replica|clean-room
implementation="auto"
"auto" (default) and "replica": the bit-exact replica; "clean-room" ("original", 0.1.0rc1’s spelling, still works): the clean room. The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
upstream_defects="fix"
"fix" (default) or "reproduce" (AFNI’s output); a UpstreamDefectWarning names each defect that changed the result. The variable LARMORX_UPSTREAM_DEFECTS in 0.1.0rc1.

Examples

The tests run every example below (validation/tests/test_reference.py), each section in a new folder where these inputs are made first: uni_xform.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm). The command lines run as python -m larmorx.

python
import larmorx as lx

# As fMRIPrep calls 3dAutomask on its unifized BOLD reference.
r = lx.afni.automask("uni_xform.nii.gz", dilate=1, apply=True)
r.mask.data.dtype  # -> dtype('uint8')
bash
larmorx afni 3dAutomask -apply_prefix uni_xform_masked.nii.gz -dilate 1 -prefix uni_xform_mask.nii.gz uni_xform.nii.gz

Ports

3dAutomask has two ports: a replica and a clean room.

Port Package Licence Status Records
replica larmorx (built in) Apache-2.0 AND CC-BY-4.0 validated afni-automask-replica
clean room larmorx Apache-2.0 validated afni-automask

Both are validated against AFNI 26.3.05 itself (the clean room against AFNI 25.2.09 until 2026-10-29), each in a standard comparison of 2026-10-30:

  • The replica (its record): 125 cases, 105 within its thresholds, 19 rejected by both alike, 1 expected divergence (AFNI’s default prefix, its own format, which LARMORX refuses); every one of the 101 compared cases that write an output is AFNI’s bit for bit (data and NIfTI header), with AFNI’s exit status and messages.
  • The clean room (its record): 130 cases, 110 within its thresholds, 19 rejected by both alike, the same expected divergence. Of the 106 compared cases that write an output, 92 are AFNI’s bit for bit (data and NIfTI header), with AFNI’s exit status and messages; the other 14, fMRIPrep’s calls on BOLD references of the data panel, have AFNI’s data and a header that differs only where AFNI reads its own header extension of the input (AFNI-10). fMRIPrep’s masks of all 22 BOLD references in the record: AFNI’s data, bit for bit.

3dAutomask has two ports, both in pip install larmorx:

  • The replica is bit-exact, translated from AFNI’s source (crates/larmorx-afni-replica; Apache-2.0, with CC BY 4.0’s attribution for the code of the Medical College of Wisconsin, which AFNI 26.3.05 releases under CC BY 4.0 (NOTICE, licensing); until 2026-10-29 the separate GPL package larmorx-gpl).
  • The clean room (crates/larmorx-afni, Apache-2.0) is built for speed and written from specs/3dAutomask.md and black-box runs of AFNI only (PROVENANCE).

implementation="auto" (the default, and larmorx afni 3dAutomask) runs the replica, in the same process; implementation="replica" or "clean-room" ("original", 0.1.0rc1’s spelling, still works) (--implementation on the command line, or LARMORX_IMPLEMENTATION) forces one. Each image’s implementation names the one that ran.

Evidence

How each of 3dAutomask’s ports was measured against AFNI, case by case: its evidence.

More in the repository

The API page docs/api/afni-automask.md holds what 3dAutomask shares with the page’s other programs: