Programs · AFNI
3dUnifize
- Original
- AFNI 26.3.05
- Command line
larmorx afni 3dUnifize- Python
lx.afni.unifize- 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-unifize.md and the code
What it does
3dUnifize makes the white-matter intensity of a T1-weighted volume uniform across space and
scales it to about 1000 (or, with -T2, of a T2-weighted one; with -EPI, of an EPI series).
Command line
larmorx afni 3dUnifize [options] datasetEverything after larmorx afni 3dUnifize is the original’s command line: the arguments of AFNI 26.3.05’s 3dUnifize, 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 3dUnifize ...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.
3dUnifize's usage text, as the clean room prints it
Usage: 3dUnifize [options] dataset (larmorx, clean-room re-implementation of AFNI 3dUnifize)
Makes the white-matter intensity of a T1-weighted NIfTI volume uniform (about 1000): at each
voxel, the mean of the automasked values between two percentiles in a ball around it estimates
the local white-matter intensity, which divides the image.
Options:
-prefix pp the output (NIfTI: .nii or .nii.gz)
-input dd the dataset (also -inset; or the first argument after the options)
-T2 invert the contrast first and back after; twice: no inversion back
-T2up uu the upper percentile of the inversion, 90 to 100 [98.5]
-GM also scale the grey matter
-Urad rr the ball's radius in voxels, 5 to 99 [18.3]
-rbt R b t radius and percentiles [18.3 70 80] (also -param)
-clfrac cc the automask's clip level fraction, 0.1 to 0.9 [0.2] (also -mfrac)
-ssave ss save the scale factors
-amsave aa save the automasked input
-noduplo never work on a half-size copy (also -nodouble)
-EPI an EPI series: the scaling of its median volume applied to every volume
-nosquash do not squash values above 1300 (also -oink)
-quiet no progress messages
-verb the automask's messages too
AFNI's global options may stand anywhere: -overwrite, -Dname=value, -ok_1D_text, -skip_afnirc.Python
lx.afni.unifize(
image: Any,
*,
t2: int | bool = False,
t2_percentile: float = 98.5,
gm: bool = False,
radius: float = 18.3,
percentiles: Sequence[float] = (70.0, 80.0),
clfrac: float = 0.2,
duplo: bool = True,
epi: bool = False,
squash: bool = True,
save_scale: bool = False,
save_automask: bool = False,
n_threads: int = 1,
implementation: ImplementationName = "auto",
upstream_defects: UpstreamDefectsName = "fix",
afni_settings: Mapping[str, str] | None = None,
) -> UnifizeResultWhere ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room"); UpstreamDefectsName is one of "fix", "reproduce".
The image with its white-matter intensity uniformized, as AFNI’s 3dUnifize makes it.
Returns an UnifizeResult: image (float32; with epi=True every volume), scale (with
save_scale=True) and automasked (with save_automask=True). lx.afni.fmriprep_unifize_options()
gives fMRIPrep’s arguments. The arguments are checked before anything runs (ValueError, with
3dUnifize’s ranges); with the clean room, AFNI’s fatal errors (no automask) are ValueErrors too.
import larmorx as lx
# As fMRIPrep's BOLD reference workflow calls 3dUnifize (-clfrac 0.2 -rbt 18.3 65.0 90.0 -T2).
uni = lx.afni.unifize("boldref_brain_masked.nii.gz", **lx.afni.fmriprep_unifize_options())
uni.image # float32, white matter about 1000
# A T1w, with the scale factors.
r = lx.afni.unifize("sub-01_T1w.nii.gz", save_scale=True, n_threads=6)Its result, UnifizeResult, holds what unifize computed.
| Field | Type | What it holds |
|---|---|---|
image |
Image |
The unifized image, float32 (white matter about 1000); with epi=True every volume. |
scale |
Image | None |
With save_scale=True: the white-matter scale factor of each voxel (-ssave). |
automasked |
Image | None |
With save_automask=True: the input inside its automask (-amsave). |
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 3dUnifize accepts (crates/larmorx-afni/src/cli/unifize.rs) and the arguments of lx.afni.unifize (python/larmorx/afni/unifize.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 |
|---|---|---|---|
-prefix p |
the result | its image; NIfTI only; AFNI’s default Unifized is its own format, refusedThe clean room’s usage: “the output (NIfTI: .nii or .nii.gz)” |
|
-input d, -inset d, or the last argument |
image |
A path to a NIfTI file (read with AFNI’s rules), or an in-memory image. Only the first volume of a 4D image is processed, unless epi=True.The clean room’s usage: “the dataset (also -inset; or the first argument after the options)” |
|
-T2 |
t2=True (or 1) |
False |
invert the contrast, unifize, invert backThe clean room’s usage: “invert the contrast first and back after; twice: no inversion back” |
-T2 -T2 |
t2=2 |
False |
no inversion back; bright edges clippedThe clean room’s usage: “invert the contrast first and back after; twice: no inversion back” |
-T2 three or more times |
– | AFNI neither inverts back nor clips edges: refused by default (AFNI-48)The clean room’s usage: “invert the contrast first and back after; twice: no inversion back” | |
-T2up u |
t2_percentile |
98.5 |
90 to 100; near 100 see AFNI-45The clean room’s usage: “the upper percentile of the inversion, 90 to 100 [98.5]” |
-GM |
gm=True |
False |
grey-matter scaling (not with -EPI)The clean room’s usage: “also scale the grey matter” |
-Urad R, -rbt R b t, -param R b t |
radius, percentiles=(b, t) |
radius=18.3, percentiles=(70.0, 80.0) |
5 ≤ R ≤ 99, 30 ≤ b ≤ 80, b < t ≤ 90The clean room’s usage: “the ball’s radius in voxels, 5 to 99 [18.3]”The clean room’s usage: “R b t radius and percentiles [18.3 70 80] (also -param)” |
-clfrac c, -mfrac c |
clfrac |
0.2 |
the automask’s clip level fraction (default 0.2; AFNI’s help says 0.1, AFNI-49)The clean room’s usage: “the automask’s clip level fraction, 0.1 to 0.9 [0.2] (also -mfrac)” |
-noduplo, -nodouble |
duplo=False |
True |
the half-size copy is only used above a million voxelsThe clean room’s usage: “never work on a half-size copy (also -nodouble)” |
-EPI |
epi=True |
False |
implies -T2 (once, whatever -T2 gave) and -noduplo, turns off -GM, sets the radius from the voxel sizeThe clean room’s usage: “an EPI series: the scaling of its median volume applied to every volume” |
-nosquash, -oink |
squash=False |
True |
False is -nosquash.The clean room’s usage: “do not squash values above 1300 (also -oink)” |
-ssave s, -amsave a |
save_scale, save_automask |
save_scale=False, save_automask=False |
the result’s scale and automaskedThe clean room’s usage: “save the scale factors”The clean room’s usage: “save the automasked input” |
-quiet, -verb |
(always quiet) | warnings become Python warningsThe clean room’s usage: “no progress messages”The clean room’s usage: “the automask’s messages too” | |
-useall |
– | disabled in AFNI 25.2.09 and 26.3.05 (a warning) | |
-overwrite, -Dname=value, -ok_1D_text, -skip_afnirc; AFNI_* |
afni_settings |
None |
AFNI’s global options, anywhere on the command line, and AFNI’s variables, as for 3dAutomask |
OMP_NUM_THREADS |
n_threads |
1 |
the result does not depend on it, in AFNI or larmorx |
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 3dUnifize ...) and are arguments of lx.afni.unifize. 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" |
As for automask. t2=3 (-T2 three times, AFNI-48) is not accepted. The variable LARMORX_IMPLEMENTATION in 0.1.0rc1. |
--upstream-defects fix|reproduceupstream_defects="fix" |
As for automask. t2=3 (-T2 three times, AFNI-48) is not accepted. 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: ref.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's BOLD reference workflow calls 3dUnifize (-clfrac 0.2 -rbt 18.3 65.0 90.0 -T2).
uni = lx.afni.unifize("ref.nii.gz", **lx.afni.fmriprep_unifize_options())
uni.image.data.dtype # -> dtype('float32')larmorx afni 3dUnifize -clfrac 0.2 -rbt 18.3 65.0 90.0 -prefix uni.nii.gz -T2 -input ref.nii.gzPorts
3dUnifize 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-unifize-replica |
| clean room | larmorx |
Apache-2.0 | validated | afni-unifize |
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): 127 cases, 106 within its thresholds, 19 rejected by both alike, 2 expected divergences (AFNI’s default prefix, its own format, which LARMORX refuses; a slab where AFNI reads memory it never wrote, AFNI-47); every one of the 97 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): 129 cases, none failing: 108
within its thresholds, 19 rejected by both alike, the same 2 expected divergences (GLIBC-05’s 5
cases since 2026-10-30). AFNI’s exit status and messages in every case; in 44 of the 99
compared cases that write outputs every output is AFNI’s, bit for bit (data and NIfTI header);
in the other 55 the headers are AFNI’s and some squashed values differ in their last bit (at
most 8.7e-8 of the largest value; the threshold is 1e-5), because AFNI’s
tanhfis glibc’s and the clean room’s is correctly rounded: AFNI run with CORE-MATH’s correctly rounded functions preloaded gives the clean room’s bytes in all 55. fMRIPrep’s own outputs of 22 BOLD references of fMRIPrep’s runs: 1 bit for bit, the other 21 AFNI’s output with the same last-bit differences. Its result does not depend on the thread count (nor does AFNI’s: 1 and 6 threads, and fMRIPrep’s build, give AFNI’s bytes).
3dUnifize 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); with fdlibm’stanhfas glibc 2.35 runs it; 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/3dUnifize.mdand black-box runs of AFNI only (PROVENANCE).
implementation="auto" (the default, and larmorx afni 3dUnifize) runs the replica, in the same
process; "replica" or "clean-room" ("original", 0.1.0rc1’s spelling, still works)
(--implementation before the family, or LARMORX_IMPLEMENTATION) forces one. Each image’s
implementation names the one that ran.
Evidence
How each of 3dUnifize’s ports was measured against AFNI, case by case: its evidence.
More in the repository
The API page docs/api/afni-unifize.md holds what 3dUnifize shares with the page’s other programs: