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-ncFSL Licence: non-commercial use only validated - clean room
larmorxApache-2.0 experimental
- replica
- 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
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):
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
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
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",
) -> BetResultWhere 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 Nn_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-roomimplementation="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|reproduceupstream_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.
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'larmorx fsl bet boldref.nii.gz boldref_brain.nii.gz -f 0.20 -mPorts
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-ncholds it, under FSL’s licence, andlarmorxruns it as a separate program,larmorx-nc fsl bet|bet2|betsurf, whenlarmorx-ncis 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 oflarmorx, 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: