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-ncFSL Licence: non-commercial use only experimental - clean room
larmorxApache-2.0 experimental
- replica
- 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
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):
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
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 mapsPython
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",
) -> FastResultWhere 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).
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 Nn_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-roomimplementation="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|reproduceupstream_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.
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) # -> 3larmorx fsl fast -I 0 -N -p -g -S 1 T1w_brain.nii.gzPorts
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 packagelarmorx-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, modulefast, Apache-2.0), written fromspecs/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 9and more too, which the replica refuses), with the tissue priors (-aregistered 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: