interfaces.fsl.epi¶
ApplyTOPUP¶
Wraps command applytopup
Interface for FSL topup, a tool for estimating and correcting susceptibility induced distortions. General reference and use example.
Examples¶
>>> from nipype.interfaces.fsl import ApplyTOPUP
>>> applytopup = ApplyTOPUP()
>>> applytopup.inputs.in_files = ["epi.nii", "epi_rev.nii"]
>>> applytopup.inputs.encoding_file = "topup_encoding.txt"
>>> applytopup.inputs.in_topup_fieldcoef = "topup_fieldcoef.nii.gz"
>>> applytopup.inputs.in_topup_movpar = "topup_movpar.txt"
>>> applytopup.inputs.output_type = "NIFTI_GZ"
>>> applytopup.cmdline
'applytopup --datain=topup_encoding.txt --imain=epi.nii,epi_rev.nii --inindex=1,2 --topup=topup --out=epi_corrected.nii.gz'
>>> res = applytopup.run()
Inputs:
[Mandatory]
encoding_file: (an existing file name)
name of text file with PE directions/times
flag: --datain=%s
in_files: (a list of items which are an existing file name)
name of file with images
flag: --imain=%s
[Optional]
args: (a unicode string)
Additional parameters to the command
flag: %s
datatype: ('char' or 'short' or 'int' or 'float' or 'double')
force output data type
flag: -d=%s
environ: (a dictionary with keys which are a bytes or None or a value
of class 'str' and with values which are a bytes or None or a value
of class 'str', nipype default value: {})
Environment variables
in_index: (a list of items which are an integer (int or long))
comma separated list of indices corresponding to --datain
flag: --inindex=%s
in_topup_fieldcoef: (an existing file name)
topup file containing the field coefficients
flag: --topup=%s
requires: in_topup_movpar
in_topup_movpar: (an existing file name)
topup movpar.txt file
requires: in_topup_fieldcoef
interp: ('trilinear' or 'spline')
interpolation method
flag: --interp=%s
method: ('jac' or 'lsr')
use jacobian modulation (jac) or least-squares resampling (lsr)
flag: --method=%s
out_corrected: (a file name)
output (warped) image
flag: --out=%s
output_type: ('NIFTI_PAIR' or 'NIFTI_GZ' or 'NIFTI' or
'NIFTI_PAIR_GZ')
FSL output type
Outputs:
out_corrected: (an existing file name)
name of 4D image file with unwarped images
References:: None
EPIDeWarp¶
Wraps command epidewarp.fsl
Wraps the unwarping script epidewarp.fsl.
Warning
deprecated in FSL, please use
nipype.workflows.dmri.preprocess.epi.sdc_fmb() instead.
Examples¶
>>> from nipype.interfaces.fsl import EPIDeWarp
>>> dewarp = EPIDeWarp()
>>> dewarp.inputs.epi_file = "functional.nii"
>>> dewarp.inputs.mag_file = "magnitude.nii"
>>> dewarp.inputs.dph_file = "phase.nii"
>>> dewarp.inputs.output_type = "NIFTI_GZ"
>>> dewarp.cmdline
'epidewarp.fsl --mag magnitude.nii --dph phase.nii --epi functional.nii --esp 0.58 --exfdw .../exfdw.nii.gz --nocleanup --sigma 2 --tediff 2.46 --tmpdir .../temp --vsm .../vsm.nii.gz'
>>> res = dewarp.run()
Inputs:
[Mandatory]
dph_file: (an existing file name)
Phase file assumed to be scaled from 0 to 4095
flag: --dph %s
mag_file: (an existing file name)
Magnitude file
flag: --mag %s, position: 0
[Optional]
args: (a unicode string)
Additional parameters to the command
flag: %s
cleanup: (a boolean)
cleanup
flag: --cleanup
environ: (a dictionary with keys which are a bytes or None or a value
of class 'str' and with values which are a bytes or None or a value
of class 'str', nipype default value: {})
Environment variables
epi_file: (an existing file name)
EPI volume to unwarp
flag: --epi %s
epidw: (a string)
dewarped epi volume
flag: --epidw %s
esp: (a float, nipype default value: 0.58)
EPI echo spacing
flag: --esp %s
exf_file: (an existing file name)
example func volume (or use epi)
flag: --exf %s
exfdw: (a string)
dewarped example func volume
flag: --exfdw %s
nocleanup: (a boolean, nipype default value: True)
no cleanup
flag: --nocleanup
output_type: ('NIFTI_PAIR' or 'NIFTI_GZ' or 'NIFTI' or
'NIFTI_PAIR_GZ')
FSL output type
sigma: (an integer (int or long), nipype default value: 2)
2D spatial gaussing smoothing stdev (default = 2mm)
flag: --sigma %s
tediff: (a float, nipype default value: 2.46)
difference in B0 field map TEs
flag: --tediff %s
tmpdir: (a string)
tmpdir
flag: --tmpdir %s
vsm: (a string)
voxel shift map
flag: --vsm %s
Outputs:
exf_mask: (a file name)
Mask from example functional volume
exfdw: (a file name)
dewarped functional volume example
unwarped_file: (a file name)
unwarped epi file
vsm_file: (a file name)
voxel shift map
References:: None
Eddy¶
Wraps command eddy_openmp
Interface for FSL eddy, a tool for estimating and correcting eddy currents induced distortions. User guide and more info regarding acqp file.
Examples¶
>>> from nipype.interfaces.fsl import Eddy
>>> eddy = Eddy()
>>> eddy.inputs.in_file = 'epi.nii'
>>> eddy.inputs.in_mask = 'epi_mask.nii'
>>> eddy.inputs.in_index = 'epi_index.txt'
>>> eddy.inputs.in_acqp = 'epi_acqp.txt'
>>> eddy.inputs.in_bvec = 'bvecs.scheme'
>>> eddy.inputs.in_bval = 'bvals.scheme'
>>> eddy.inputs.use_cuda = True
>>> eddy.cmdline
'eddy_cuda --ff=10.0 --acqp=epi_acqp.txt --bvals=bvals.scheme --bvecs=bvecs.scheme --imain=epi.nii --index=epi_index.txt --mask=epi_mask.nii --niter=5 --nvoxhp=1000 --out=.../eddy_corrected'
>>> eddy.inputs.use_cuda = False
>>> eddy.cmdline
'eddy_openmp --ff=10.0 --acqp=epi_acqp.txt --bvals=bvals.scheme --bvecs=bvecs.scheme --imain=epi.nii --index=epi_index.txt --mask=epi_mask.nii --niter=5 --nvoxhp=1000 --out=.../eddy_corrected'
>>> res = eddy.run()
Inputs:
[Mandatory]
in_acqp: (an existing file name)
File containing acquisition parameters
flag: --acqp=%s
in_bval: (an existing file name)
File containing the b-values for all volumes in --imain
flag: --bvals=%s
in_bvec: (an existing file name)
File containing the b-vectors for all volumes in --imain
flag: --bvecs=%s
in_file: (an existing file name)
File containing all the images to estimate distortions for
flag: --imain=%s
in_index: (an existing file name)
File containing indices for all volumes in --imain into --acqp and
--topup
flag: --index=%s
in_mask: (an existing file name)
Mask to indicate brain
flag: --mask=%s
[Optional]
args: (a unicode string)
Additional parameters to the command
flag: %s
dont_peas: (a boolean)
Do NOT perform a post-eddy alignment of shells
flag: --dont_peas
dont_sep_offs_move: (a boolean)
Do NOT attempt to separate field offset from subject movement
flag: --dont_sep_offs_move
environ: (a dictionary with keys which are a bytes or None or a value
of class 'str' and with values which are a bytes or None or a value
of class 'str', nipype default value: {})
Environment variables
fep: (a boolean)
Fill empty planes in x- or y-directions
flag: --fep
field: (a unicode string)
NonTOPUP fieldmap scaled in Hz - filename has to be provided without
an extension. TOPUP is strongly recommended
flag: --field=%s
field_mat: (an existing file name)
Matrix that specifies the relative locations of the field specified
by --field and first volume in file --imain
flag: --field_mat=%s
flm: ('linear' or 'quadratic' or 'cubic')
First level EC model
flag: --flm=%s
fudge_factor: (a float, nipype default value: 10.0)
Fudge factor for hyperparameter error variance
flag: --ff=%s
fwhm: (a float)
FWHM for conditioning filter when estimating the parameters
flag: --fwhm=%s
in_topup_fieldcoef: (an existing file name)
topup file containing the field coefficients
flag: --topup=%s
requires: in_topup_movpar
in_topup_movpar: (an existing file name)
topup movpar.txt file
requires: in_topup_fieldcoef
interp: ('spline' or 'trilinear')
Interpolation model for estimation step
flag: --interp=%s
is_shelled: (a boolean)
Override internal check to ensure that date are acquired on a set of
b-value shells
flag: --data_is_shelled
method: ('jac' or 'lsr')
Final resampling method (jacobian/least squares)
flag: --resamp=%s
niter: (an integer (int or long), nipype default value: 5)
Number of iterations
flag: --niter=%s
num_threads: (an integer (int or long), nipype default value: 1)
Number of openmp threads to use
nvoxhp: (an integer (int or long), nipype default value: 1000)
# of voxels used to estimate the hyperparameters
flag: --nvoxhp=%s
out_base: (a unicode string, nipype default value: eddy_corrected)
basename for output (warped) image
flag: --out=%s
output_type: ('NIFTI_PAIR' or 'NIFTI_GZ' or 'NIFTI' or
'NIFTI_PAIR_GZ')
FSL output type
repol: (a boolean)
Detect and replace outlier slices
flag: --repol
session: (an existing file name)
File containing session indices for all volumes in --imain
flag: --session=%s
slm: ('none' or 'linear' or 'quadratic')
Second level EC model
flag: --slm=%s
use_cuda: (a boolean)
Run eddy using cuda gpu
Outputs:
out_corrected: (an existing file name)
4D image file containing all the corrected volumes
out_movement_rms: (an existing file name)
Summary of the "total movement" in each volume
out_outlier_report: (an existing file name)
Text-file with a plain language report on what outlier slices eddy
has found
out_parameter: (an existing file name)
text file with parameters definining the field andmovement for each
scan
out_restricted_movement_rms: (an existing file name)
Summary of the "total movement" in each volume disregarding
translation in the PE direction
out_rotated_bvecs: (an existing file name)
File containing rotated b-values for all volumes
out_shell_alignment_parameters: (an existing file name)
File containing rigid body movement parameters between the different
shells as estimated by a post-hoc mutual information based
registration
References:: None
EddyCorrect¶
Wraps command eddy_correct
Warning
Deprecated in FSL. Please use
nipype.interfaces.fsl.epi.Eddy instead
Example¶
>>> from nipype.interfaces.fsl import EddyCorrect
>>> eddyc = EddyCorrect(in_file='diffusion.nii',
... out_file="diffusion_edc.nii", ref_num=0)
>>> eddyc.cmdline
'eddy_correct diffusion.nii diffusion_edc.nii 0'
Inputs:
[Mandatory]
in_file: (an existing file name)
4D input file
flag: %s, position: 0
ref_num: (an integer (int or long), nipype default value: 0)
reference number
flag: %d, position: 2
[Optional]
args: (a unicode string)
Additional parameters to the command
flag: %s
environ: (a dictionary with keys which are a bytes or None or a value
of class 'str' and with values which are a bytes or None or a value
of class 'str', nipype default value: {})
Environment variables
out_file: (a file name)
4D output file
flag: %s, position: 1
output_type: ('NIFTI_PAIR' or 'NIFTI_GZ' or 'NIFTI' or
'NIFTI_PAIR_GZ')
FSL output type
Outputs:
eddy_corrected: (an existing file name)
path/name of 4D eddy corrected output file
References:: None
EpiReg¶
Wraps command epi_reg
Runs FSL epi_reg script for simultaneous coregistration and fieldmap unwarping.
Examples¶
>>> from nipype.interfaces.fsl import EpiReg
>>> epireg = EpiReg()
>>> epireg.inputs.epi='epi.nii'
>>> epireg.inputs.t1_head='T1.nii'
>>> epireg.inputs.t1_brain='T1_brain.nii'
>>> epireg.inputs.out_base='epi2struct'
>>> epireg.inputs.fmap='fieldmap_phase_fslprepared.nii'
>>> epireg.inputs.fmapmag='fieldmap_mag.nii'
>>> epireg.inputs.fmapmagbrain='fieldmap_mag_brain.nii'
>>> epireg.inputs.echospacing=0.00067
>>> epireg.inputs.pedir='y'
>>> epireg.cmdline
'epi_reg --echospacing=0.000670 --fmap=fieldmap_phase_fslprepared.nii --fmapmag=fieldmap_mag.nii --fmapmagbrain=fieldmap_mag_brain.nii --noclean --pedir=y --epi=epi.nii --t1=T1.nii --t1brain=T1_brain.nii --out=epi2struct'
>>> epireg.run()
Inputs:
[Mandatory]
epi: (an existing file name)
EPI image
flag: --epi=%s, position: -4
t1_brain: (an existing file name)
brain extracted T1 image
flag: --t1brain=%s, position: -2
t1_head: (an existing file name)
wholehead T1 image
flag: --t1=%s, position: -3
[Optional]
args: (a unicode string)
Additional parameters to the command
flag: %s
echospacing: (a float)
Effective EPI echo spacing (sometimes called dwell time) - in
seconds
flag: --echospacing=%f
environ: (a dictionary with keys which are a bytes or None or a value
of class 'str' and with values which are a bytes or None or a value
of class 'str', nipype default value: {})
Environment variables
fmap: (an existing file name)
fieldmap image (in rad/s)
flag: --fmap=%s
fmapmag: (an existing file name)
fieldmap magnitude image - wholehead
flag: --fmapmag=%s
fmapmagbrain: (an existing file name)
fieldmap magnitude image - brain extracted
flag: --fmapmagbrain=%s
no_clean: (a boolean, nipype default value: True)
do not clean up intermediate files
flag: --noclean
no_fmapreg: (a boolean)
do not perform registration of fmap to T1 (use if fmap already
registered)
flag: --nofmapreg
out_base: (a string, nipype default value: epi2struct)
output base name
flag: --out=%s, position: -1
output_type: ('NIFTI_PAIR' or 'NIFTI_GZ' or 'NIFTI' or
'NIFTI_PAIR_GZ')
FSL output type
pedir: ('x' or 'y' or 'z' or '-x' or '-y' or '-z')
phase encoding direction, dir = x/y/z/-x/-y/-z
flag: --pedir=%s
weight_image: (an existing file name)
weighting image (in T1 space)
flag: --weight=%s
wmseg: (an existing file name)
white matter segmentation of T1 image, has to be named like the
t1brain and end on _wmseg
flag: --wmseg=%s
Outputs:
epi2str_inv: (an existing file name)
rigid structural-to-epi transform
epi2str_mat: (an existing file name)
rigid epi-to-structural transform
fmap2epi_mat: (an existing file name)
rigid fieldmap-to-epi transform
fmap2str_mat: (an existing file name)
rigid fieldmap-to-structural transform
fmap_epi: (an existing file name)
fieldmap in epi space
fmap_str: (an existing file name)
fieldmap in structural space
fmapmag_str: (an existing file name)
fieldmap magnitude image in structural space
fullwarp: (an existing file name)
warpfield to unwarp epi and transform into structural space
out_1vol: (an existing file name)
unwarped and coregistered single volume
out_file: (an existing file name)
unwarped and coregistered epi input
seg: (an existing file name)
white matter, gray matter, csf segmentation
shiftmap: (an existing file name)
shiftmap in epi space
wmedge: (an existing file name)
white matter edges for visualization
wmseg: (an existing file name)
white matter segmentation used in flirt bbr
References:: None
PrepareFieldmap¶
Wraps command fsl_prepare_fieldmap
Interface for the fsl_prepare_fieldmap script (FSL 5.0)
Prepares a fieldmap suitable for FEAT from SIEMENS data - saves output in
rad/s format (e.g. `fsl_prepare_fieldmap SIEMENS
images_3_gre_field_mapping images_4_gre_field_mapping fmap_rads 2.65`).
Examples¶
>>> from nipype.interfaces.fsl import PrepareFieldmap
>>> prepare = PrepareFieldmap()
>>> prepare.inputs.in_phase = "phase.nii"
>>> prepare.inputs.in_magnitude = "magnitude.nii"
>>> prepare.inputs.output_type = "NIFTI_GZ"
>>> prepare.cmdline
'fsl_prepare_fieldmap SIEMENS phase.nii magnitude.nii .../phase_fslprepared.nii.gz 2.460000'
>>> res = prepare.run()
Inputs:
[Mandatory]
delta_TE: (a float, nipype default value: 2.46)
echo time difference of the fieldmap sequence in ms. (usually 2.46ms
in Siemens)
flag: %f, position: -2
in_magnitude: (an existing file name)
Magnitude difference map, brain extracted
flag: %s, position: 3
in_phase: (an existing file name)
Phase difference map, in SIEMENS format range from 0-4096 or 0-8192)
flag: %s, position: 2
[Optional]
args: (a unicode string)
Additional parameters to the command
flag: %s
environ: (a dictionary with keys which are a bytes or None or a value
of class 'str' and with values which are a bytes or None or a value
of class 'str', nipype default value: {})
Environment variables
nocheck: (a boolean, nipype default value: False)
do not perform sanity checks for image size/range/dimensions
flag: --nocheck, position: -1
out_fieldmap: (a file name)
output name for prepared fieldmap
flag: %s, position: 4
output_type: ('NIFTI_PAIR' or 'NIFTI_GZ' or 'NIFTI' or
'NIFTI_PAIR_GZ')
FSL output type
scanner: (a string, nipype default value: SIEMENS)
must be SIEMENS
flag: %s, position: 1
Outputs:
out_fieldmap: (an existing file name)
output name for prepared fieldmap
References:: None
SigLoss¶
Wraps command sigloss
Estimates signal loss from a field map (in rad/s)
Examples¶
>>> from nipype.interfaces.fsl import SigLoss
>>> sigloss = SigLoss()
>>> sigloss.inputs.in_file = "phase.nii"
>>> sigloss.inputs.echo_time = 0.03
>>> sigloss.inputs.output_type = "NIFTI_GZ"
>>> sigloss.cmdline
'sigloss --te=0.030000 -i phase.nii -s .../phase_sigloss.nii.gz'
>>> res = sigloss.run()
Inputs:
[Mandatory]
in_file: (an existing file name)
b0 fieldmap file
flag: -i %s
[Optional]
args: (a unicode string)
Additional parameters to the command
flag: %s
echo_time: (a float)
echo time in seconds
flag: --te=%f
environ: (a dictionary with keys which are a bytes or None or a value
of class 'str' and with values which are a bytes or None or a value
of class 'str', nipype default value: {})
Environment variables
mask_file: (an existing file name)
brain mask file
flag: -m %s
out_file: (a file name)
output signal loss estimate file
flag: -s %s
output_type: ('NIFTI_PAIR' or 'NIFTI_GZ' or 'NIFTI' or
'NIFTI_PAIR_GZ')
FSL output type
slice_direction: ('x' or 'y' or 'z')
slicing direction
flag: -d %s
Outputs:
out_file: (an existing file name)
signal loss estimate file
References:: None
TOPUP¶
Wraps command topup
Interface for FSL topup, a tool for estimating and correcting susceptibility induced distortions. See FSL documentation for reference, usage examples, and exemplary config files.
Examples¶
>>> from nipype.interfaces.fsl import TOPUP
>>> topup = TOPUP()
>>> topup.inputs.in_file = "b0_b0rev.nii"
>>> topup.inputs.encoding_file = "topup_encoding.txt"
>>> topup.inputs.output_type = "NIFTI_GZ"
>>> topup.cmdline
'topup --config=b02b0.cnf --datain=topup_encoding.txt --imain=b0_b0rev.nii --out=b0_b0rev_base --iout=b0_b0rev_corrected.nii.gz --fout=b0_b0rev_field.nii.gz --jacout=jac --logout=b0_b0rev_topup.log --rbmout=xfm --dfout=warpfield'
>>> res = topup.run()
Inputs:
[Mandatory]
encoding_direction: (a list of items which are 'y' or 'x' or 'z' or
'x-' or 'y-' or 'z-')
encoding direction for automatic generation of encoding_file
flag: --datain=%s
mutually_exclusive: encoding_file
requires: readout_times
encoding_file: (an existing file name)
name of text file with PE directions/times
flag: --datain=%s
mutually_exclusive: encoding_direction
in_file: (an existing file name)
name of 4D file with images
flag: --imain=%s
readout_times: (a list of items which are a float)
readout times (dwell times by # phase-encode steps minus 1)
mutually_exclusive: encoding_file
requires: encoding_direction
[Optional]
args: (a unicode string)
Additional parameters to the command
flag: %s
config: (a string, nipype default value: b02b0.cnf)
Name of config file specifying command line arguments
flag: --config=%s
environ: (a dictionary with keys which are a bytes or None or a value
of class 'str' and with values which are a bytes or None or a value
of class 'str', nipype default value: {})
Environment variables
estmov: (1 or 0)
estimate movements if set
flag: --estmov=%d
fwhm: (a float)
FWHM (in mm) of gaussian smoothing kernel
flag: --fwhm=%f
interp: ('spline' or 'linear')
Image interpolation model, linear or spline.
flag: --interp=%s
max_iter: (an integer (int or long))
max # of non-linear iterations
flag: --miter=%d
minmet: (0 or 1)
Minimisation method 0=Levenberg-Marquardt, 1=Scaled Conjugate
Gradient
flag: --minmet=%d
numprec: ('double' or 'float')
Precision for representing Hessian, double or float.
flag: --numprec=%s
out_base: (a file name)
base-name of output files (spline coefficients (Hz) and movement
parameters)
flag: --out=%s
out_corrected: (a file name)
name of 4D image file with unwarped images
flag: --iout=%s
out_field: (a file name)
name of image file with field (Hz)
flag: --fout=%s
out_jac_prefix: (a unicode string, nipype default value: jac)
prefix for the warpfield images
flag: --jacout=%s
out_logfile: (a file name)
name of log-file
flag: --logout=%s
out_mat_prefix: (a unicode string, nipype default value: xfm)
prefix for the realignment matrices
flag: --rbmout=%s
out_warp_prefix: (a unicode string, nipype default value: warpfield)
prefix for the warpfield images (in mm)
flag: --dfout=%s
output_type: ('NIFTI_PAIR' or 'NIFTI_GZ' or 'NIFTI' or
'NIFTI_PAIR_GZ')
FSL output type
reg_lambda: (a float)
Weight of regularisation, default depending on --ssqlambda and
--regmod switches.
flag: --lambda=%0.f
regmod: ('bending_energy' or 'membrane_energy')
Regularisation term implementation. Defaults to bending_energy. Note
that the two functions have vastly different scales. The membrane
energy is based on the first derivatives and the bending energy on
the second derivatives. The second derivatives will typically be
much smaller than the first derivatives, so input lambda will have
to be larger for bending_energy to yield approximately the same
level of regularisation.
flag: --regmod=%s
regrid: (1 or 0)
If set (=1), the calculations are done in a different grid
flag: --regrid=%d
scale: (0 or 1)
If set (=1), the images are individually scaled to a common mean
flag: --scale=%d
splineorder: (an integer (int or long))
order of spline, 2->Qadratic spline, 3->Cubic spline
flag: --splineorder=%d
ssqlambda: (1 or 0)
Weight lambda by the current value of the ssd. If used (=1), the
effective weight of regularisation term becomes higher for the
initial iterations, therefore initial steps are a little smoother
than they would without weighting. This reduces the risk of finding
a local minimum.
flag: --ssqlambda=%d
subsamp: (an integer (int or long))
sub-sampling scheme
flag: --subsamp=%d
warp_res: (a float)
(approximate) resolution (in mm) of warp basis for the different
sub-sampling levels
flag: --warpres=%f
Outputs:
out_corrected: (a file name)
name of 4D image file with unwarped images
out_enc_file: (a file name)
encoding directions file output for applytopup
out_field: (a file name)
name of image file with field (Hz)
out_fieldcoef: (an existing file name)
file containing the field coefficients
out_jacs: (a list of items which are an existing file name)
Jacobian images
out_logfile: (a file name)
name of log-file
out_mats: (a list of items which are an existing file name)
realignment matrices
out_movpar: (an existing file name)
movpar.txt output file
out_warps: (a list of items which are an existing file name)
warpfield images
References:: None