API

Pydra tasks for FSL.

FSL interfaces are available within the pydra.tasks.fsl package.

>>> from pydra.tasks import fsl

BET

Brain Extraction Tool (BET)

BET removes non-brain tissues from whole-head images. It can also estimate the inner and outer skull surfaces, and outer scalp surface, when provided with good quality T1 and T2 input images.

RobustFOV

Automatic FOV reduction to remove the neck and lower part of the head from structural brain images.

Examples

>>> task = RobustFOV(input_image="image.nii")
>>> task.cmdline  
'robustfov -i image.nii -r ...image_rfov.nii -b 170 -m ...image_rfov.mat'

Eddy

Eddy

Correct for artifacts induced by Eddy currents and subject motion.

Examples

>>> task = Eddy(
...     input_image="input.nii",
...     brain_mask="brain.nii",
...     encoding_file="params.txt",
...     index_file="index.txt",
...     bvec_file="input.bvec",
...     bval_file="input.bval",
...     fieldmap_image="fieldmap.nii",
... )
>>> task.cmdline    
'eddy --imain=input.nii --mask=brain.nii --acqp=params.txt --index=index.txt --bvecs=input.bvec --bvals=input.bval --field=fieldmap.nii --out=eddy ...'

Topup

Examples

Minimal call to topup:

>>> task = Topup(input_image="input.nii", encoding_file="encoding.txt")
>>> task.cmdline  
'topup --imain=input.nii --datain=encoding.txt --out=input_topup --fout=...input_fieldmap.nii --iout=...input_unwarped.nii ...'

Using a multiple resolution approach:

>>> task = Topup(
...     input_image="input.nii",
...     encoding_file="encoding.txt",
...     subsampling_per_level=(4, 2, 1),
...     smoothing_per_level=(8.0, 4.0, 0.0),
... )
>>> task.cmdline  
'topup --imain=input.nii --datain=encoding.txt ... --subsamp=4,2,1 --fwhm=8.0,4.0,0.0 ...'

ApplyTopup

Examples

>>> task = ApplyTopup(
...     input_image="blipup.nii",
...     encoding_file="parameters.txt",
...     input_index=1,
...     fieldmap_image="fieldmap.nii",
...     method="jac",
... )
>>> task.cmdline    
'applytopup --imain=blipup.nii --datain=parameters.txt --inindex=1 --topup=fieldmap --out=blipup_topup.nii --method=jac ...'

>>> task = ApplyTopup(
...     input_image=["blipup.nii", "blipdown.nii"],
...     encoding_file="parameters.txt",
...     input_index=[1, 2, 3],
...     field_coefficients_image="topup_fieldcoef.nii",
...     movement_parameters_file="topup_movpar.txt",
...     output_image="corrected.nii",
... )
>>> task.cmdline    
'applytopup --imain=blipup.nii,blipdown.nii --datain=parameters.txt --inindex=1,2,3 --topup=topup --out=corrected.nii ...'

FAST

Automatic segmentation of 3D images of the brain.

FLIRT

FLIRT

FLIRT (FMRIB’s Linear Image Registration Tool) is a robust and accurate tool for affine registration of intra- and inter-modal brain images.

Examples

Register two images together:

>>> task = FLIRT(
...     input_image="invol.nii",
...     reference_image="refvol.nii",
...     output_matrix="invol2refvol.mat",
...     cost_function="mutualinfo",
...     degrees_of_freedom=6,
... )
>>> task.cmdline  
'flirt -in invol.nii -ref refvol.nii -out ...invol_flirt.nii -omat invol2refvol.mat ... -cost mutualinfo ...'

Perform a single slice registration:

>>> task = FLIRT(
...     input_image="inslice.nii",
...     reference_image="refslice.nii",
...     output_image="outslice.nii",
...     output_matrix="i2r.mat",
...     interpolation="nearestneighbour",
...     use_2d_registration=True,
...     no_search=True,
... )
>>> task.cmdline
'flirt -in inslice.nii -ref refslice.nii -out outslice.nii -omat i2r.mat -2D -nosearch ... -interp nearestneighbour'

Apply a transformation:

>>> task = ApplyXFM(
...     input_image="invol.nii",
...     output_image="outvol.nii",
...     reference_image="refvol.nii",
...     initial_matrix="affine.mat",
... )
>>> task.cmdline  
'flirt -in invol.nii -ref refvol.nii -out outvol.nii -init affine.mat -applyxfm ...'

Apply a trasnformation and force isotropic resampling to 1 mm:

>>> task = ApplyXFM(
...     input_image="invol.nii",
...     output_image="outvol.nii",
...     reference_image="refvol.nii",
...     initial_matrix="affine.mat",
...     isotropic_resolution=1,
...     padding_size=5,
... )
>>> task.cmdline  
'flirt -in invol.nii -ref refvol.nii -out outvol.nii -init affine.mat -applyisoxfm 1 -paddingsize 5 ...'

ConvertXFM

Examples

Concatenate transformation matrix:

>>> task = ConcatXFM(input_matrix="AtoB.mat", concat_matrix="BtoC.mat", output_matrix="AtoC.mat")
>>> task.cmdline
'convert_xfm -omat AtoC.mat -concat BtoC.mat AtoB.mat'

Invert transformation matrix:

>>> task = InvertXFM(input_matrix="AtoB.mat", output_matrix="BtoA.mat")
>>> task.cmdline
'convert_xfm -omat BtoA.mat -inverse AtoB.mat'

Fix scaling and skewness with additional matrix:

>>> task = FixScaleSkew(input_matrix="A.mat", fixscaleskew_matrix="B.mat")
>>> task.cmdline
'convert_xfm -omat ...A_cxfm.mat -fixscaleskew B.mat A.mat'

Use ConvertXFM to combine multiple operations at once, such as concatenation and inversion:

>>> task = ConvertXFM(input_matrix="AtoB.mat", concat_matrix="BtoC.mat", inverse=True, output_matrix="CtoA.mat")
>>> task.cmdline
'convert_xfm -omat CtoA.mat -concat BtoC.mat -inverse AtoB.mat'

Img2ImgCoord

Examples

>>> task = Img2ImgCoord(
... input_coordinates="coordinates.txt",
... source_image="source.nii",
... destination_image="target.nii",
... affine_matrix="affine.mat",
... )
>>> task.cmdline  
'img2imgcoord -xfm affine.mat ... -src source.nii -dest target.nii coordinates.txt'

Img2StdCoord

Examples

>>> task = Img2StdCoord(
... input_coordinates="coordinates.txt",
... input_image="input.nii",
... standard_image="standard.nii",
... affine_matrix="affine.mat",
... )
>>> task.cmdline  
'img2stdcoord -xfm affine.mat ... -img input.nii -std standard.nii coordinates.txt'

Std2ImgCoord

Examples

>>> task = Std2ImgCoord(
... input_coordinates="coordinates.txt",
... input_image="input.nii",
... standard_image="standard.nii",
... affine_matrix="affine.mat",
... )
>>> task.cmdline  
'std2imgcoord -xfm affine.mat ... -std standard.nii -img input.nii coordinates.txt'

FNIRT

FNIRT

FNIRT (FSL Non-linear Image Registration Tool) performs non-linear registration of brain images.

Examples

>>> task = FNIRT(
...     reference_image="template.nii",
...     input_image="input.nii",
... )
>>> task.cmdline  
'fnirt --ref template.nii --in input.nii --cout ...input_warpcoef.nii --iout ...input_warped.nii --fout ...input_warpfield.nii --jout ...input_jac.nii ...'

>>> task = FNIRT(
...     reference_image="template.nii",
...     input_image="input.nii",
...     subsampling=[4, 2, 1],
...     warp_resolution=[8, 8, 8],
...     input_fwhm=[8, 4, 2],
... )
>>> task.cmdline  
'fnirt --ref template.nii --in input.nii ... --subsamp 4,2,1 --warpres 8,8,8 ... --infwhm 8,4,2 ...'

FNIRTFileUtils

Examples

>>> task = FNIRTFileUtils(
...     input_image="input.nii",
...     reference_image="reference.nii",
... )
>>> task.cmdline  
'fnirtfileutils --in input.nii --ref reference.nii --out ...input_field.nii --outformat field ...'

>>> task = FNIRTFileUtils(
...     input_image="input.nii",
...     reference_image="reference.nii",
...     output_jacobian_image="jacobian.nii",
...     with_affine_transform=True,
... )
>>> task.cmdline  
'fnirtfileutils --in input.nii --ref reference.nii ... --jac jacobian.nii ... --withaff'

ApplyWarp

Examples

>>> task = ApplyWarp(
...     input_image="invol.nii",
...     reference_image="refvol.nii",
...     input_warpfield="warpvol.nii",
...     warpfield_as="abs",
... )
>>> task.cmdline  
'applywarp --in invol.nii --ref refvol.nii --out ...invol_warped.nii --warp warpvol.nii --abs ...'

>>> task = ApplyWarp(
...     input_image="invol.nii",
...     reference_image="refvol.nii",
...     output_image="outvol.nii",
...     use_sqform=True,
... )
>>> task.cmdline  
'applywarp --in invol.nii --ref refvol.nii --out outvol.nii ... --usesqform'

ConvertWarp

Examples

>>> task = ConvertWarp(
...     reference_image="refvol.nii",
...     pre_affine_matrix="affine.mat",
... )
>>> task.cmdline  
'convertwarp --ref refvol.nii --out ...refvol_warp.nii --premat affine.mat --jacobian ...refvol_jac.nii'

>>> task = ConvertWarp(
...     reference_image="refvol.nii",
...     output_warpfield="outwarp.nii",
...     pre_affine_matrix="pre.mat",
...     pre_warpfield="warp1.nii",
...     post_warpfield="warp2.nii",
...     post_affine_matrix="post.mat",
... )
>>> task.cmdline  
'convertwarp --ref refvol.nii --out outwarp.nii --premat pre.mat --warp1 warp1.nii --warp2 warp2.nii --postmat post.mat --jacobian ...refvol_jac.nii'

>>> task = ConvertWarp(
...     reference_image="refvol.nii",
...     input_shiftmap="shiftmap.nii",
...     shift_direction="y-",
... )
>>> task.cmdline  
'convertwarp --ref refvol.nii --out .../refvol_warp.nii --shiftmap shiftmap.nii --shiftdir y- --jacobian .../refvol_jac.nii'

InvWarp

Examples

>>> task = InvWarp(
...     input_warpfield="warpvol.nii",
...     reference_image= "refvol.nii",
... )
>>> task.cmdline  
'invwarp --warp warpvol.nii --ref refvol.nii --out ...warpvol_invwarp.nii'

>>> task = InvWarp(
...     input_warpfield="warpvol.nii",
...     reference_image= "refvol.nii",
...     output_warpfield="invwarpvol.nii",
...     no_jacobian_constraints=True,
... )
>>> task.cmdline
'invwarp --warp warpvol.nii --ref refvol.nii --out invwarpvol.nii --noconstraint'

fslmaths

Mathematical manipulation of images.

Examples

Convert input image to float:

>>> task = Maths(input_image="input.nii")
>>> task.cmdline    
'fslmaths input.nii .../input_fslmaths.nii'

Multiply input image with a binary mask:

>>> task = Mul(input_image="input.nii", other_image="mask.nii", output_image="output.nii")
>>> task.cmdline
'fslmaths input.nii -mul mask.nii output.nii'

>>> task = Threshold(input_image="input.nii", threshold=0.3, output_image="output.nii")
>>> task.cmdline
'fslmaths input.nii -thr 0.3 output.nii'

FUGUE

FUGUE

>>> task = FUGUE(
...     input_image="epi.nii",
...     input_phasemap="phasemap.nii",
...     dwell_to_asym_time_ratio=0.3,
...     output_inverse_warpfield="unwarped.nii",
... )
>>> task.cmdline
'fugue --in epi.nii --unwarp unwarped.nii --phasemap phasemap.nii --dwelltoasym 0.3'

>>> task = FUGUE(
...     input_image="unwarped.nii",
...     input_phasemap="phasemap.nii",
...     dwell_to_asym_time_ratio=0.3,
...     output_warpfield="warped.nii",
... )
>>> task.cmdline
'fugue --in unwarped.nii --warp warped.nii --phasemap phasemap.nii --dwelltoasym 0.3'

>>> task = FUGUE(
...     input_phasemap="phasemap.nii",
...     output_shiftmap="shiftmap.nii",
... )
>>> task.cmdline
'fugue --phasemap phasemap.nii --saveshift shiftmap.nii'

PrepareFieldmap

EPI fieldmap preprocessing.

Examples

>>> task = PrepareFieldmap(phase_image="gre_phase.nii", magnitude_image="gre_mag.nii", output_image="fmap.nii")
>>> task.cmdline
'fsl_prepare_fieldmap SIEMENS gre_phase.nii gre_mag.nii fmap.nii 2.46'

Prelude

Phase Region Expanding Labeller for Unwrapping Discrete Estimates.

Examples

>>> task = Prelude(complex_image="complex.nii")
>>> task.cmdline  
'prelude --complex complex.nii --out complex_unwrapped_phase.nii --rawphase complex_raw_phase.nii --labels complex_labels.nii --savemask complex_mask.nii ...'

>>> task = Prelude(
...     phase_image="phase.nii",
...     magnitude_image="magnitude.nii",
...     output_unwrapped_phase_image="unwrapped.nii",
... )
>>> task.cmdline  
'prelude --abs magnitude.nii --phase phase.nii --out unwrapped.nii ...'

SigLoss

Estimate signal loss from a B0 map.

Examples

>>> task = SigLoss(input_image="b0map.nii", input_mask="mask.nii", output_image="sigloss.nii")
>>> task.cmdline  
'sigloss ... --in b0map.nii --mask mask.nii --sigloss sigloss.nii'

SUSAN

Structure-preserving noise reduction.

Examples

>>> task = SUSAN(input_image="input.nii")
>>> task.cmdline  
'susan input.nii 3.0 3 1 0 .../input_susan.nii'

>>> task = SUSAN(
...     input_image="input.nii",
...     output_image="output.nii",
...     use_median=False,
...     usans=[("usan1.nii", 1.0), ("usan2.nii", -1.0)],
... )
>>> task.cmdline
'susan input.nii 3.0 3 0 2 usan1.nii 1.0 usan2.nii -1.0 output.nii'

Utils

ChFileType

Convert image to a different NIfTI file format.

Examples

>>> task = ChFileType(filetype="NIFTI2_GZ", input_image="input.nii", output_basename="output")
>>> task.cmdline
'fslchfiletype NIFTI2_GZ input.nii output'

FFT (Fast Fourier Transform)

Compute the forward or inverse Fast Fourier Transform of a NIfTI image.

Examples

Compute the forward FFT:

>>> task = FFT(input_image="input.nii")
>>> task.cmdline    
'fslfft input.nii .../input_fft.nii'

Compute the inverse FFT:

>>> task = FFT(input_image="input.nii", output_image="output.nii", inverse=True)
>>> task.cmdline
'fslfft input.nii output.nii -inv'

Info

Read essential metadata from the header of a NIfTI image.

Interleave

Examples

Interleave images:

>>> task = Interleave(input_image="in1.nii", other_image="in2.nii")
>>> task.cmdline  
'fslinterleave in1.nii in2.nii .../in1_interleave.nii'

Interleave in reverse order:

>>> task = Interleave(
...     input_image="in1.nii",
...     other_image="in2.nii",
...     output_image="out.nii",
...     reverse=True,
... )
>>> task.cmdline
'fslinterleave in1.nii in2.nii out.nii -i'

Merge

Examples

>>> task = Merge(dimension="t", input_images=["vol1.nii", "vol2.nii"])
>>> task.cmdline  
'fslmerge -t ...merged vol1.nii vol2.nii'

Orient

Change the orientation of an image.

Examples

>>> import tempfile
>>> input_file = tempfile.NamedTemporaryFile(suffix="input.nii")

Change orientation to radiological:

>>> task = Orient(input_image=input_file.name, force_radiological=True)
>>> task.cmdline  
'fslorient -forceradiological ...input.nii'

Change orientation to neurological:

>>> task = Orient(input_image=input_file.name, force_neurological=True)
>>> task.cmdline  
'fslorient -forceneurological ...input.nii'

Swap between radiological and neurological:

>>> task = Orient(input_image=input_file.name, swap_orientation=True)
>>> task.cmdline  
'fslorient -swaporient ...input.nii'

Delete orientation:

>>> task = Orient(input_image=input_file.name, delete_orientation=True)
>>> task.cmdline  
'fslorient -deleteorient ...input.nii'

Reorient2Std

Change orientation of the image to match the one used for standard template images (MNI152).

Examples

>>> task = Reorient2Std(input_image="image.nii")
>>> task.cmdline  
'fslreorient2std -m ...image_r2std.mat image.nii ...image_r2std.nii'

ROI (Region-Of-Interest)

Manual cropping to a region-of-interest for structural brain images.

Examples

Extract a 16-voxel cube starting at position (10, 20, 30):

>>> task = ROI(
...     input_image="image.nii",
...     x_min=10,
...     x_size=16,
...     y_min=20,
...     y_size=16,
...     z_min=30,
...     z_size=16,
... )
>>> task.cmdline    
'fslroi image.nii ...image_roi.nii 10 16 20 16 30 16 ...'

Extract a temporal window starting at 5 onwards:

>>> task = ROI(input_image="input.nii", output_image="output.nii", t_min=5)
>>> task.cmdline
'fslroi input.nii output.nii 5 -1'

SelectVols

Examples

Select volumes from a list and concatenate them:

>>> task = SelectVols(input_image="input.nii", volumes=[0, 1, 6, 7])
>>> task.cmdline
'fslselectvols --in input.nii --out .../input_selectvols.nii --vols 0,1,6,7'

Select volumes from a file and calculate their mean:

>>> task = SelectVols(
...     input_image="input.nii",
...     output_image="mean.nii",
...     volumes="volumes.txt",
...     calculate_mean=True,
... )
>>> task.cmdline
'fslselectvols --in input.nii --out mean.nii --vols volumes.txt -m'

Select volumes from a file and calculate their variance:

>>> task = SelectVols(
...     input_image="input.nii",
...     output_image="variance.nii",
...     volumes="volumes.txt",
...     calculate_variance=True,
... )
>>> task.cmdline
'fslselectvols --in input.nii --out variance.nii --vols volumes.txt -v'

SmoothFill

Examples

>>> task = SmoothFill(input_image="input.nii", output_image="smoothed.nii", input_mask="mask.nii")
>>> task.cmdline
'fslsmoothfill --in input.nii --out smoothed.nii --mask mask.nii'

Split

Examples

>>> task = Split(input_image="input.nii.gz")
>>> task.cmdline
'fslsplit input.nii.gz input -t'

>>> task = Slice(input_image="volume.nii", output_basename="slice")
>>> task.cmdline
'fslsplit volume.nii slice -z'

SwapDim

Examples

>>> task = SwapDim(
...     input_image="input.nii",
...     new_x="y",
...     new_y="x",
...     new_z="-z",
... )
>>> task.cmdline  
'fslswapdim input.nii y x -z ...input_swapdim.nii'

>>> task = SwapDim(
...     input_image="input.nii",
...     output_image="output.nii",
...     new_x="RL",
...     new_y="PA",
...     new_z="IS",
... )
>>> task.cmdline
'fslswapdim input.nii RL PA IS output.nii'