Programs · FSL

bet

bet finds the brain in a head image.

Original
FSL 6.0.7.23
Command line
larmorx fsl bet
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 writes the brain and, on request, its mask, its outline, an approximate skull and the brain’s surface as a mesh. It runs FSL’s brain extraction, bet2, alone or inside one of seven variations (below).

Command line

text
larmorx fsl bet <input> <output> [options]

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

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.

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

Main bet2 options:
  -o          generate brain surface outline overlaid onto original image
  -m          generate binary brain mask
  -s          generate approximate skull image
  -n          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 <r>      head radius (mm not voxels); initial surface sphere is set to half of this
  -c <x y z>  centre-of-gravity (voxels not mm) of initial mesh surface.
  -t          apply thresholding to segmented brain image and mask
  -e          generates brain surface as mesh in .vtk format

Variations on default bet2 functionality (mutually exclusive options):
  (default)   just run bet2
  -R          robust brain centre estimation (iterates BET several times)
  -S          eye & optic nerve cleanup (can be useful in SIENA - disables -o option)
  -B          bias field & neck cleanup (can be useful in SIENA)
  -Z          improve BET if FOV is very small in Z (by temporarily padding end slices)
  -F          apply to 4D FMRI data (uses -f 0.3 and dilates brain mask slightly)
  -A          run bet2 and then betsurf to get additional skull and scalp surfaces (includes registrations)
  -A2 <T2>    as with -A, when also feeding in non-brain-extracted T2 (includes registrations)

Miscellaneous options:
  -v          verbose (switch on diagnostic messages)
  -h          display this help, then exits
  -d          debug (don't delete temporary intermediate images)

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.

image is a path (any image FSL reads: NIfTI-1 or -2, single file or pair, gzipped or not, ANALYZE) or an in-memory image. Without variation it runs bet2. With "robust" (-R), "small_fov" (-Z) or "fmri" (-F) it runs the bet script. "eyes" (-S), "bias" (-B), "surfaces" (-A) and "surfaces_t2" (-A2, with t2) run the script with FLIRT, standard_space_roi, FAST, fslmaths, fslstats and betsurf; each port runs its own copies of those programs, in its own process. "surfaces" and "surfaces_t2" also return betsurf’s surfaces (BetResult.surfaces, a BetsurfResult with the masks, the skull’s mask and the outlines).

These four read FSL’s standard images, which are FSL’s data under the FSL Licence and which this package never ships. They come from fsl_data (a directory laid out as $FSLDIR/data), else from the variable LARMORX_FSL_DATA; when given, that is the only place looked. Otherwise the clean room reads them from the copy larmorx-nc installs (as data), else $FSLDIR/data, else larmorx’s data cache, filled once by a checksum-verified download of FSL’s fsl-data_standard package (larmorx fetch fsl-standard fetches it ahead; fsl-roi.md, “FSL’s standard images”). The replica reads $FSLDIR/data, else its own copy. An image found nowhere is refused before anything runs, naming the image and every place looked (a RuntimeError from the clean room).

The arguments are checked first (ValueError). FSL’s settings belong to the call: the outputs are written as NIfTI-1 and read back; FSLOUTPUTTYPE, FSL_LOAD_NIFTI_EXTENSIONS and every other FSL* variable of the process are never passed; and no FSL program is looked for on the PATH.

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 bet accepts (crates/larmorx-fsl/src/cli/bet.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 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.”
-t threshold=True False also thresholds the brain and maskFSL: “apply thresholding to segmented brain image and mask”
-m mask=True False FSL: “generate binary brain mask”
-o outline=True False FSL: “generate brain surface outline overlaid onto original image”
-s skull=True False FSL: “generate approximate skull image”
-n brain=False True FSL: “don’t generate segmented brain image output”
-e mesh=True False VTK; also switches the self-intersection test to the exact oneFSL: “generates brain surface as mesh in .vtk format”
-v (command line only) FSL: “verbose (switch on diagnostic messages)”
-h (command line only) FSL: “display this help, then exits”
--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
(bet2's -w) smoothness 1.0 bet2 only (bet does not pass it)
(bet2's --ct) head_ct=True False bet2 only: the input in Hounsfield units
LARMORX_FSL_DATA fsl_data None where -S, -B, -A and -A2 read FSL’s standard images (bet's Python call)
FSLOUTPUTTYPE (always NIfTI-1 in Python) on the command line read from the environment, as FSL does (unset: NIFTI_GZ, FSL-11)
bet option Python variation What it does
(none) None bet2
-R "robust" bet2 again from the brain’s centre until it moves less than a voxel (at most 11 runs); -n ignoredFSL: “robust brain centre estimation (iterates BET several times)”
-Z "small_fov" pads the image to 100 mm in z with copies of its end slices, crops back (FSL-45)FSL: “improve BET if FOV is very small in Z (by temporarily padding end slices)”
-F "fmri" the first volume’s mask (-f 0.3, then the user’s -f), dilated, applied to every volumeFSL: “apply to 4D FMRI data (uses -f 0.3 and dilates brain mask slightly)”
-S "eyes" SIENA’s eye and optic nerve cleanup: bet2 -s; standard_space_roi -b -d and bet2 -n -m -f 0.4 on its result; MNI152’s eye mask taken into the input (FLIRT -applyxfm through standard_space_roi’s inverse matrix), dilated (-dilF, 7 more in 2D) and removed from the brain mask, the premask’s brain added; what is brighter than 3.5 standard deviations above the brain’s mean (fslstats -M, -S, GNU dc: FSL-216) removed with a little morphology; the mask (_mask) and the skull without the eyes (_skull) always written; no outline or mesh (-o, -e only in its temporary run); with -n it fails (brain=False refused)FSL: “eye & optic nerve cleanup (can be useful in SIENA - disables -o option)”
-B "bias" SIENA’s bias field and neck cleanup: standard_space_roi -b -d, FAST’s bias field (fast -b, its messages discarded), the input divided by it; with -s the skull from standard_space_roi -maskFOV -roiNONE -d and bet2, moved by fslpy’s immv (and -s removed from the options through echo: FSL-63); standard_space_roi -b -d again and bet -m -R -d on its result (the brain and mask always written: -R removes -n)FSL: “bias field & neck cleanup (can be useful in SIENA)”
-A "surfaces" FLIRT to MNI152_T1_2mm (the matrix), bet2 -e, betsurf --t1only -o -m -s: the brain, its mesh, the three surfaces, their masks and outlines, the skull’s maskFSL: “run bet2 and then betsurf to get additional skull and scalp surfaces (includes registrations)”
-A2 <T2> "surfaces_t2", t2 the T2 registered to the input by FLIRT (-interp sinc), then as -A with betsurf -o -m -s on the registered T2FSL: “as with -A, when also feeding in non-brain-extracted T2 (includes registrations)”
(the last of -R, -S, -Z, -F, -A, -A2, -B given) the variation run
-d (command line only) keeps the temporary filesFSL: “debug (don’t delete temporary intermediate images)”

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 bet ...) 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: boldref.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

# As fMRIPrep calls BET on its BOLD reference.
r = lx.fsl.bet("boldref.nii.gz", frac=0.2, mask=True)
r.brain, r.mask
# The port that ran: the clean room of larmorx,
# or the replica once larmorx-nc is installed.
r.mask.implementation

# The same call, the clean room chosen.
c = lx.fsl.bet("boldref.nii.gz", frac=0.2, mask=True, implementation="clean-room")
c.mask.implementation.kind  # -> 'clean-room'
bash
larmorx fsl bet boldref.nii.gz boldref_brain.nii.gz -f 0.20 -m

Ports

bet 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 is within the thresholds in 198 of the 200 compared cases of its record, which holds the same programs. One of the two others is bet’s: a 3.5-year-old’s bet -B. The boundaries of its brain and mask lie up to 2.24 voxels from FSL’s, where the threshold is 2, and the mask’s boundary distance at the 95th percentile is 1.0 voxel, where the threshold is 0.5. Their Dice coefficients, 0.9989 and 0.9983, are within the threshold of 0.995.

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 bet’s ports was measured against FSL, case by case: its evidence.

On the same page, for bet: The standard images the variations read.

More in the repository

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