Programs · FSL

fslroi

fslroi takes a box of an image (xmin xsize ymin ysize zmin zsize), a range of its volumes (tmin tsize) or both.

Original
FSL 6.0.7.23
Command line
larmorx fsl fslroi
Python
lx.fsl.fslroi
Ports
  • replica larmorx-nc FSL Licence: non-commercial use only validated
  • clean room larmorx Apache-2.0 experimental
Evidence
every comparison with FSL
Source
made from docs/api/fsl-roi.md and the code

What it does

The result keeps the image’s own data type, and its header’s transforms move to the box’s corner. A size of -1 is the rest of the axis, and the box may reach outside the image (zeros there). The indices are NIfTI voxel indices, from 0.

Command line

text
larmorx fsl fslroi <input> <output> <xmin> <xsize> <ymin> <ysize> <zmin> <zsize>
larmorx fsl fslroi <input> <output> <tmin> <tsize>

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

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.

fslroi's usage text, as the clean room prints it
text
Usage: fslroi <input> <output> <xmin> <xsize> <ymin> <ysize> <zmin> <zsize>
       fslroi <input> <output> <tmin> <tsize>

       fslroi <input> <output> <xmin> <xsize> <ymin> <ysize> <zmin> <zsize> <tmin> <tsize>
Note: indexing (in both time and space) starts with 0 not 1! Inputting -1 for a size will set it to the full image extent for that dimension.

Python

python
lx.fsl.fslroi(
    image: Any,
    *,
    x: Region = None,
    y: Region = None,
    z: Region = None,
    t: Region = None,
    n_threads: int = 1,
    implementation: ImplementationName = "auto",
    upstream_defects: UpstreamDefectsName = "fix",
) -> Image

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 fslroi: the region of image given as (min, size) per axis (indices from 0, a size of -1 the rest of the axis; an axis not given whole), in the image’s own type. Only t (fslroi <in> <out> <tmin> <tsize>), only space (x, y, z) or all four; the spatial indices are NIfTI voxel indices.

image is a path or an lx.Image; x, y, z and t are (min, size) pairs. Only t, only space (x, y, z) or all four; an axis of space not given is whole, (0, -1). The result is an lx.Image.

Its result, Image, holds a voxel array placed in world space by an affine.

Field Type What it holds
data np.ndarray
affine np.ndarray
header NiftiHeader | None
implementation Implementation | None

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 fslroi accepts (crates/larmorx-fsl/src/cli/fslroi.rs) and the arguments of lx.fsl.fslroi (python/larmorx/fsl/regions.py), whose defaults and descriptions are taken from it. Under each option, in grey, FSL’s own help for it.

fslroi arguments Python Default Notes
<input> image
<output> the result
<tmin> <tsize> t=(tmin, tsize) None a range of volumes
<xmin> <xsize> <ymin> <ysize> <zmin> <zsize> x, y, z x=None, y=None, z=None a box; an axis not given in Python: (0, -1)
all ten numbers x, y, z, t x=None, y=None, z=None, t=None both

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 fslroi ...) and are arguments of lx.fsl.fslroi. 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), given to the program as OMP_NUM_THREADS and to the reading and writing of images; 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-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-roi.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: bold.nii.gz (a synthetic series of 4 such heads). The command lines run as python -m larmorx.

python
import larmorx as lx

first = lx.fsl.fslroi("bold.nii.gz", t=(0, 2))
first.shape  # -> (40, 48, 40, 2)
bash
larmorx fsl fslroi bold.nii.gz bold_first2 0 2

Ports

fslroi has two ports: a replica and a clean room.

Port Package Licence Status Records
replica larmorx-nc FSL Licence: non-commercial use only validated fsl-bet-replica
clean room larmorx Apache-2.0 experimental fsl-bet

Both ports are complete. FSL’s defects are corrected by default, and reproduce gives FSL’s behaviour: fslroi exits with status 1 after the errors it reports (FSL-215), an int8 input is written as int8 (FSL-217), and with FSLOUTPUTTYPE unset the image is written as .nii.gz (FSL-11). The clean room is built for speed: it converts the stored values once (or moves them, where the type is kept) and copies the box row by row in parallel.

Both records are BET’s, as these programs came with BET’s options. The replica’s holds 26 cases of fslroi: 24 identical to FSL, 2 where both refuse alike. The clean room’s holds 26: 24 within its thresholds, 2 refused alike.

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 clean room (crates/larmorx-fsl, larmorx_fsl::cli::fslroi and ::ssroi, Apache-2.0) is written from specs/standard_space_roi.md, FSL’s documentation and black-box runs of FSL 6.0.7.23 (PROVENANCE), and runs in this process. Its standard_space_roi runs the clean room’s own FLIRT, convert_xfm, fslmaths, fslstats and fslroi, and fslpy’s imcp, in the same process: no FSL installation is needed.
  • The replica is bit-exact: larmorx-nc fsl fslroi and larmorx-nc fsl standard_space_roi, in the package larmorx-nc (crates-nc/), under the FSL Licence’s terms. It runs every program in the replica’s own process.

implementation="auto" runs the replica when its program is found, else the clean room; "clean-room" ("original", 0.1.0rc1’s spelling, still works) and "replica" choose. The command line follows --implementation (before the family) or LARMORX_IMPLEMENTATION the same way.

Evidence

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

More in the repository

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