Programs · AFNI
3dAutomask
- Original
- AFNI 26.3.05
- Command line
larmorx afni 3dAutomask- Python
lx.afni.automask- Ports
- replica
larmorxApache-2.0 AND CC-BY-4.0 validated - clean room
larmorxApache-2.0 validated
- replica
- 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
larmorx afni 3dAutomask [options] datasetEverything 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):
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
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
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,
) -> AutomaskResultWhere 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.
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 Nn_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-roomimplementation="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|reproduceupstream_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.
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')larmorx afni 3dAutomask -apply_prefix uni_xform_masked.nii.gz -dilate 1 -prefix uni_xform_mask.nii.gz uni_xform.nii.gzPorts
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 packagelarmorx-gpl). - The clean room (
crates/larmorx-afni, Apache-2.0) is built for speed and written fromspecs/3dAutomask.mdand 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: