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-ncFSL Licence: non-commercial use only validated - clean room
larmorxApache-2.0 experimental
- replica
- 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
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):
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
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
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",
) -> ImageWhere 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 Nn_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-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-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.
import larmorx as lx
first = lx.fsl.fslroi("bold.nii.gz", t=(0, 2))
first.shape # -> (40, 48, 40, 2)larmorx fsl fslroi bold.nii.gz bold_first2 0 2Ports
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::fslroiand::ssroi, Apache-2.0) is written fromspecs/standard_space_roi.md, FSL’s documentation and black-box runs of FSL 6.0.7.23 (PROVENANCE), and runs in this process. Itsstandard_space_roiruns the clean room’s own FLIRT,convert_xfm,fslmaths,fslstatsandfslroi, and fslpy’simcp, in the same process: no FSL installation is needed. - The replica is bit-exact:
larmorx-nc fsl fslroiandlarmorx-nc fsl standard_space_roi, in the packagelarmorx-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: