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-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-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
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):
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
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<uthreshPython
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",
) -> strWhere 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_maskand the image operands (-k,-d) arelx.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=Truegives each number at full precision (a decimal that reads back to the same double, as nlohmann/json writes it; NaN and the infinities asnull). - 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:
ValueErrorfor invalid arguments,larmorx.ReplicaErrorwhen the replica fails (its message in the error, without the usage text),RuntimeErrorwhen the clean room does,larmorx.ReplicaNotFoundErrorwithoutlarmorx-nc. - The typed wrappers (
lx.fsl.image_meanand the others in the options table) choose the voxels in a fixed order (The typed wrappers); for another order callfslstats().
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 Nn_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-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-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.
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'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 50Ports
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 packagelarmorx-nc, under the FSL Licence’s terms, translated from FSL’s source. The program is incrates-nc/larmorx-nc-core, because BET’s script runs it, with its command line incrates-nc/larmorx-nc-avwutils. - The clean room is in the main package (Apache-2.0, crate
larmorx-fsl, itscli::fslstats), written fromspecs/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: