Programs · FSL
applytopup
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl applytopup- Python
lx.fsl.applytopup- 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-topup.md and the code
What it does
applytopup corrects images with topup’s result, by Jacobian modulation of each image or by the
least-squares restoration of pairs with opposite phase encodings.
Command line
larmorx fsl applytopup -in=topdn,botup --topup=mytu --inindex=1,2 --out=hifi
larmorx fsl applytopup -in=topdn --topup=mytu --inindex=1 --method=jac --interp=spline --out=hifiEverything after larmorx fsl applytopup is the original’s command line: the arguments of FSL 6.0.7.23’s applytopup, 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 applytopup ...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.
applytopup's usage text, as the clean room prints it
Part of FSL (ID: 2412.6-dirty)
applytopup (Version 1.0)
Copyright(c) 2009, University of Oxford (Jesper Andersson)
Usage:
applytopup -in=topdn,botup --topup=mytu --inindex=1,2 --out=hifi
applytopup -in=topdn --topup=mytu --inindex=1 --method=jac --interp=spline --out=hifi
Compulsory arguments (You MUST set one or more of):
-i,--imain comma separated list of names of input image (to be corrected)
-a,--datain name of text file with PE directions/times
-x,--inindex comma separated list of indicies into --datain of the input image (to be corrected)
-t,--topup name of field/movements (from topup)
-o,--out basename for output (warped) image
Optional arguments (You may optionally specify one or more of):
-m,--method Use jacobian modulation (jac) or least-squares resampling (lsr), default=lsr.
-n,--interp interpolation method {trilinear,spline}, default=spline
-d,--datatype Force output data type [preserve char short int float double].
-v,--verbose switch on diagnostic messages
-h,--help display this messagePython
lx.fsl.applytopup(
images: Any,
acquisition: Any,
indices: Sequence[int],
topup_result: Any,
*,
method: Literal["lsr", "jac", "vb2D", "vb3D", "vb4D"] = "lsr",
interp: Literal["spline", "trilinear"] = "spline",
datatype: Literal["preserve", "char", "short", "int", "float", "double"] | None = None,
verbose: bool = False,
n_threads: int = 1,
implementation: ImplementationName = "auto",
upstream_defects: UpstreamDefectsName = "fix",
) -> ApplytopupResultWhere ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room"); UpstreamDefectsName is one of "fix", "reproduce".
Correct images with topup’s field (FSL’s applytopup).
FSL’s settings are the call’s (CLAUDE.md rule 6): the outputs are NIfTI-1 read back, and no FSL variable of the process reaches the program.
Its result, ApplytopupResult, holds what applytopup wrote.
| Field | Type | What it holds |
|---|---|---|
corrected |
Image |
The corrected image (--out). |
stdout |
str |
applytopup’s standard output (the vb* methods print their iterations). |
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 applytopup accepts (crates/larmorx-fsl/src/cli/applytopup.rs) and the arguments of lx.fsl.applytopup (python/larmorx/fsl/topup.py), whose defaults and descriptions are taken from it. Under each option, in grey, FSL’s own help for it.
applytopup option |
Python | Default | Notes |
|---|---|---|---|
-i, --imain |
images |
one image or a list of them (3D or 4D, one grid)FSL: “comma separated list of names of input image (to be corrected)” | |
-a, --datain |
acquisition |
as topup’sFSL: “name of text file with PE directions/times” | |
-x, --inindex |
indices |
each image’s row of acquisition (1-based)FSL: “comma separated list of indicies into --datain of the input image (to be corrected)” |
|
-t, --topup |
topup_result |
a TopupResult, a field image in Hz, or the base name of topup’s files (without extension)FSL: “name of field/movements (from topup)” |
|
-o, --out |
the result | the corrected imageFSL: “basename for output (warped) image” | |
-m, --method |
method |
"lsr" |
"lsr" (least-squares restoration of opposite phase encodings), "jac" (Jacobian modulation), "vb2D", "vb3D", "vb4D" (undocumented variational-Bayes restorations)FSL: “Use jacobian modulation (jac) or least-squares resampling (lsr), default=lsr.” |
-n, --interp |
interp |
"spline" |
"spline" (default) or "trilinear"FSL: “interpolation method {trilinear,spline}, default=spline” |
-d, --datatype |
datatype |
None |
"preserve", "char", "short", "int", "float" (default), "double"FSL: “Force output data type [preserve char short int float double].” |
-v, --verbose |
verbose=True |
False |
(applytopup prints nothing more)FSL: “switch on diagnostic messages” |
-h, --help |
command line only | FSL: “display this message” | |
OMP_NUM_THREADS |
n_threads |
1 |
threads of the resampling; the results do not depend on it |
LARMORX_UPSTREAM_DEFECTS |
upstream_defects |
"fix" |
as topup’s |
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 applytopup ...) and are arguments of lx.fsl.applytopup. 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 results do 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 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-topup.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: b0.nii.gz (a synthetic series of 4 such heads), acqp.txt (the phase encodings of four volumes, two along +y and two along −y, read out in 0.05 s). The command lines run as python -m larmorx.
import larmorx as lx
r = lx.fsl.topup("b0.nii.gz", "acqp.txt", warpres=20, subsamp=2, miter=2, estmov=False)
# Each volume corrected by Jacobian modulation, with topup's result.
c = lx.fsl.applytopup("b0.nii.gz", "acqp.txt", [1], r, method="jac")
c.corrected.shape # -> (40, 48, 40, 4)larmorx fsl topup --imain=b0 --datain=acqp.txt --warpres=20 --subsamp=2 --miter=2 --estmov=0 --out=tu
larmorx fsl applytopup --imain=b0 --datain=acqp.txt --inindex=1 --topup=tu --method=jac --out=b0_correctedPorts
applytopup 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-topup-replica |
| clean room | larmorx |
Apache-2.0 | experimental | fsl-topup |
Both ports are complete (specs/topup.md §2 to §10): applytopup’s every method (lsr, jac,
vb2D, vb3D, vb4D; lines of 30, 32 and 96 voxels), data type and failure, each compared file
by file with FSL’s. The replica’s record holds 75 cases of applytopup: 48 identical to FSL, 25
where both refuse alike, 2 refused in both modes. The clean room’s holds 75: 44 within its
thresholds, 25 refused alike, 6 expected divergences (the records say why). The
clean room’s lsr on ds005040’s pair takes 0.13 s on one thread and 0.04 s on 14 (FSL 0.42 s, the
replica 3.47 s).
FSL is distributed under the FSL Licence (non-commercial use only), so each program has two ports, a replica and a clean room, in different packages (licensing):
- The replica is bit-exact:
larmorx-nc fsl topupandfsl applytopup, in the packagelarmorx-nc(crates-nc/larmorx-nc-topup), under the FSL Licence’s terms, translated from FSL’s source with the B-spline fields, sparse matrices, non-linear optimisers and warps of FSL’s libraries. - The clean room is in the main package (Apache-2.0, crate
larmorx-fsl, moduletopup), written fromspecs/topup.mdwithout FSL’s source.
implementation="auto" (the default) runs the replica when larmorx-nc is installed (pip install larmorx-nc) and the clean room otherwise; "replica" needs larmorx-nc (otherwise
ReplicaNotFoundError); "clean-room" ("original", 0.1.0rc1’s spelling, still works) always
runs the clean room. The command line chooses alike (--implementation before the family, or
LARMORX_IMPLEMENTATION).
Evidence
How each of applytopup’s ports was measured against FSL, case by case: its evidence.
More in the repository
The API page docs/api/fsl-topup.md holds what applytopup shares with the page’s other programs: