DOC updates in users/tutorial_101: move code in external file (and update it), mention that nodes need absolut file path correct typos and add download section.

Author: Mathieu Dubois

doc/users/tutorial_101.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+import os
+import nipype.interfaces.spm as spm         # the spm interfaces
+import nipype.pipeline.engine as pe         # the workflow and node wrappers
+
+import nipype.interfaces.matlab as mlab      # how to run matlab
+# Path to matlab
+mlab.MatlabCommand.set_default_matlab_cmd("/full/path/to/matlab_exe")
+# Add SPM to MATLAB path if not present
+mlab.MatlabCommand.set_default_paths("/full/path/to/spm")
+
+#
+# Define nodes
+#
+
+realigner = pe.Node(interface=spm.Realign(), name='realign')
+realigner.inputs.in_files = os.abspath('somefuncrun.nii')
+realigner.inputs.register_to_mean = True
+
+smoother = pe.Node(interface=spm.Smooth(fwhm=6), name='smooth')
+
+#
+# Creating and configuring a workflow
+#
+workflow = pe.Workflow(name='preproc')
+workflow.base_dir = '.'
+
+#
+# Connecting nodes to each other
+#
+workflow.connect(realigner, 'realigned_files', smoother, 'in_files')
+
+
+#
+# Visualizing the workflow
+#
+workflow.write_graph()
+
+#
+# Extend it
+#
+import nipype.algorithms.rapidart as ra
+artdetect = pe.Node(interface=ra.ArtifactDetect(), name='artdetect')
+artdetect.inputs.use_differences = [True, False]
+artdetect.inputs.use_norm = True
+artdetect.inputs.norm_threshold = 0.5
+artdetect.inputs.zintensity_threshold = 3
+artdetect.inputs.parameter_source = 'SPM'
+artdetect.inputs.mask_type = 'spm_global'
+workflow.connect([(realigner, artdetect,
+                   [('realigned_files', 'realigned_files'),
+                    ('realignment_parameters', 'realignment_parameters')]
+                  )])
+workflow.write_graph()
+
+#
+# Execute the workflow
+#
+workflow.run()

doc/users/tutorial_101.rst

@@ -25,30 +25,24 @@ setting up a workflow is separate from executing it.
 
 **1. Import appropriate modules**
 
-.. testcode::
-
-   import nipype.interfaces.spm as spm         # the spm interfaces
-   import nipype.pipeline.engine as pe         # the workflow and node wrappers
+.. literalinclude:: tutorial_101.py
+   :lines: 2-4
 
 **2. Define nodes**
 
 Here we take instances of interfaces and make them pipeline compatible by
 wrapping them with pipeline specific elements. To determine the inputs and outputs
 of a given interface, please see :ref:`interface_tutorial`. Let's
-start with defining a realign node using the interface
-:class:`nipype.interfaces.spm.Realign`
+start with defining a realign node using the :ref:`Realign <nipype.interfaces.spm.Realign>` interface:
 
-.. testcode::
-
-   realigner = pe.Node(interface=spm.Realign(), name='realign')
-   realigner.inputs.in_files = 'somefuncrun.nii'
-   realigner.inputs.register_to_mean = True
+.. literalinclude:: tutorial_101.py
+   :lines: 16-18
 
 This would be equivalent to:
 
 .. testcode::
-
-   realigner = pe.Node(interface=spm.Realign(infile='somefuncrun.nii',
+   
+   realigner = pe.Node(interface=spm.Realign(infile=os.abspath('somefuncrun.nii'),
                                              register_to_mean = True),
                        name='realign')
 
@@ -58,15 +52,17 @@ later or while initializing the interface.
 
 .. note::
 
-   In the above example, 'somefuncrun.nii' has to exist, otherwise the
-   commands won't work. A node will check if appropriate inputs are
-   being supplied.
+   a) In the above example, 'somefuncrun.nii' has to exist in the current directory,
+   otherwise the commands won't work. A node will check if appropriate
+   inputs are being supplied.
 
-Similar to the realigner node, we now set up a smoothing node.
+   b) As noted above, you have to use the absolute path
+   of the file otherwise the workflow will fail to run.
 
-.. testcode::
+Similar to the realigner node, we now set up a smoothing node.
 
-   smoother = pe.Node(interface=spm.Smooth(fwhm=6), name='smooth')
+.. literalinclude:: tutorial_101.py
+   :lines: 20
 
 Now we have two nodes with their inputs defined. Note that we have not defined
 an input file for the smoothing node. This will be done by connecting the
@@ -77,17 +73,15 @@ realigner to the smoother in step 5.
 Here we create an instance of a workflow and indicate that it should operate in
 the current directory.
 
-.. testcode::
-
-   workflow = pe.Workflow(name='preproc')
-   workflow.base_dir = '.'
+.. literalinclude:: tutorial_101.py
+   :lines: 25-26
 
 **4. Adding nodes to workflows (optional)**
 
 If nodes are going to be connected (see step 5), this step is not
 necessary. However, if you would like to run a node by itself without
 connecting it to any other node, then you need to add it to the
-workflow. For adding nodes, order of nodes is not important.
+workflow. When adding nodes, the order is not important.
 
 .. testcode::
 
@@ -100,15 +94,14 @@ This results in a workflow containing two isolated nodes:
 **5. Connecting nodes to each other**
 
 We want to connect the output produced by the node realignment to the input of
-the node smoothing. This is done as follows.
-
-.. testcode::
+the node smoothing. This is done as follows:
 
-   workflow.connect(realigner, 'realigned_files', smoother, 'in_files')
+.. literalinclude:: tutorial_101.py
+   :lines: 31
 
-
-Although not shown here, the following notation can be used to connect multiple outputs from one node to
-multiple inputs (see step 7 below).
+or alternatively, a more flexible notation can be used. Although not shown here,
+the following notation can be used to connect multiple outputs from one node to
+multiple inputs (see step 7 below):
 
 .. testcode::
 
@@ -121,8 +114,8 @@ This results in a workflow containing two connected nodes:
 **6. Visualizing the workflow**
 
 The workflow is represented as a directed acyclic graph (DAG) and one
-can visualize this using the following command. In fact, the pictures
-above were generated using this.
+can visualize this using the following command (in fact, the pictures
+above were generated using this):
 
 .. testcode::
 
@@ -147,18 +140,9 @@ options:
 Now that you have seen a basic pipeline let's add another node to the
 above pipeline.
 
-.. testcode::
 
-   import nipype.algorithms.rapidart as ra
-   artdetect = pe.Node(interface=ra.ArtifactDetect(), name='artdetect')
-   artdetect.inputs.use_differences  = [True, False]
-   art.inputs.use_norm = True
-   art.inputs.norm_threshold = 0.5
-   art.inputs.zintensity_threshold = 3
-   workflow.connect([(realigner, artdetect,
-                      [('realigned_files', 'realigned_files'),
-                       ('realignment_parameters','realignment_parameters')]
-                     )])
+.. literalinclude:: tutorial_101.py
+   :lines: 42-53
 
 .. note::
 
@@ -180,14 +164,17 @@ This results in
 Assuming that **somefuncrun.nii** is actually a file or you've
 replaced it with an appropriate one, you can run the pipeline with:
 
-.. testcode::
-
-   workflow.run()
+.. literalinclude:: tutorial_101.py
+   :lines: 59
 
 This should create a folder called preproc in your current directory,
 inside which are three folders: realign, smooth and artdetect (the names
 of the nodes). The outputs of these routines are in these folders.
 
+.. admonition:: Example source code
+
+  You can download :download:`the source code of this example <tutorial_101.py>`.
+
 .. include:: ../links_names.txt
 
 .. glossary::