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
|
.. _tutorial_102:
============
Pipeline 102
============
Now that you know how to construct a workflow and execute it, we will go
into more advanced concepts. This tutorial focuses on
:class:`nipype.pipeline.engine.Workflow`
:class:`nipype.pipeline.engine.Node` and
:class:`nipype.pipeline.engine.MapNode`.
A workflow is a **directed acyclic graph (DAG)** consisting of nodes
which can be of type `Workflow`, `Node` or `MapNode`. Workflows can
be re-used and hierarchical workflows can be easily constructed.
'name' : the mandatory keyword arg
==================================
When instantiating a Workflow, Node or MapNode, a `name` has to be
provided. For any given level of a workflow, no two nodes can have the
same name. The engine will let you know if this is the case when you add
nodes to a workflow either directly using `add_nodes` or using the
`connect` function.
Names have many internal uses. They determine the name of the directory
in which the workflow/node is run and the outputs are stored.
.. testcode::
realigner = pe.Node(interface=spm.Realign(),
name='RealignSPM')
Now this output will be stored in a directory called
*RealignSPM*. Proper naming of your nodes can be advantageous
from the perspective that it provides a semantic descriptor aligned with
your thought process. This name parameter is also used to refer to nodes in
embedded workflows.
iterables
---------
This can only be set for Node and MapNode. This is syntactic sugar for
running a subgraph with the Node/MapNode at its root in a ``for``
loop. For example, consider an fMRI preprocessing pipeline that you
would like to run for all your subjects. You can define a workflow and
then execute it for every single subject inside a ``for`` loop. Consider
the simplistic example below, where startnode is a node belonging to
workflow 'mywork.'
.. testcode::
for s in subjects:
startnode.inputs.subject_id = s
mywork.run()
The pipeline engine provides a convenience function that simplifies
this:
.. testcode::
startnode.iterables = ('subject_id', subjects)
mywork.run()
This will achieve the same exact behavior as the for loop above. The
workflow graph is:
.. image:: images/proc2subj.png
:width: 650 px
Now consider the situation in which you want the last node (typically
smoothing) of your preprocessing pipeline to smooth using two
different kernels (0 mm and 6 mm FWHM). Again the common approach
would be:
.. testcode::
for s in subjects:
startnode.inputs.subject_id = s
uptosmoothingworkflow.run()
smoothnode.inputs.infile = lastnode.output.outfile
for fwhm in [0, 6]:
smoothnode.inputs.fwhm = fwhm
remainingworkflow.run()
Instead of having multiple ``for`` loops at various stages, you can set up
another set of iterables for the smoothnode.
.. testcode::
startnode.iterables = ('subject_id', subjects)
smoothnode.iterables = ('fwhm', [0, 6])
mywork.run()
This will run the preprocessing workflow for two different smoothing
kernels over all subjects.
.. image:: images/proc2subj2fwhm.png
:width: 650 px
Thus setting iterables has a multiplicative effect. In the above
examples there is a separate, distinct specifymodel node that's
executed for each combination of subject and smoothing.
iterfield
---------
This is a mandatory keyword arg for MapNode. This enables running the
underlying interface over a set of inputs and is particularly useful
when the interface can only operate on a single input. For example, the
:class:`nipype.interfaces.fsl.BET` will operate on only one (3d or 4d)
NIfTI file. But wrapping BET in a MapNode can execute it over a list of files:
.. testcode::
better = pe.MapNode(interface=fsl.Bet(), name='stripper',
iterfield=['in_file'])
better.inputs.in_file = ['file1.nii','file2.nii']
better.run()
This will create a directory called ``stripper`` and inside it two
subdirectories called ``in_file_0`` and ``in_file_1``. The output of running bet
separately on each of those files will be stored in those two
subdirectories.
This can be extended to run it on pairwise inputs. For example,
.. testcode::
transform = pe.MapNode(interface=fs.ApplyVolTransform(),
name='warpvol',
iterfield=['source_file', 'reg_file'])
transform.inputs.source_file = ['file1.nii','file2.nii']
transform.inputs.reg_file = ['file1.reg','file2.reg']
transform.run()
The above will be equivalent to running transform by taking corresponding items from
each of the two fields in iterfield. The subdirectories get always
named with respect to the first iterfield.
overwrite
---------
The overwrite keyword arg forces a node to be rerun.
The `clone` function
--------------------
The `clone` function can be used to create a copy of a workflow. No
references to the original workflow are retained. As such the clone
function requires a name keyword arg that specifies a new name for the
duplicate workflow.
.. include:: ../links_names.txt
|
