Home · Quickstart · Documentation · Citation · NiPy

# Tutorial : Interfaces

## Specifying options

The nipype interface modules provide a Python interface to external packages like FSL and SPM. Within the module are a series of Python classes which wrap specific package functionality. For example, in the fsl module, the class `nipype.interfaces.fsl.Bet` wraps the `bet` command-line tool. Using the command-line tool, one would specify options using flags like `-o`, `-m`, `-f <f>`, etc... However, in nipype, options are assigned to Python attributes and can be specified in the following ways:

Options can be assigned when you first create an interface object:

    import nipype.interfaces.fsl as fsl
    mybet = fsl.BET(in_file='foo.nii', out_file='bar.nii')
    result = mybet.run()

Options can be assigned through the `inputs` attribute:

    import nipype.interfaces.fsl as fsl
    mybet = fsl.BET()
    mybet.inputs.in_file = 'foo.nii'
    mybet.inputs.out_file = 'bar.nii'
    result = mybet.run()

Options can be assigned when calling the `run` method:

    import nipype.interfaces.fsl as fsl
    mybet = fsl.BET()
    result = mybet.run(in_file='foo.nii', out_file='bar.nii', frac=0.5)

## Getting Help

In IPython you can view the docstrings which provide some basic documentation and examples.

    In [2]: fsl.FAST?
    Type:               type
    Base Class: <type 'type'>
    String Form:        <class 'nipype.interfaces.fsl.preprocess.FAST'>
    Namespace:  Interactive
    File:               /Users/satra/sp/nipype/interfaces/fsl/preprocess.py
    Docstring:
        Use FSL FAST for segmenting and bias correction.

        For complete details, see the `FAST Documentation.
        <http://www.fmrib.ox.ac.uk/fsl/fast4/index.html>`_

        Examples
        --------
        >>> from nipype.interfaces import fsl
        >>> from nipype.testing import anatfile

        Assign options through the ``inputs`` attribute:

        >>> fastr = fsl.FAST()
        >>> fastr.inputs.in_files = anatfile
        >>> out = fastr.run() #doctest: +SKIP

    Constructor information:
    Definition: fsl.FAST(self, **inputs)

    In [5]: spm.Realign?
    Type:                type
    Base Class:  <type 'type'>
    String Form: <class 'nipype.interfaces.spm.preprocess.Realign'>
    Namespace:   Interactive
    File:                /Users/satra/sp/nipype/interfaces/spm/preprocess.py
    Docstring:
        Use spm_realign for estimating within modality rigid body alignment

        http://www.fil.ion.ucl.ac.uk/spm/doc/manual.pdf#page=25

        Examples
        --------

        >>> import nipype.interfaces.spm as spm
        >>> realign = spm.Realign()
        >>> realign.inputs.in_files = 'functional.nii'
        >>> realign.inputs.register_to_mean = True
        >>> realign.run() # doctest: +SKIP

    Constructor information:
    Definition:  spm.Realign(self, **inputs)

All of the nipype.interfaces classes have an `help` method which provides information on each of the options one can assign.

    In [6]: fsl.BET.help()
    Inputs
    ------

    Mandatory:
     in_file: input file to skull strip

    Optional:
     args: Additional parameters to the command
     center: center of gravity in voxels
     environ: Environment variables (default={})
     frac: fractional intensity threshold
     functional: apply to 4D fMRI data
      mutually exclusive: functional, reduce_bias
     mask: create binary mask image
     mesh: generate a vtk mesh brain surface
     no_output: Don't generate segmented output
     out_file: name of output skull stripped image
     outline: create surface outline image
     output_type: FSL output type
     radius: head radius
     reduce_bias: bias field and neck cleanup
      mutually exclusive: functional, reduce_bias
     skull: create skull image
     threshold: apply thresholding to segmented brain image and mask
     vertical_gradient: vertical gradient in fractional intensity threshold (-1, 1)

    Outputs
    -------
    mask_file: path/name of binary brain mask (if generated)
    meshfile: path/name of vtk mesh file (if generated)
    out_file: path/name of skullstripped file
    outline_file: path/name of outline file (if generated)

    In [7]: spm.Realign.help()
    Inputs
    ------

    Mandatory:
     in_files: list of filenames to realign

    Optional:
     fwhm: gaussian smoothing kernel width
     interp: degree of b-spline used for interpolation
     jobtype: one of: estimate, write, estwrite (default=estwrite)
     matlab_cmd: None
     mfile: Run m-code using m-file (default=True)
     paths: Paths to add to matlabpath
     quality: 0.1 = fast, 1.0 = precise
     register_to_mean: Indicate whether realignment is done to the mean image
     separation: sampling separation in mm
     weight_img: filename of weighting image
     wrap: Check if interpolation should wrap in [x,y,z]
     write_interp: degree of b-spline used for interpolation
     write_mask: True/False mask output image
     write_which: determines which images to reslice
     write_wrap: Check if interpolation should wrap in [x,y,z]

    Outputs
    -------
    mean_image: Mean image file from the realignment
    realigned_files: Realigned files
    realignment_parameters: Estimated translation and rotation parameters

Our Interfaces and Algorithms documentation provides html versions of our docstrings and includes links to the specific package documentation. For instance, the `nipype.interfaces.fsl.Bet` docstring has a direct link to the online BET Documentation.

## FSL interface example

Using FSL to realign a time_series:

    import nipype.interfaces.fsl as fsl
    realigner = fsl.McFlirt()
    realigner.inputs.in_file='timeseries4D.nii'
    result = realigner.run()

## SPM interface example

Using SPM to realign a time-series:

    import nipype.interfaces.spm as spm
    from glob import glob
    allepi = glob('epi*.nii') # this will return an unsorted list
    allepi.sort()
    realigner = spm.Realign()
    realigner.inputs.in_files = allepi
    result = realigner.run()