mrsiprep.interfaces.fsl

FSL FLIRT/FNIRT registration interface.

Functions

apply_transforms(fixed, moving, transforms, ...)

Apply an FSL FLIRT affine, or a FNIRT warp, to moving.

default_fnirt_warpres(mrsi_voxel_mm[, floor_mm])

FNIRT --warpres (B-spline control-point grid spacing, mm), auto-scaled to the MRSI acquisition's own native voxel size rather than a fixed constant.

register_flirt(fixed, moving, out_prefix, *)

Register moving to fixed with FLIRT (affine only; see register_fnirt for the deformable FSL backend).

register_fnirt(fixed, moving, out_prefix, *, ...)

Register moving to fixed with FLIRT (seeded, corrected defaults -- see register_flirt) followed by FNIRT, mrsiprep's deformable fsl registration stage, mimicking the deformable (SyN) component of ANTs' default sr preset.

require_cli(command)

run_cli(cmd[, verbose])

run_fast(t1_path, out_prefix[, verbose])

Exceptions

FSLError

Raised when FSL cannot complete a requested operation.
exception mrsiprep.interfaces.fsl.FSLError[source]

Bases: RuntimeError

Raised when FSL cannot complete a requested operation.

mrsiprep.interfaces.fsl.apply_transforms(fixed, moving, transforms, out_path, interpolation='linear', verbose=False)[source]

Apply an FSL FLIRT affine, or a FNIRT warp, to moving.

A FNIRT warp (.fnirt_warp.nii.gz) takes priority over any affine also present in transforms: when fnirt is run with --aff (as register_fnirt always does), its --fout warp field already encodes the full affine+nonlinear composition end to end, so the warp is applied alone via applywarp with no --premat. Passing the affine as well (--premat) would double-apply it -- this was hit and confirmed empirically: with --premat, the resampled map's correlation against the ANTs SyN reference collapsed from r=0.71 to r=-0.24 and lost roughly a third of its in-brain voxel coverage.

Parameters:

  • transforms (list[str | Path])

  • out_path (str | Path)

  • interpolation (str)

  • verbose (bool)

Return type:

Path

mrsiprep.interfaces.fsl.default_fnirt_warpres(mrsi_voxel_mm, floor_mm=6)[source]

FNIRT --warpres (B-spline control-point grid spacing, mm), auto-scaled to the MRSI acquisition's own native voxel size rather than a fixed constant.

--warpres sets the spacing of FNIRT's deformation-field control-point grid in the fixed (T1w) image's space -- but the real constraint here is how much local deformation detail the moving (MRSI) image's resolution can actually justify without the warp just fitting noise. A higher-resolution MRSI acquisition (e.g. ~3.2mm at 7T) carries more spatial degrees of freedom than a coarser one (e.g. ~5mm at 3T), so it can support a finer control-point grid.

Rule of thumb, validated against a real 3T subject (5.0mm MRSI, where warpres=10mm -- i.e. ~2x voxel size -- scored best against the ANTs SyN reference, see experiments/fnirt_vs_syn_comparison.py): warpres ~= 2 x native MRSI voxel size, floored at floor_mm (default 6mm -- FNIRT's practical lower bound before the control-point grid outnumbers the spatial information the MRSI data can actually support).

Parameters:

  • mrsi_voxel_mm (tuple[float, float, float])

  • floor_mm (int)

Return type:

tuple[int, int, int]

mrsiprep.interfaces.fsl.register_flirt(fixed, moving, out_prefix, *, fixed_mask=None, flirt_dof=12, flirt_cost='corratio', flirt_init='flirt', flirt_nosearch=True, verbose=False)[source]

Register moving to fixed with FLIRT (affine only; see register_fnirt for the deformable FSL backend).

Defaults (flirt_cost="corratio", seeded from -usesqform with -nosearch) replace FLIRT's own out-of-the-box defaults (mutualinfo cost, unrestricted global rotation/translation search), which were found to actively diverge on a real MRSI-reference-vs-T1w registration: a naive qform/sform-only alignment with zero optimization already scored r=0.63 (Pearson correlation, in-brain-mask voxels) against the equivalent ANTs SyN registration, while FLIRT's own search stage -- with either cost function -- walked away to a worse, sometimes strongly anti-correlated (r=-0.09 to -0.29), local optimum. This is because the moving image here (a small, low-contrast MRSI reference map, e.g. 44x44x25) gives FLIRT's coarse-resolution cost evaluation too little information to reliably find the right optimum during a blind search. Seeding from the physically-meaningful qform/sform frame and skipping the search (-nosearch, only local gradient-descent refinement from that seed) recovers and improves on the qform-only baseline (r=0.65). See experiments/fnirt_vs_syn_comparison.py and its metrics.tsv output for the full before/after comparison this was validated against.

Parameters:

  • out_prefix (str | Path)

  • flirt_dof (int)

  • flirt_cost (str)

  • flirt_init (str)

  • flirt_nosearch (bool)

  • verbose (bool)

Return type:

dict[str, list[Path]]

mrsiprep.interfaces.fsl.register_fnirt(fixed, moving, out_prefix, *, fixed_mask, moving_mask, flirt_dof=12, flirt_cost='corratio', warpres=None, lambda_weight='300,200,150,150', regmod='bending_energy', verbose=False)[source]

Register moving to fixed with FLIRT (seeded, corrected defaults -- see register_flirt) followed by FNIRT, mrsiprep's deformable fsl registration stage, mimicking the deformable (SyN) component of ANTs' default sr preset.

fixed_mask/moving_mask are required (not optional): FNIRT, unlike FLIRT's own -refweight masking, needs explicit masking on both sides (--refmask/--inmask) to avoid trying to deform regions with no MRSI signal to match background noise.

warpres should ordinarily come from default_fnirt_warpres(), called with the MRSI reference image's own native voxel size, rather than a fixed value -- see that function's docstring for why.

Parameters:

  • out_prefix (str | Path)

  • flirt_dof (int)

  • flirt_cost (str)

  • warpres (tuple[int, int, int] | None)

  • lambda_weight (str)

  • regmod (str)

  • verbose (bool)

Return type:

dict[str, list[Path]]

mrsiprep.interfaces.fsl.require_cli(command)[source]
Parameters:

command (str)

Return type:

str

mrsiprep.interfaces.fsl.run_cli(cmd, verbose=False)[source]
Parameters:

  • cmd (list[str])

  • verbose (bool)

Return type:

None

mrsiprep.interfaces.fsl.run_fast(t1_path, out_prefix, verbose=False)[source]
Parameters:

  • t1_path (str | Path)

  • out_prefix (str | Path)

  • verbose (bool)

Return type:

dict[str, Path]