Programs · FSL

prelude

prelude unwraps a phase image (radians) inside a mask.

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

What it does

The masked phase is split into regions of similar wrapped phase, which are merged, the best-agreeing pair first, each moved by the whole number of 2 pi turns that best joins it to its neighbour. The result is the unwrapped phase in radians, 0 outside the mask. sdcflows (fMRIPrep) runs it on the phase difference of a phase-difference field map before converting it to a field in Hz: prelude --abs=<magnitude> --mask=<mask> --phase=<phase difference> --unwrap=<out>.

Command line

text
larmorx fsl prelude -c <rawphase> -o <unwrappedphase> [options]
larmorx fsl prelude -p <phasevol> -a <absvol> -o <unwrappedphase> [options]

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

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.

prelude's usage text, as the clean room prints it
text
Part of FSL (ID: 2412.6-dirty)
prelude (Version 2.0 in c# minor)
Phase Region Expanding Labeller for Unwrapping Discrete Estimates
Copyright(c) 2001, University of Oxford (Mark Jenkinson)

Usage: 
prelude -c <rawphase> -o <unwrappedphase> [options]
prelude -p <phasevol> -a <absvol> -o <unwrappedphase> [options]

Compulsory arguments (You MUST set one or more of):
	-o,--out,-u,--unwrap	filename for saving the unwrapped phase output

Optional arguments (You may optionally specify one or more of):
	-c,--complex	filename of complex phase input volume
	-a,--abs	filename of absolute input volume
	-p,--phase	filename of raw phase input volume
	-n,--numphasesplit	number of phase partitions to use
	--labelslices	does label processing in 2D (slice at a time)
	-s,--slices	does all processing in 2D (slice at a time)
	-f,--force3D	forces all processing to be full 3D
	-t,--thresh	intensity threshold for masking
	-m,--mask	filename of mask input volume
	--start	first image number to process (default 0)
	--end	final image number to process (default Inf)
	--savemask	filename for saving the mask volume
	-r,--rawphase	filename for saving the raw phase output
	-l,--labels	filename for saving the area labels output
	--removeramps	remove phase ramps during unwrapping
	-v,--verbose	switch on diagnostic messages
	-h,--help	display this message

Python

python
lx.fsl.prelude(
    phase: Any = None,
    magnitude: Any = None,
    *,
    complex_image: Any = None,
    mask: Any = None,
    threshold: float | None = None,
    num_phase_split: int = 8,
    slices: bool = False,
    label_slices: bool = False,
    force_3d: bool = False,
    start: int | None = None,
    end: int | None = None,
    remove_ramps: bool = False,
    save_mask: bool = False,
    save_labels: bool = False,
    save_raw_phase: bool = False,
    verbose: bool = False,
    implementation: ImplementationName = "auto",
    upstream_defects: UpstreamDefectsName = "fix",
    n_threads: int = 1,
) -> PreludeResult

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

FSL’s prelude: the phase of phase (radians; a range above 3 pi is refused, values beyond [-pi, pi] are rewrapped first) unwrapped inside a mask, with magnitude (-p, -a), or the phase and magnitude of complex_image (-c: complex values) instead.

Inputs are paths or in-memory images (an lx.Image, a nibabel image, an (array, affine) pair); in-memory images are written to a temporary directory in their own type (uint8, int16, int32, float32, float64; other types as float32; a complex array as complex64). A run that fails raises ReplicaError (a RuntimeError) with prelude’s messages. The function checks its arguments before running anything (ValueError): complex_image or phase and magnitude together, num_phase_split of at least 2, start and end not negative.

python
import larmorx as lx

# fMRIPrep's call: a phase difference (radians) with its magnitude and brain mask
res = lx.fsl.prelude("phasediff_rad.nii.gz", "magnitude.nii.gz", mask="mask.nii.gz")
res.unwrapped            # lx.Image, float32, radians

# a complex image, the masks and labels returned, the linear ramps removed during unwrapping
res = lx.fsl.prelude(complex_image="complex.nii.gz", remove_ramps=True,
                     save_mask=True, save_labels=True)
res.mask, res.labels

Its result, PreludeResult, holds what prelude wrote, read back.

Field Type What it holds
unwrapped Image The unwrapped phase in radians (--unwrap, float32): one volume per processed volume (start to end), 0 outside the mask.
mask Image | None With save_mask=True: the mask each volume was unwrapped in (--savemask, float32, 1 inside), else None.
labels Image | None With save_labels=True: the regions’ labels (--labels, int32; 0 outside the mask), else None.
raw_phase Image | None With save_raw_phase=True: the wrapped phase as prelude used it (--rawphase: the input phase, every volume, rewrapped to [-pi, pi] where it lay outside), else None.
stdout str prelude’s standard output (its diagnostic messages with verbose=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 prelude accepts (crates/larmorx-fsl/src/cli/prelude.rs) and the arguments of lx.fsl.prelude (python/larmorx/fsl/prelude.py), whose defaults and descriptions are taken from it. Under each option, in grey, FSL’s own help for it.

prelude option Python Default Notes
-p, --phase <image> phase (first argument) None the wrapped phase, radians; a range (maximum minus minimum) above 3 pi is refused (exit 255), values beyond [-pi, pi] are rewrapped firstFSL: “filename of raw phase input volume”
-a, --abs <image> magnitude (second argument) None the magnitude, for the mask; with -p onlyFSL: “filename of absolute input volume”
-c, --complex <image> complex_image None a complex image instead of -p and -a: its phase and magnitudeFSL: “filename of complex phase input volume”
-o, --out, -u, --unwrap <name> the result the unwrapped phase (compulsory): the result’s unwrappedFSL: “filename for saving the unwrapped phase output”
-m, --mask <image> mask None the mask (thresholded at 0.5 unless -t is given); its last volume serves the volumes beyond itFSL: “filename of mask input volume”
-t, --thresh <value> threshold None the mask’s threshold on the magnitude (default: 10 % of the way from the 2nd to the 98th percentile); the largest connected part above it is keptFSL: “intensity threshold for masking”
-n, --numphasesplit <n> num_phase_split 8 the number of phase intervals the regions are first split into (at least 2)FSL: “number of phase partitions to use”
-s, --slices slices=True False labels and unwraps slice by slice, then joins the slicesFSL: “does all processing in 2D (slice at a time)”
--labelslices label_slices=True False labels slice by slice (automatic when the image is larger than 64 voxels along x or y), unwraps in 3DFSL: “does label processing in 2D (slice at a time)”
-f, --force3D force_3d=True False everything in 3D (overrides -s, --labelslices and the automatic 2D labels)FSL: “forces all processing to be full 3D”
--start=<n> start None the first volume processed (from 0)FSL: “first image number to process (default 0)”
--end=<n> end None the last volume processed (default: the last)FSL: “final image number to process (default Inf)”
--removeramps remove_ramps=True False removes the linear phase ramps before unwrapping and restores them afterFSL: “remove phase ramps during unwrapping”
--savemask=<name> save_mask=True False the mask used: the result’s maskFSL: “filename for saving the mask volume”
-l, --labels <name> save_labels=True False the regions’ labels (int32): the result’s labelsFSL: “filename for saving the area labels output”
-r, --rawphase <name> save_raw_phase=True False the wrapped phase as prelude used it (rewrapped where it was outside [-pi, pi]): the result’s raw_phaseFSL: “filename for saving the raw phase output”
-v, --verbose verbose=True False diagnostic messages: the result’s stdoutFSL: “switch on diagnostic messages”
-h, --help command line only the usage (exit 1)FSL: “display this message”
FSLOUTPUTTYPE NIfTI, read back the output files’ type; the function sets it and never reads the caller’s FSL variables
OMP_NUM_THREADS n_threads 1 threads: the replica’s for reading and writing the images; the clean room’s also for the mask, the regions, the ramps and the slices of -s (the merging itself is sequential: its order is the result); the same bits at any count

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 prelude ...) and are arguments of lx.fsl.prelude. 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 replica’s for reading and writing the images, the clean room’s also for the mask, the regions, the ramps and the slices; the same bits 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-prelude.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: phasediff.nii.gz (a phase ramp along x, wrapped into [−pi, pi), on the head’s grid), magnitude.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

# A wrapped phase difference (radians) and its magnitude, as fMRIPrep gives them.
res = lx.fsl.prelude("phasediff.nii.gz", "magnitude.nii.gz")
res.unwrapped.shape  # -> (40, 48, 40)
bash
larmorx fsl prelude -p phasediff.nii.gz -a magnitude.nii.gz -o unwrapped

Ports

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

With reproduce both ports give FSL’s result bit for bit. By default they agree bit for bit too, except the phase of a complex image (-c): the clean room’s arctangent is correctly rounded, glibc’s atan2f (FSL’s, and the replica’s) is not, so a few phases differ in their last bit (GLIBC-07, named), and the unwrapped phase keeps FSL’s whole turns.

  • The replica against FSL 6.0.7.23 (the record fsl-prelude-replica, 88 cases: 68 identical to FSL, 20 where both refuse alike): bit-identical exit status, messages and files on every option, output type and failure case; fMRIPrep 25.2.6’s seven prelude calls on four of its runs (ds005454, ds002603, ds002422, ds001600) bit-identical to FSL and to fMRIPrep’s own outputs. larmorx-nc’s 15 cases and 4 failures of its cross-platform checks (crates-nc/larmorx-nc-cli/tests/golden.rs) run on every platform.
  • The clean room against FSL 6.0.7.23 (its record, 166 cases: 138 within its thresholds, 28 refused alike): the replica’s cases, the clean room standing in for the replica’s program; its own cases (every option, image type, NaN input, failure and output type) with reproduce bit-identical to FSL (headers whole, the pair’s extension bytes included) and by default bit-identical to the replica’s default (GLIBC-07’s phases by their whole turns); fMRIPrep’s seven calls bit-identical to fMRIPrep’s own outputs in both modes. Its cross-platform checks: cli.fsl.prelude, cli.fsl.prelude.reproduce and py.fsl.prelude (tests/golden/registry.py), on every platform. Findings: fsl-prelude-original.

Speed. The replica merges the regions with FSL’s arithmetic in FSL’s order, but keeps each region’s neighbours and the candidate merges ordered, instead of scanning every region for every merge: fMRIPrep’s call on ds005454-sub-16 (14,678 regions) takes 0.15 s against FSL’s 6.5 s, with the same bits. The clean room makes the same choices in the same order through an indexed heap of the candidate merges and a weighted union-find of the regions’ turns (each merge costs a logarithm of the candidates and the neighbours of the region that joins), and runs the linear parts (the mask, the regions, the ramps, reading and writing) on its threads: the same call takes 0.069 s on one thread (97 times FSL’s speed, 2.5 times the replica’s), 0.053 s on 12; ds002603’s 0.135 s against FSL’s 28.4 s; a 256 x 256 x 160 map of 153,000 regions 2.0 s (the replica 9.4 s), with the same bits at every thread count (benchmarks).

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

  • The replica is bit-exact: larmorx-nc fsl prelude, in the package larmorx-nc (crates-nc/), under the FSL Licence’s terms, run as a separate program.
  • The clean room is larmorx fsl prelude in the main package (crate larmorx-fsl, Apache-2.0, written from specs/prelude.md without FSL’s source: PROVENANCE), run in this process and built for speed.

implementation="auto" runs the replica when larmorx-nc is installed (pip install larmorx-nc), else the clean room; "replica" needs larmorx-nc (ReplicaNotFoundError without it); "clean-room" ("original", 0.1.0rc1’s spelling, still works) runs the clean room. The command line follows --implementation (before the family) or LARMORX_IMPLEMENTATION the same way (exit 127 when the replica’s program is asked for and not found).

Evidence

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

More in the repository

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