Programs · FSL

bet2

bet2 is FSL’s brain extraction itself, which the bet script runs.

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

What it does

It deforms a tessellated sphere onto the brain’s surface in a head image and writes the brain and, on request, its mask, its outline, an approximate skull and the surface as a mesh.

Command line

text
larmorx fsl bet2 <input_fileroot> <output_fileroot> [options]

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

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.

bet2's usage text, as the clean room prints it
text
Part of FSL (ID: 2412.6-dirty)
BET (Brain Extraction Tool) v2.1 - FMRIB Analysis Group, Oxford

Usage: 
bet2 <input_fileroot> <output_fileroot> [options]

Optional arguments (You may optionally specify one or more of):
	-o,--outline	generate brain surface outline overlaid onto original image
	-m,--mask	generate binary brain mask
	-s,--skull	generate approximate skull image
	-n,--nooutput	don't generate segmented brain image output
	-f <f>		fractional intensity threshold (0->1); default=0.5; smaller values give larger brain outline estimates
	-g <g>		vertical gradient in fractional intensity threshold (-1->1); default=0; positive values give larger brain outline at bottom, smaller at top
	-r,--radius <r>	head radius (mm not voxels); initial surface sphere is set to half of this
	-w,--smooth <r>	smoothness factor; default=1; values smaller than 1 produce more detailed brain surface, values larger than one produce smoother, less detailed surface
	-c <x y z>	centre-of-gravity (voxels not mm) of initial mesh surface.
	-t,--threshold	-apply thresholding to segmented brain image and mask
	--ct	-treat input as CT image (default is MRI)
	--binaryMask <image>	Generate mesh from existing mask
	-e,--mesh	generates brain surface as mesh in vtk format
	-v,--verbose	switch on diagnostic messages
	-h,--help	displays this help, then exits

Python

python
lx.fsl.bet(
    image: Any,
    *,
    frac: float = 0.5,
    gradient: float = 0.0,
    radius: float | None = None,
    centre: Sequence[float] | None = None,
    smoothness: float = 1.0,
    threshold: bool = False,
    head_ct: bool = False,
    variation: Variation | None = None,
    t2: Any = None,
    brain: bool = True,
    mask: bool = False,
    outline: bool = False,
    skull: bool = False,
    mesh: bool = False,
    tanh: Tanh = "glibc",
    fsl_data: str | os.PathLike[str] | None = None,
    n_threads: int = 1,
    implementation: ImplementationName = "auto",
    upstream_defects: UpstreamDefectsName = "fix",
) -> BetResult

Where Variation is one of "robust", "small_fov", "fmri", "eyes", "bias", "surfaces", "surfaces_t2"; Tanh is one of "glibc", "correctly-rounded"; ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room"); UpstreamDefectsName is one of "fix", "reproduce".

The brain, as FSL’s bet2 (or, with variation, the bet script) extracts it.

lx.fsl.bet without variation runs bet2 (the function’s description: bet).

Its result, BetResult, holds what bet computed (None for what was not asked for).

Field Type What it holds
brain Image | None The input with every voxel outside the brain 0 (float32; 4D with "fmri").
mask Image | None The brain mask (int16, 1 inside).
outline Image | None The surface drawn on the input at its maximum (float32; -o).
skull Image | None An approximate skull (int16; -s).
mesh Surface | None The brain’s surface (-e): its vertices (n, 3) in FSL’s millimetre coordinates and its triangles (m, 3).
surfaces BetsurfResult | None The inner skull, outer skull and scalp surfaces, their masks, the skull’s mask and the surfaces’ outlines ("surfaces" and "surfaces_t2": betsurf -o -m -s).

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

FSL option Python Default Notes
<input> <output> image; the result outputs <output>, _mask, _overlay, _skull, _mesh.vtk
-f <f> frac 0.5 0 to 1; smaller gives a larger brainFSL: “fractional intensity threshold (0->1); default=0.5; smaller values give larger brain outline estimates”
-g <g> gradient 0.0 -1 to 1; positive gives a larger brain at the bottomFSL: “vertical gradient in fractional intensity threshold (-1->1); default=0; positive values give larger brain outline at bottom, smaller at top”
-r <r>, --radius radius None mm; the initial sphere is half of itFSL: “head radius (mm not voxels); initial surface sphere is set to half of this”
-c <x y z> centre None voxels of the file as stored; 0 0 0 is “not given” (the centre of gravity), as in FSLFSL: “centre-of-gravity (voxels not mm) of initial mesh surface.”
-w <r>, --smooth smoothness 1.0 bet2 only (bet does not pass it)FSL: “smoothness factor; default=1; values smaller than 1 produce more detailed brain surface, values larger than one produce smoother, less detailed surface”
-t, --threshold threshold=True False also thresholds the brain and maskFSL: “apply thresholding to segmented brain image and mask”
--ct head_ct=True False bet2 only: the input in Hounsfield unitsFSL: “treat input as CT image (default is MRI)”
-m, --mask mask=True False FSL: “generate binary brain mask”
-o, --outline outline=True False FSL: “generate brain surface outline overlaid onto original image”
-s, --skull skull=True False FSL: “generate approximate skull image”
-n, --nooutput brain=False True FSL: “don’t generate segmented brain image output”
-e, --mesh mesh=True False VTK; also switches the self-intersection test to the exact oneFSL: “generates brain surface as mesh in vtk format”
-v, --verbose (command line only) FSL: “switch on diagnostic messages”
--binaryMask <image> (command line only) FSL: “Generate mesh from existing mask”
-h, --help (command line only) FSL: “displays this help, then exits”
--parameter_d1=, --parameter_d2= (command line only) hidden search depths (7 and 3)
--tanh=correctly-rounded (LARMORX’s own option; also --tanh correctly-rounded, and passed on by bet) tanh="correctly-rounded" "glibc" computes the surface’s smoothness weight with the correctly rounded tanh (CORE-MATH’s, larmorx_core::math::tanh) instead of glibc 2.35’s, which FSL calls and which is the default (glibc; decision GLIBC-06). No notice: it is asked for. Where a surface self-intersects and is found again, the last bit can change the result (4 of the 13 real images of the clean room’s standard comparison: its findings). Clean room only: implementation="replica" refuses it, and "auto" runs the clean room
FSLOUTPUTTYPE (always NIfTI-1 in Python) on the command line read from the environment, as FSL does (unset: NIFTI_GZ, FSL-11)
(bet's variations) variation, t2, fsl_data variation=None, t2=None, fsl_data=None bet only (its options)

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 bet2 ...) and are arguments of lx.fsl.bet. 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"
"auto" (default): the replica in larmorx-nc when it is installed, else the clean room (always the clean room with tanh="correctly-rounded"); "replica": the replica (ReplicaNotFoundError without it); "clean-room": the clean room (FSL’s behaviour within the thresholds of its validation record, docs/validation/fsl-bet.md). The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
upstream_defects="fix"
"fix" (default) or "reproduce" (FSL’s output); an UpstreamDefectWarning names each defect that changed the result. 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). The command lines run as python -m larmorx.

python
import larmorx as lx

b = lx.fsl.bet("T1w.nii.gz", mesh=True)
b.brain, b.mesh
bash
larmorx fsl bet2 T1w.nii.gz T1w_brain -e

Ports

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

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

The replica gives FSL 6.0.7.23’s exit status, messages and files byte for byte in 201 of the 263 cases of its record, which holds bet, bet2, betsurf, standard_space_roi and fslroi; 47 more are rejected by both. The clean room’s record holds the same programs. Of its 380 brains, masks and outlines (betsurf’s counted apart), 378 are FSL’s bit for bit; the two others are bet -B’s. 11 of 11 meshes have FSL’s vertices to the file’s 6 decimals.

FSL’s licence allows non-commercial use only, so the two ports of bet, bet2 and betsurf, a replica and a clean room, live in different packages (licensing says what each package holds):

  • The replica is translated from FSL’s source. The package larmorx-nc holds it, under FSL’s licence, and larmorx runs it as a separate program, larmorx-nc fsl bet|bet2|betsurf, when larmorx-nc is installed (pip install larmorx-nc).
  • The clean room is written from specs/bet.md, the BET paper and runs of FSL, without FSL’s source or the replica. It is part of larmorx, under Apache-2.0 (crates/larmorx-fsl, with its PROVENANCE).

implementation="auto" runs the replica when larmorx-nc is installed, and the clean room otherwise. "replica" and "clean-room" choose one ("original", 0.1.0rc1’s spelling of "clean-room", still works). Each image’s implementation names the port that ran. On the command line, --implementation auto|replica|clean-room before the family chooses alike, from the next release; in 0.1.0rc1 the variable LARMORX_IMPLEMENTATION chooses (original for the clean room).

Evidence

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

More in the repository

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