File: interface_tutorial.rst

package info (click to toggle)
nipype 0.5.3-2wheezy2
  • links: PTS, VCS
  • area: main
  • in suites: wheezy
  • size: 4,884 kB
  • sloc: python: 36,872; tcl: 597; makefile: 167
file content (211 lines) | stat: -rw-r--r-- 6,335 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
.. _interface_tutorial:

=======================
 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 :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:

.. testcode::
   
   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:

.. testcode::

   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:

.. testcode::

   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.

.. sourcecode:: ipython

    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)

.. sourcecode:: ipython

   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.

.. sourcecode:: ipython

    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)

.. sourcecode:: ipython

    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 :ref:`interface-index` documentation provides html versions of our
docstrings and includes links to the specific package
documentation. For instance, the :class:`nipype.interfaces.fsl.Bet`
docstring has a direct link to the online BET Documentation.


FSL interface example
---------------------

Using FSL_ to realign a time_series:

.. testcode::

   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:

.. testcode::
   
   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()

.. include:: ../links_names.txt