Programs · FSL

standard_space_roi

standard_space_roi is a script that masks an image or cuts it down with a region of a standard space.

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

It registers the input to a standard-space reference with FLIRT (MNI152_T1_2mm unless -ssref gives another), takes the reference’s field of view (less its outer voxel) or a standard-space mask back into the input’s space with the inverse matrix, and masks the input with it and/or cuts the input down to its bounding box. bet -S and bet -B run it (-b -d, -maskFOV -roiNONE -d).

Command line

text
larmorx fsl standard_space_roi <input> <output> [options] [flirt options]

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

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.

standard_space_roi's usage text, as the clean room prints it
text
Usage: standard_space_roi <input> <output> [options] [flirt options]

This masks the input and/or reduces its FOV, on the basis of a
standard space image or mask, that is transformed into the space
of the input image.

Masking options (applied before FOV-reduction):
  -maskFOV           : mask output using transformed standard space FOV (default)
  -maskMASK <mask>   : mask output using transformed standard space mask
  -maskNONE          : do not mask output

FOV-reduction options:
  -roiFOV            : cut down input FOV using bounding box of the transformed standard space FOV (default)
  -roiMASK <mask>    : cut down input FOV using nonbackground bounding box of the transformed standard space mask
  -roiNONE           : do not cut down input FOV

With either MASK option, <mask> must be in the same space as the standard space reference image.

Other options:
  -ssref <ref_image> : standard space reference image to use (default ${FSLDIR}/data/standard/MNI152_T1)
  -altinput <image>  : alternative input image to apply the ROI to (instead of the one used to register to the reference)
  -d                 : debug (don't delete intermediate files)
  -b                 : betpremask, equivalent to: -maskMASK ${FSLDIR}/data/standard/MNI152_T1_2mm_brain_mask_dil -roiNONE

All above options must come before any flirt options.

Python

python
lx.fsl.standard_space_roi(
    image: Any,
    *,
    mask: Literal["fov", "none"] | Any = None,
    roi: Literal["fov", "none"] | Any = None,
    reference: Any = None,
    alt_input: Any = None,
    betpremask: bool = False,
    flirt_args: list[str] | None = None,
    fsl_data: str | os.PathLike | None = None,
    n_threads: int = 1,
    implementation: ImplementationName = "auto",
    upstream_defects: UpstreamDefectsName = "fix",
) -> StandardSpaceRoiResult

Where ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room"); UpstreamDefectsName is one of "fix", "reproduce".

FLIRT’s standard_space_roi: image registered to the standard-space reference (FSL’s MNI152_T1_2mm when not given), then masked (mask: "fov" the reference’s field of view less its outer voxel, a standard-space mask image, or "none") and cut down (roi: the bounding box of "fov", of a standard-space mask, or "none"), both taken into the image’s space; None is the script’s default ("fov", or betpremask’s). alt_input is masked and cut instead of image; betpremask is -b (the dilated MNI152 brain mask, thresholded at 0.5, and no cut), given before mask and roi; flirt_args go to the first FLIRT run; fsl_data is the directory of FSL’s standard images (docs/api/fsl-roi.md, “FSL’s standard images”).

The images are paths or lx.Image objects.

Its result, StandardSpaceRoiResult, holds standard_space_roi’s output image, and FLIRT’s matrices between the input and the standard space (to_standard: input to reference, FSL’s <out>_tmp_to_std.mat; from_standard its inverse).

Field Type What it holds
image Image
to_standard np.ndarray
from_standard np.ndarray

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

standard_space_roi option Python Default Notes
<input> <output> image, the result
-maskFOV, -maskMASK <mask>, -maskNONE mask="fov", mask=<image>, mask="none" mask=None, mask=None, mask=None None: the script’s defaultFSL: “mask output using transformed standard space FOV (default)”FSL: “mask output using transformed standard space mask”FSL: “do not mask output”
-roiFOV, -roiMASK <mask>, -roiNONE roi="fov", roi=<image>, roi="none" roi=None, roi=None, roi=None FSL: “cut down input FOV using bounding box of the transformed standard space FOV (default)”FSL: “cut down input FOV using nonbackground bounding box of the transformed standard space mask”FSL: “do not cut down input FOV”
-ssref <ref> reference None FSL: “standard space reference image to use (default ${FSLDIR}/data/standard/MNI152_T1)”
-altinput <image> alt_input None FSL: “alternative input image to apply the ROI to (instead of the one used to register to the reference)”
-b betpremask=True False given before mask and roiFSL: “betpremask, equivalent to: -maskMASK ${FSLDIR}/data/standard/MNI152_T1_2mm_brain_mask_dil -roiNONE”
-d always the matrices are returned: to_standard, from_standardFSL: “debug (don’t delete intermediate files)”
FLIRT’s options after the script’s flirt_args=[...] None
LARMORX_FSL_DATA fsl_data None where FSL’s standard images are

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 standard_space_roi ...) and are arguments of lx.fsl.standard_space_roi. 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: T1w.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), std.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm). The command lines run as python -m larmorx.

python
import larmorx as lx

r = lx.fsl.standard_space_roi("T1w.nii.gz", reference="std.nii.gz")
r.to_standard.shape  # -> (4, 4)
bash
larmorx fsl standard_space_roi T1w.nii.gz T1w_roi -ssref std.nii.gz

Ports

standard_space_roi 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: FSL-11, and FSL-211 to FSL-214 (the script’s names, cleanup, maskthr and failures). The clean room converts an input of another file type than FSLOUTPUTTYPE as fslpy’s imcp does with nibabel (the same header and data in the output’s file layout and compression: a .nii.gz input becomes FSL’s .nii byte for byte, the record’s ssroi/phantom-none-convert); the replica refuses that case clearly (exit 1) in both modes. The clean room is built for speed: the registration to the reference is almost all of standard_space_roi’s time; besides it, without -d the temporary images are written uncompressed (they are removed at the end), and when the field of view is both the mask and the region it is resampled into the input’s space once.

Both records are BET’s, as these programs came with BET’s options. The replica’s holds 25 cases of standard_space_roi: 16 identical to FSL, 8 where both refuse alike, and the conversion the replica refuses. The clean room’s holds 25: 17 within its thresholds, 8 refused alike. Its standard_space_roi is FSL’s bit for bit where its FLIRT gives FSL’s matrix (an adult’s T1w, a Philips T1w and a T2w with the defaults); elsewhere its matrices are within FLIRT’s 12-dof threshold and, given FSL’s matrix, every file is FSL’s (findings, “standard_space_roi and fslroi”).

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 standard_space_roi’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 standard_space_roi shares with the page’s other programs: