Programs · AFNI

3dUnifize

Original
AFNI 26.3.05
Command line
larmorx afni 3dUnifize
Python
lx.afni.unifize
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-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

text
larmorx afni 3dUnifize [options] dataset

Everything 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):

text
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
text
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

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,
) -> UnifizeResult

Where 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.

python
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 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"
As for automask. t2=3 (-T2 three times, AFNI-48) is not accepted. The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
upstream_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.

python
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')
bash
larmorx afni 3dUnifize -clfrac 0.2 -rbt 18.3 65.0 90.0 -prefix uni.nii.gz -T2 -input ref.nii.gz

Ports

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 tanhf is 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’s tanhf as glibc 2.35 runs it; 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/3dUnifize.md and 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: