Programs · FSL

applytopup

Original
FSL 6.0.7.23
Command line
larmorx fsl applytopup
Python
lx.fsl.applytopup
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-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

text
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=hifi

Everything 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):

text
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
text
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 message

Python

python
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",
) -> ApplytopupResult

Where 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 N
n_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-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-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.

python
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)
bash
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_corrected

Ports

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 topup and fsl applytopup, in the package larmorx-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, module topup), written from specs/topup.md without 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: