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
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
|
"""
================================
Workshop: Dartmouth College 2010
================================
First lets go to the directory with the data we'll be working on and start the interactive python interpreter
(with some nipype specific configuration). Note that nipype does not need to be run through ipython - it is
just much nicer to do interactive work in it.
.. sourcecode:: bash
cd $TDPATH
ipython -p nipype
For every neuroimaging procedure supported by nipype there exists a wrapper - a small piece of code managing
the underlying software (FSL, SPM, AFNI etc.). We call those interfaces. They are standarised so we can hook them up
together. Lets have a look at some of them.
.. sourcecode:: ipython
In [1]: import nipype.interfaces.fsl as fsl
In [2]: 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 [3]: import nipype.interfaces.freesurfer as fs
In [4]: fs.Smooth.help()
Inputs
------
Mandatory:
in_file: source volume
num_iters: number of iterations instead of fwhm
mutually exclusive: surface_fwhm
reg_file: registers volume to surface anatomical
surface_fwhm: surface FWHM in mm
mutually exclusive: num_iters
requires: reg_file
Optional:
args: Additional parameters to the command
environ: Environment variables (default={})
proj_frac: project frac of thickness a long surface normal
mutually exclusive: proj_frac_avg
proj_frac_avg: average a long normal min max delta
mutually exclusive: proj_frac
smoothed_file: output volume
subjects_dir: subjects directory
vol_fwhm: volumesmoothing outside of surface
Outputs
-------
args: Additional parameters to the command
environ: Environment variables
smoothed_file: smoothed input volume
subjects_dir: subjects directory
You can read about all of the interfaces implemented in nipype at our online documentation at http://nipy.sourceforge.net/nipype/documentation.html#documentation .
Check it out now.
Using interfaces
----------------
Having interfaces allows us to use third party software (like FSL BET) as function. Look how simple it is.
"""
import nipype.interfaces.fsl as fsl
result = fsl.BET(in_file='data/s1/struct.nii').run()
print result
"""
Running a single program is not much of a breakthrough. Lets run motion correction followed by smoothing
(isotropic - in other words not using SUSAN). Notice that in the first line we are setting the output data type
for all FSL interfaces.
"""
fsl.FSLCommand.set_default_output_type('NIFTI_GZ')
result1 = fsl.MCFLIRT(in_file='data/s1/f3.nii').run()
result2 = fsl.Smooth(in_file='f3_mcf.nii.gz', fwhm=6).run()
"""
Simple workflow
---------------
In the previous example we knew that fsl.MCFLIRT will produce a file called f3_mcf.nii.gz and we have hard coded
this as an input to fsl.Smooth. This is quite limited, but luckily nipype supports joining interfaces in pipelines.
This way output of one interface will be used as an input of another without having to hard code anything. Before
connecting Interfaces we need to put them into (separate) Nodes and give them unique names. This way every interface will
process data in a separate folder.
"""
import nipype.pipeline.engine as pe
import os
motion_correct = pe.Node(interface=fsl.MCFLIRT(in_file=os.path.abspath('data/s1/f3.nii')),
name="motion_correct")
smooth = pe.Node(interface=fsl.Smooth(fwhm=6), name="smooth")
motion_correct_and_smooth = pe.Workflow(name="motion_correct_and_smooth")
motion_correct_and_smooth.base_dir = os.path.abspath('.') # define where will be the root folder for the workflow
motion_correct_and_smooth.connect([
(motion_correct, smooth, [('out_file', 'in_file')])
])
# we are connecting 'out_file' output of motion_correct to 'in_file' input of smooth
motion_correct_and_smooth.run()
"""
Another workflow
----------------
Another example of a simple workflow (calculate the mean of fMRI signal and subtract it).
This time we'll be assigning inputs after defining the workflow.
"""
calc_mean = pe.Node(interface=fsl.ImageMaths(), name="calc_mean")
calc_mean.inputs.op_string = "-Tmean"
subtract = pe.Node(interface=fsl.ImageMaths(), name="subtract")
subtract.inputs.op_string = "-sub"
demean = pe.Workflow(name="demean")
demean.base_dir = os.path.abspath('.')
demean.connect([
(calc_mean, subtract, [('out_file', 'in_file2')])
])
demean.inputs.calc_mean.in_file = os.path.abspath('data/s1/f3.nii')
demean.inputs.subtract.in_file = os.path.abspath('data/s1/f3.nii')
demean.run()
"""
Reusing workflows
-----------------
The beauty of the workflows is that they are reusable. We can just import a workflow made by someone
else and feed it with our data.
"""
from fmri_fsl import preproc
preproc.base_dir = os.path.abspath('.')
preproc.inputs.inputspec.func = os.path.abspath('data/s1/f3.nii')
preproc.inputs.inputspec.struct = os.path.abspath('data/s1/struct.nii')
preproc.run()
"""
... and we can run it again and it won't actually rerun anything because none of
the parameters have changed.
"""
preproc.run()
"""
... and we can change a parameter and run it again. Only the dependent nodes
are rerun and that too only if the input state has changed.
"""
preproc.inputs.meanfuncmask.frac = 0.5
preproc.run()
"""
Visualizing workflows 1
-----------------------
So what did we run in this precanned workflow
"""
preproc.write_graph()
"""
Datasink
--------
Datasink is a special interface for copying and arranging results.
"""
import nipype.interfaces.io as nio
preproc.inputs.inputspec.func = os.path.abspath('data/s1/f3.nii')
preproc.inputs.inputspec.struct = os.path.abspath('data/s1/struct.nii')
datasink = pe.Node(interface=nio.DataSink(),name='sinker')
preprocess = pe.Workflow(name='preprocout')
preprocess.base_dir = os.path.abspath('.')
preprocess.connect([
(preproc, datasink, [('meanfunc2.out_file', 'meanfunc'),
('maskfunc3.out_file', 'funcruns')])
])
preprocess.run()
"""
Datagrabber
-----------
Datagrabber is (surprise, surprise) an interface for collecting files from hard drive. It is very flexible and
supports almost any file organisation of your data you can imagine.
"""
datasource1 = nio.DataGrabber()
datasource1.inputs.template = 'data/s1/f3.nii'
results = datasource1.run()
print results.outputs
datasource2 = nio.DataGrabber()
datasource2.inputs.template = 'data/s*/f*.nii'
results = datasource2.run()
print results.outputs
datasource3 = nio.DataGrabber(infields=['run'])
datasource3.inputs.template = 'data/s1/f%d.nii'
datasource3.inputs.run = [3, 7]
results = datasource3.run()
print results.outputs
datasource4 = nio.DataGrabber(infields=['subject_id', 'run'])
datasource4.inputs.template = 'data/%s/f%d.nii'
datasource4.inputs.run = [3, 7]
datasource4.inputs.subject_id = ['s1', 's3']
results = datasource4.run()
print results.outputs
"""
Iterables
---------
Iterables is a special field of the Node class that enables to iterate all workfloes/nodes connected to it over
some parameters. Here we'll use it to iterate over two subjects.
"""
import nipype.interfaces.utility as util
infosource = pe.Node(interface=util.IdentityInterface(fields=['subject_id']),
name="infosource")
infosource.iterables = ('subject_id', ['s1', 's3'])
datasource = pe.Node(nio.DataGrabber(infields=['subject_id'], outfields=['func', 'struct']), name="datasource")
datasource.inputs.template = '%s/%s.nii'
datasource.inputs.base_directory = os.path.abspath('data')
datasource.inputs.template_args = dict(func=[['subject_id','f3']], struct=[['subject_id','struct']])
my_workflow = pe.Workflow(name="my_workflow")
my_workflow.base_dir = os.path.abspath('.')
my_workflow.connect([(infosource, datasource, [('subject_id', 'subject_id')]),
(datasource, preproc, [('func', 'inputspec.func'),
('struct', 'inputspec.struct')])])
my_workflow.run()
"""
and we can change a node attribute and run it again
"""
smoothnode = my_workflow.get_node('preproc.smooth')
assert(str(smoothnode)=='preproc.smooth')
smoothnode.iterables = ('fwhm', [5.,10.])
my_workflow.run()
"""
Visualizing workflows 2
-----------------------
In the case of nested workflows, we might want to look at expanded forms of the workflow.
"""
|
