Programs · FSL

fslstats

fslstats prints statistics of an image, per volume, per label or as JSON.

Original
FSL 6.0.7.23
Command line
larmorx fsl fslstats
Python
lx.fsl.fslstats
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-stats.md and the code

What it does

Its options apply in order: thresholds, masks, absolute values and a difference image change what the later options see; the others print the mean, standard deviation, minimum and maximum, robust range, percentiles, entropy, voxel count and volume, centre of gravity, the extremes’ coordinates, the bounding box of the nonzero voxels or a histogram. With -t it prints one line per volume, with -K one per label of an index image, with -json everything as JSON.

Order matters: -k replaces the masks the thresholds made, as a later threshold replaces -k’s, so fslstats img -M -l 10 -M reports the nonzero mean, applies a threshold, then reports the new nonzero mean.

Command line

text
larmorx fsl fslstats [preoptions] <input> [options]

Everything after larmorx fsl fslstats is the original’s command line: the arguments of FSL 6.0.7.23’s fslstats, 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 fslstats ...

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.

fslstats's usage text, as the clean room prints it
text
Usage: fslstats [preoptions] <input> [options]

preoption -json: output in JSON format to standard out
preoption -t will give a separate output line for each 3D volume of a 4D timeseries
preoption -K < indexMask > will generate seperate n submasks from indexMask, for indexvalues 1..n where n is the maximum index value in indexMask, and generate statistics for each submask
Note - options are applied in order, e.g. -M -l 10 -M will report the non-zero mean, apply a threshold and then report the new nonzero mean

-l <lthresh> : set lower threshold
-u <uthresh> : set upper threshold
-r           : output <robust min intensity> <robust max intensity>
-R           : output <min intensity> <max intensity>
-e           : output mean entropy ; mean(-i*ln(i))
-E           : output mean entropy (of nonzero voxels)
-v           : output <voxels> <volume>
-V           : output <voxels> <volume> (for nonzero voxels)
-m           : output mean
-M           : output mean (for nonzero voxels)
-s           : output standard deviation
-S           : output standard deviation (for nonzero voxels)
-w           : output smallest ROI <xmin> <xsize> <ymin> <ysize> <zmin> <zsize> <tmin> <tsize> containing nonzero voxels
-x           : output co-ordinates of maximum voxel
-X           : output co-ordinates of minimum voxel
-c           : output centre-of-gravity (cog) in mm coordinates
-C           : output centre-of-gravity (cog) in voxel coordinates
-p <n>       : output nth percentile (n between 0 and 100)
-P <n>       : output nth percentile (for nonzero voxels)
-a           : use absolute values of all image intensities
-n           : treat NaN or Inf as zero for subsequent stats
-k <mask>    : use the specified image (filename) for masking - overrides lower and upper thresholds
-d <image>   : take the difference between the base image and the image specified here
-h <nbins>   : output a histogram (for the thresholded/masked voxels only) with nbins
-H <nbins> <min> <max>   : output a histogram (for the thresholded/masked voxels only) with nbins and histogram limits of min and max
Note - thresholds are not inclusive ie lthresh<allowed<uthresh

Python

python
lx.fsl.fslstats(
    image: Any,
    *options: Any,
    timeseries: bool = False,
    index_mask: Any = None,
    json: bool = False,
    n_threads: int = 1,
    implementation: ImplementationName = "auto",
    upstream_defects: UpstreamDefectsName = "fix",
) -> str

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

Run fslstats’ options on image, as fslstats [-t] [-K <index_mask>] [-json] <image> <options...> does, and return its standard output.

  • image, index_mask and the image operands (-k, -d) are lx.Images, nibabel images, (array, affine) pairs or paths (in-memory images written for the program in their own data type); options are fslstats’ own words, numbers passed as their shortest round-trip text.
  • The program runs in the caller’s working directory: relative names are read there.
  • Numbers: the text output has six decimals (%.6f), as nipype reads it for fMRIPrep; json=True gives each number at full precision (a decimal that reads back to the same double, as nlohmann/json writes it; NaN and the infinities as null).
  • FSL’s environment variables are settings of the call, never read from the process. FSL’s fslstats runs on one thread; the clean room runs on n_threads, with the same results at any count.
  • Errors: ValueError for invalid arguments, larmorx.ReplicaError when the replica fails (its message in the error, without the usage text), RuntimeError when the clean room does, larmorx.ReplicaNotFoundError without larmorx-nc.
  • The typed wrappers (lx.fsl.image_mean and the others in the options table) choose the voxels in a fixed order (The typed wrappers); for another order call fslstats().
python
import larmorx as lx

# fMRIPrep's goodvoxels mask: fslstats <cov_ribbon> -M, then -S (the nonzero voxels)
m = lx.fsl.image_mean("cov_ribbon.nii.gz", nonzero=True)
s = lx.fsl.image_std("cov_ribbon.nii.gz", nonzero=True)
upper = m + 0.5 * s

# BET's script: the centre of gravity, in voxels, of the voxels above a threshold
cog = lx.fsl.centre_of_gravity("t1w.nii.gz", lower=0.001, voxels=True)

# per volume, per label, in a mask
means = lx.fsl.image_mean("bold.nii.gz", per_volume=True)            # shape (n_volumes,)
by_label = lx.fsl.image_mean("t1w.nii.gz", labels="labels.nii.gz")   # shape (n_labels,)

# any option list, in fslstats' own words; JSON for full precision
text = lx.fsl.fslstats("t1w.nii.gz", "-M", "-l", 10, "-M")
doc = lx.fsl.fslstats("t1w.nii.gz", "-r", "-p", 50, json=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 fslstats accepts (crates/larmorx-fsl/src/cli/fslstats.rs) and the arguments of lx.fsl.fslstats (python/larmorx/fsl/stats.py), whose defaults and descriptions are taken from it. Under each option, in grey, FSL’s own help for it.

fslstats option Python Default Notes
the first word after the preoptions image the image
-t timeseries=True False one line per volumeFSL: “will give a separate output line for each 3D volume of a 4D timeseries”
-K index_mask None one line per label 1…n of the 3D label imageFSL: “will generate seperate n submasks from indexMask, for indexvalues 1…n where n is the maximum index value in indexMask, and generate statistics for each submask”
-json json=True False the numbers in JSON, at full precision; NaN and the infinities as nullFSL: “output in JSON format to standard out”
-l, -u options the voxels strictly between (the typed wrappers’ lower=, upper=)FSL: “set lower threshold”FSL: “set upper threshold”
-k options the voxels where the mask is above 0.5 (it overrides thresholds, as a later threshold overrides it; the typed wrappers’ mask=)FSL: “use the specified image (filename) for masking - overrides lower and upper thresholds”
-d options the image minus this one first (the typed wrappers’ difference=)FSL: “take the difference between the base image and the image specified here”
-a options absolute values first (the typed wrappers’ absolute=True)FSL: “use absolute values of all image intensities”
-n options NaN and infinities as 0 first (the typed wrappers’ nan_as_zero=True)FSL: “treat NaN or Inf as zero for subsequent stats”
-m, -M options; lx.fsl.image_mean(image, nonzero=False) the mean (of the nonzero voxels)FSL: “output mean”FSL: “output mean (for nonzero voxels)”
-s, -S options; lx.fsl.image_std(image, nonzero=False) the standard deviation (of the nonzero voxels)FSL: “output standard deviation”FSL: “output standard deviation (for nonzero voxels)”
-p, -P options; lx.fsl.image_percentile(image, percent, nonzero=False) the percentile, percent in [0, 100]FSL: “output nth percentile (n between 0 and 100)”FSL: “output nth percentile (for nonzero voxels)”
-R, -r options; lx.fsl.image_range(image, robust=False) [min, max], or the robust range (FSL’s 2 %-98 % histogram limits)FSL: “output <min intensity> <max intensity>”FSL: “output <robust min intensity> <robust max intensity>”
-e, -E options; lx.fsl.image_entropy(image, nonzero=False) the mean entropy of the intensities’ histogramFSL: “output mean entropy ; mean(-i*ln(i))”FSL: “output mean entropy (of nonzero voxels)”
-v, -V options; lx.fsl.image_volume(image, nonzero=False) [voxels, mm³]FSL: “output <voxels> <volume>”FSL: “output <voxels> <volume> (for nonzero voxels)”
-c, -C options; lx.fsl.centre_of_gravity(image, voxels=False) [x, y, z] in mm, or in voxel coordinatesFSL: “output centre-of-gravity (cog) in mm coordinates”FSL: “output centre-of-gravity (cog) in voxel coordinates”
-x, -X options; lx.fsl.extremum_position(image, minimum=False) the voxel coordinates of the maximum (minimum)FSL: “output co-ordinates of maximum voxel”FSL: “output co-ordinates of minimum voxel”
-w options; lx.fsl.bounding_roi(image) [xmin, xsize, ymin, ysize, zmin, zsize, tmin, tsize] of the nonzero voxels, as lx.fsl.roi takes a regionFSL: “output smallest ROI <xmin> <xsize> <ymin> <ysize> <zmin> <zsize> <tmin> <tsize> containing nonzero voxels”
-h, -H options; lx.fsl.image_histogram(image, bins, limits=None) the counts in bins bins over the image’s range (-h) or limits (-H)FSL: “output a histogram (for the thresholded/masked voxels only) with nbins”FSL: “output a histogram (for the thresholded/masked voxels only) with nbins and histogram limits of min and max”
-D options (hidden in FSL’s usage) the sum of every value, masks ignored (specs/fslstats.md §5.2)
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 fslstats ...) and are arguments of lx.fsl.fslstats. 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) for writing in-memory images, and the clean room’s own; the same results at any count. 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-stats.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.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), bold.nii.gz (a synthetic series of 4 such heads). The command lines run as python -m larmorx.

python
import larmorx as lx

# BET's script: the centre of gravity, in voxels, of the voxels above a threshold
cog = lx.fsl.centre_of_gravity("t1w.nii.gz", lower=0.001, voxels=True)
len(cog)  # -> 3
# One mean per volume of a series.
lx.fsl.image_mean("bold.nii.gz", per_volume=True).shape  # -> (4,)
# Any option list, in fslstats' own words: the nonzero mean, then above a threshold.
lx.fsl.fslstats("t1w.nii.gz", "-M", "-l", 100, "-M")  # -> '124.499801 498.625669 \n'
bash
larmorx fsl fslstats t1w.nii.gz -M -S
larmorx fsl fslstats -t bold.nii.gz -m
larmorx fsl fslstats -json t1w.nii.gz -r -p 50

Ports

fslstats 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-stats-replica
clean room larmorx Apache-2.0 experimental fsl-stats

Both ports take every option, preoption (-t, -K, -json), message, exit status and failure case of FSL’s, and correct the defects FSL-181 to FSL-189.

The replica against FSL 6.0.7.23 itself (its record, the standard comparison, 2026-11-03): 172 of 172 compared cases identical, their standard output, standard error and exit status; 36 more rejected by both alike. Among them fMRIPrep’s four goodvoxels calls (-M and -S of the ribbon’s coefficient of variation, before and after its modulation) on ds005040’s chain (the ribbon a stand-in: the segmentation’s grey matter, as the no-reconall runs have no FreeSurfer ribbon), BET’s -l 0.001 -C on ds005040’s T1w, the option lists of FSL’s own test script against its expected outputs, and random testing’s permanent cases.

The clean room against FSL 6.0.7.23 (its record, the standard comparison, 2026-11-04, specs/fslstats.md §10’s thresholds): 162 cases, 126 within the thresholds, 36 rejected by both alike, 0 failures. 125 of the 126 are identical to FSL’s (standard output, standard error, exit status), fMRIPrep’s four goodvoxels calls on ds005040’s chain among them; BET’s -l 0.001 -C on ds005040’s T1w is within §10’s bound (its x 6.1e-8 relative from FSL’s).

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

  • The replica is bit-exact: larmorx-nc fsl fslstats, in the package larmorx-nc, under the FSL Licence’s terms, translated from FSL’s source. The program is in crates-nc/larmorx-nc-core, because BET’s script runs it, with its command line in crates-nc/larmorx-nc-avwutils.
  • The clean room is in the main package (Apache-2.0, crate larmorx-fsl, its cli::fslstats), written from specs/fslstats.md, FSL’s documentation and black-box runs of FSL’s program (PROVENANCE).

implementation="auto" (the default) runs the replica when larmorx-nc is installed, the clean room otherwise; "replica" needs larmorx-nc (otherwise ReplicaNotFoundError); "clean-room" ("original", 0.1.0rc1’s spelling, still works) runs the clean room in this process on n_threads threads (its results the same at any count; a failure raises RuntimeError with its messages). The command line chooses alike (--implementation before the family, or LARMORX_IMPLEMENTATION).

Evidence

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

More in the repository

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