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-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
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
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):
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
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
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",
) -> StandardSpaceRoiResultWhere 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 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: 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.
import larmorx as lx
r = lx.fsl.standard_space_roi("T1w.nii.gz", reference="std.nii.gz")
r.to_standard.shape # -> (4, 4)larmorx fsl standard_space_roi T1w.nii.gz T1w_roi -ssref std.nii.gzPorts
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::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 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: