Programs · FSL
pairreg
pairreg is a script that registers one brain to another and refines the result with the two heads’ skulls.
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl pairreg- Python
lx.fsl.pairreg- 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-flirt.md and the code
What it does
It runs FLIRT three times, with FSL’s schedules pairreg1.sch to pairreg3.sch:
the brains first, then the skulls, then the brains again; brain1 and skull1 are the references.
Command line
larmorx fsl pairreg brain1 brain2 skull1 skull2 outputmatrix [extra flirt args]Everything after larmorx fsl pairreg is the original’s command line: the arguments of FSL 6.0.7.23’s pairreg, 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 pairreg ...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.
pairreg's usage text, as the clean room prints it
Usage: pairreg brain1 brain2 skull1 skull2 outputmatrix [extra flirt args]
NB: brain1 and skull1 are used as -ref arguments internallyPython
lx.fsl.pairreg(
brain1: str | os.PathLike,
brain2: str | os.PathLike,
skull1: str | os.PathLike,
skull2: str | os.PathLike,
*,
flirt_args: list[str] | None = None,
n_threads: int = 1,
implementation: ImplementationName = "auto",
upstream_defects: UpstreamDefectsName = "fix",
) -> np.ndarrayWhere 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 pairreg: the matrix from brain2 to brain1 (brain1 and skull1 the references), found with the brains, refined with the skulls and finished with the brains (three FLIRT runs with FSL’s pairreg1.sch to pairreg3.sch schedules, which the clean room carries: no $FSLDIR needed); flirt_args are passed to every FLIRT run.
The images are paths; flirt_args is a list of FLIRT’s options. The result is the 4 × 4 matrix
from brain2 to brain1.
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 pairreg accepts (crates/larmorx-fsl/src/cli/pairreg.rs) and the arguments of lx.fsl.pairreg (python/larmorx/fsl/flirt_more.py), whose defaults and descriptions are taken from it. Under each option, in grey, FSL’s own help for it.
pairreg arguments |
Python | Default | Notes |
|---|---|---|---|
brain1 brain2 skull1 skull2 |
brain1, brain2, skull1, skull2 |
brain1 and skull1 the references |
|
outputmatrix |
the result | ||
[extra flirt args] |
flirt_args |
None |
passed to every FLIRT run |
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 pairreg ...) and are arguments of lx.fsl.pairreg. 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), given to the program as OMP_NUM_THREADS; 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 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-flirt.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: b1_brain.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), b2_brain.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), b1.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), b2.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
pair = lx.fsl.pairreg("b1_brain.nii.gz", "b2_brain.nii.gz", "b1.nii.gz", "b2.nii.gz")
pair.shape # -> (4, 4)larmorx fsl pairreg b1_brain.nii.gz b2_brain.nii.gz b1.nii.gz b2.nii.gz b2_to_b1.matPorts
pairreg 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-flirt-replica |
| clean room | larmorx |
Apache-2.0 | experimental | fsl-flirt |
Both ports are complete (specs/flirt.md §15.8). The clean room runs its own flirt three times and one convert_xfm -fixscaleskew, in
this process, and carries FSL’s three schedules itself: it needs no $FSLDIR. -v echoes FSL’s
lines, and a step that aborts is followed by the shell’s Aborted line. Arguments that the
script’s shell would split or expand are refused.
The replica’s record holds 3 cases of pairreg: 2 identical to FSL, 1 where both refuse alike.
The clean room’s holds 5: 4 within its thresholds, 1 refused alike.
FSL’s licence allows non-commercial use only, so each of FLIRT’s programs has two ports, a replica and a clean room, in different packages (licensing says what each package holds):
- The replica is translated from FSL’s source. The package
larmorx-ncholds it (crates-nc/), under the FSL Licence’s terms, andlarmorxruns it as a separate program,larmorx-nc fsl <program>, whenlarmorx-ncis installed (pip install larmorx-nc). - The clean room is written from
specs/flirt.mdby an implementer who never read FSL’s source or the replica. It is part oflarmorx, under Apache-2.0 (crates/larmorx-fsl, with its PROVENANCE, section “FLIRT”), and runs on LARMORX’s clean-room registration engine, the head-motion correction’s (lx.mri.hmc).
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); "clean-room" runs the clean room in this process. 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 pairreg’s ports was measured against FSL, case by case: its evidence.
More in the repository
The API page docs/api/fsl-flirt.md holds what pairreg shares with the page’s other programs: