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-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-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
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):
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
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 messagePython
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,
) -> PreludeResultWhere 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.
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.labelsIts 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 Nn_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-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-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.
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)larmorx fsl prelude -p phasediff.nii.gz -a magnitude.nii.gz -o unwrappedPorts
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
reproducebit-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.reproduceandpy.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 packagelarmorx-nc(crates-nc/), under the FSL Licence’s terms, run as a separate program. - The clean room is
larmorx fsl preludein the main package (cratelarmorx-fsl, Apache-2.0, written fromspecs/prelude.mdwithout 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: