Programs · FSL

fast

fast segments a skull-stripped brain image into tissue classes (by default CSF, grey matter and white matter) with a hidden Markov random field fitted by expectation-maximisation.

Original
FSL 6.0.7.23
Command line
larmorx fsl fast
Python
lx.fsl.fast
Ports
  • replica larmorx-nc FSL Licence: non-commercial use only experimental
  • clean room larmorx Apache-2.0 experimental
Evidence
every comparison with FSL
Source
made from docs/api/fsl-fast.md and the code

What it does

It also estimates a bias field and the partial volume of each class in each voxel, on one image or 2 to 8 co-registered channels, with FSL’s tissue priors if asked.

Command line

text
larmorx fsl fast [options] file(s)

Everything after larmorx fsl fast is the original’s command line: the arguments of FSL 6.0.7.23’s fast, as FSL takes them. LARMORX’s own options stand between larmorx and the family fsl, so they never meet the original’s (below):

text
larmorx
        [--n-threads N]
        [--implementation auto|replica|clean-room]
        [--upstream-defects fix|reproduce]
        fsl fast ...

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.

fast's usage text, as the clean room prints it
text
Part of FSL (ID: 2412.6-dirty)
FAST 
Copyright(c) 2004-2012, University of Oxford

Usage: 
fast [options] file(s)

Optional arguments (You may optionally specify one or more of):
	-n,--class	number of tissue-type classes; default=3
	-I,--iter	number of main-loop iterations during bias-field removal; default=4
	-l,--lowpass	bias field smoothing extent (FWHM) in mm; default=20
	-t,--type	type of image 1=T1, 2=T2, 3=PD; default=T1
	-f,--fHard	initial segmentation spatial smoothness (during bias field estimation); default=0.02
	-g,--segments	outputs a separate binary image for each tissue type
	-a <standard2input.mat> initialise using priors; you must supply a FLIRT transform
	-A <prior1> <prior2> <prior3>    alternative prior images
	--nopve	turn off PVE (partial volume estimation)
	-b		output estimated bias field
	-B		output bias-corrected image
	-N,--nobias	do not remove bias field
	-S,--channels	number of input images (channels); default 1
	-o,--out	output basename
	-P,--Prior	use priors throughout; you must also set the -a option
	-W,--init	number of segmentation-initialisation iterations; default=15
	-R,--mixel	spatial smoothness for mixeltype; default=0.3
	-O,--fixed	number of main-loop iterations after bias-field removal; default=4
	-H,--Hyper	segmentation spatial smoothness; default=0.1
	-v,--verbose	switch on diagnostic messages
	-h,--help	display this message
	-s,--manualseg <filename> Filename containing intensities
	-p		outputs individual probability maps

Python

python
lx.fsl.fast(
    images: Any,
    *,
    n_classes: int = 3,
    image_type: ImageType = "T1",
    bias_iterations: int = 4,
    bias_lowpass: float = 20.0,
    no_bias: bool = False,
    fixed_iterations: int = 4,
    init_iterations: int = 15,
    initial_smoothness: float = 0.02,
    smoothness: float = 0.1,
    mixel_smoothness: float = 0.3,
    pve: bool = True,
    segments: bool = False,
    probabilities: bool = False,
    restored: bool = False,
    bias_field: bool = False,
    manual_means: Any = None,
    priors_matrix: Any = None,
    priors: Sequence[Any] | None = None,
    priors_throughout: bool = False,
    fsldir: str | os.PathLike[str] | None = None,
    verbose: bool = False,
    n_threads: int = 1,
    implementation: ImplementationName = "auto",
    upstream_defects: UpstreamDefectsName = "fix",
) -> FastResult

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

Segment images into n_classes tissue types (FSL’s fast).

FSL’s settings are the call’s (CLAUDE.md rule 6): the outputs are NIfTI-1 read back, and no FSL variable of the process reaches the program. Invalid arguments raise ValueError before anything runs (also the values FAST would use without meaning: FSL-99).

python
import larmorx as lx

# fMRIPrep's call: fast -I 0 -N -p -g -S 1 <T1w brain>
r = lx.fsl.fast(
    "T1w_brain.nii.gz", bias_iterations=0, no_bias=True, probabilities=True, segments=True
)
csf, gm, wm = r.partial_volumes          # lx.Image each, on the input's grid
labels = r.segmentation.data             # 1 CSF, 2 grey matter, 3 white matter, 0 outside

# The bias field and the corrected image, then a T2w + T1w pair (channel 1 first).
r = lx.fsl.fast("T1w_brain.nii.gz", bias_field=True, restored=True)
r2 = lx.fsl.fast(["T1w_brain.nii.gz", "T2w_brain.nii.gz"], restored=True)

Its result, FastResult, holds what fast wrote, read back (each on the input’s grid; channel 1’s header).

Field Type What it holds
segmentation Image The hard segmentation (_seg): each voxel’s class, 1 to n_classes, 0 outside the mask (int32).
segments tuple[Image, ...] | None With segments=True: one binary image per class (_seg_<n>, int32), else None.
probabilities tuple[Image, ...] | None With probabilities=True: each class’s posterior probability (_prob_<n>, float32), else None.
partial_volumes tuple[Image, ...] | None Each class’s partial-volume fraction (_pve_<n>, float32); None with pve=False.
pve_segmentation Image | None The segmentation by largest partial volume (_pveseg, int32), or None.
mixeltype Image | None Each voxel’s mixel type (_mixeltype, int32: 0 to n_classes - 1 a pure class, then the mixtures of two classes), or None.
restored tuple[Image, ...] | None With restored=True: each channel’s bias-corrected image (_restore for one channel, _restore_<n> for several), in channel order, else None.
bias_fields tuple[Image, ...] | None With bias_field=True: each channel’s estimated bias field (_bias, _bias_<n>), in channel order, else None.
stdout str FAST’s standard output (its diagnostic messages with verbose=True).

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 fast accepts (crates/larmorx-fsl/src/cli/fast.rs) and the arguments of lx.fsl.fast (python/larmorx/fsl/fast.py), whose defaults and descriptions are taken from it. Under each option, in grey, FSL’s own help for it.

fast option Python Default Notes
the last word(s) images one image (path or lx.Image), or a list of channels, channel 1 first (the command line names channel 1 last: larmorx fsl fast -S 2 -B -o out T2w_brain.nii.gz T1w_brain.nii.gz)
-S, --channels images the number of channels (default 1): the list’s lengthFSL: “number of input images (channels); default 1”
-n, --class n_classes 3 tissue classesFSL: “number of tissue-type classes; default=3”
-t, --type image_type "T1" "T1", "T2" (reverses the class order: brightest first), "PD"; 1, 2, 3 on the command lineFSL: “type of image 1=T1, 2=T2, 3=PD; default=T1”
-I, --iter bias_iterations 4 main-loop iterations with the bias fieldFSL: “number of main-loop iterations during bias-field removal; default=4”
-l, --lowpass bias_lowpass 20.0 the bias field’s smoothing (FWHM, mm)FSL: “bias field smoothing extent (FWHM) in mm; default=20”
-N, --nobias no_bias=True False no bias fieldFSL: “do not remove bias field”
-O, --fixed fixed_iterations 4 main-loop iterations after the bias field (also added to the initialisation’s iterations)FSL: “number of main-loop iterations after bias-field removal; default=4”
-W, --init init_iterations 15 initialisation iterationsFSL: “number of segmentation-initialisation iterations; default=15”
-f, --fHard initial_smoothness 0.02 the MRF weight while the bias field is estimatedFSL: “initial segmentation spatial smoothness (during bias field estimation); default=0.02”
-H, --Hyper smoothness 0.1 the MRF weight afterwardsFSL: “segmentation spatial smoothness; default=0.1”
-R, --mixel mixel_smoothness 0.3 the MRF weight of the mixel types (partial volumes)FSL: “spatial smoothness for mixeltype; default=0.3”
--nopve pve=False True no partial volumesFSL: “turn off PVE (partial volume estimation)”
-g, --segments segments=True False one binary image per classFSL: “outputs a separate binary image for each tissue type”
-p probabilities=True False each class’s posterior probabilityFSL: “outputs individual probability maps”
-B restored=True False the bias-corrected image(s)FSL: “output bias-corrected image”
-b bias_field=True False the bias field(s)FSL: “output estimated bias field”
-s, --manualseg manual_means None the initial class intensities: a file, or n_classes numbers (several channels: n_channels rows of n_classes)
-a priors_matrix None the standard-to-input FLIRT matrix (4 x 4 array or file): initialise from tissue priors registered with it
-A priors None the CSF, grey- and white-matter priors in standard space (three images); without them FSL’s standard priors from fsldirFSL: “alternative prior images”
-P, --Prior priors_throughout=True False use the priors in every iteration (needs priors_matrix)FSL: “use priors throughout; you must also set the -a option”
-o, --out the result the outputs’ basenameFSL: “output basename”
-v, --verbose verbose=True False FAST’s diagnostic messages (in the result’s stdout)FSL: “switch on diagnostic messages”
-h, --help command line only FSL: “display this message”
FSLDIR fsldir None the FSL installation whose data/standard/tissuepriors the standard priors come from (needed only for priors_matrix without priors)
OMP_NUM_THREADS n_threads 1 threads (0: all); the results do not depend on it (the clean room’s: the same bits on any count)
LARMORX_UPSTREAM_DEFECTS upstream_defects "fix" "reproduce": FSL’s defects as FSL has them

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 fsl on the command line (larmorx --n-threads 4 fsl fast ...) and are arguments of lx.fsl.fast. 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 results do 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): the replica when larmorx-nc is installed, else the clean room; "replica" or "clean-room" ("original", 0.1.0rc1’s spelling, still works). The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
upstream_defects="fix"
"fix" (default) or "reproduce": FSL’s defects corrected, or FSL’s behaviour (docs/api/fsl-fast.md, “Defects of the original, corrected by default”). 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: T1w_brain.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

# fMRIPrep's call: fast -I 0 -N -p -g -S 1 <T1w brain>
r = lx.fsl.fast(
    "T1w_brain.nii.gz", bias_iterations=0, no_bias=True, probabilities=True, segments=True
)
len(r.partial_volumes)  # -> 3
bash
larmorx fsl fast -I 0 -N -p -g -S 1 T1w_brain.nii.gz

Ports

fast has two ports: a replica and a clean room.

Port Package Licence Status Records
replica larmorx-nc FSL Licence: non-commercial use only experimental fsl-fast-replica
clean room larmorx Apache-2.0 experimental fsl-fast

The replica against FSL 6.0.7.23 itself (its record, the standard comparison): fMRIPrep’s call bit-identical in three of fMRIPrep’s runs (ds000005, an adult; ds000228, a 3.5-year-old; ds005003, a glioma), every file FAST writes, its standard output and error; every option, 2 to 8 channels, the priors, the odd inputs and every message, exit status and failure case of the command line: 59 of 59 compared cases bit-identical, 27 rejected by both alike, 1 refused where FSL reads past a smaller channel (FSL-104). With -a, FSL’s FLIRT is the replica’s own, run in the same process (no FSL installation needed when -A names the priors).

The clean room against FSL 6.0.7.23 (its record, the standard comparison, specs/fast.md §11’s thresholds, 2026-11-05): 64 of 65 compared cases within the thresholds, fMRIPrep’s three calls included (with reproduce, as FSL is built with glibc’s functions, fMRIPrep’s calls and every single-channel case FSL’s values bit for bit, two to eight channels FSL’s segmentations); 35 rejected by both alike (every abort and message of FSL’s, the lines of standard output an abort loses among them), 2 expected divergences (FSL-104’s refusal, and multi/s2-manualseg-cycle, below); the one outside, multi/s5, is explained (five channels with nearly singular covariances, decided by the matrix arithmetic’s last bits). Its default is held to the replica’s default (the same corrections): with glibc’s functions it is the replica’s default bit for bit on every single-channel case, and with its correctly rounded functions it stays within the narrow band of FSL-202’s corrected variance on one channel (fMRIPrep’s calls: the same labels as the replica’s default); several channels have no FSL-202, so there the two defaults lie FSL’s own last-bit band apart (multi/s3, multi/s2-n4: to every digit FSL against FSL with correctly rounded maths), and multi/s2-manualseg-cycle, whose defaults both correct FSL-98’s cycle, is the expected divergence measured in the findings. It is built for speed: fMRIPrep’s call on the standard comparison’s three T1w brains takes 2.4 to 5.2 s on one thread, 0.4 to 0.9 s on 14 (FSL 22 to 60 s, the replica 15 to 31 s).

FSL is distributed under the FSL Licence (non-commercial use only), so fast has two ports, a replica and a clean room, in different packages (licensing):

  • The replica is bit-exact: larmorx-nc fsl fast, in the package larmorx-nc (crates-nc/larmorx-nc-fast), under the FSL Licence’s terms, translated from FSL’s source.
  • The clean room is in the main package (crate larmorx-fsl, module fast, Apache-2.0), written from specs/fast.md, the FAST paper, FSL’s documentation and black-box runs of FSL’s program (PROVENANCE). It segments one channel and several (any number: -S 9 and more too, which the replica refuses), with the tissue priors (-a registered by LARMORX’s own FLIRT in this process, -A, -P).

implementation="auto" (the default) runs the replica when larmorx-nc is installed, else the clean room; "replica" needs larmorx-nc (pip install larmorx-nc; otherwise ReplicaNotFoundError); "clean-room" ("original", 0.1.0rc1’s spelling, still works) runs the clean room. The command line chooses alike (--implementation before the family, or LARMORX_IMPLEMENTATION).

Evidence

How each of fast’s ports was measured against FSL, case by case: its evidence.

More in the repository

The API page docs/api/fsl-fast.md holds what fast shares with the page’s other programs: