DOC reworked devel/matlab_interface_devel.rst: move code to external files and correct output specification in example 2.

Author: Mathieu Dubois

doc/devel/matlab_example1.py

@@ -0,0 +1,47 @@
+from nipype.interfaces.matlab import MatlabCommand
+from nipype.interfaces.base import TraitedSpec, \
+    BaseInterface, BaseInterfaceInputSpec, File
+import os
+from string import Template
+
+
+class ConmapTxt2MatInputSpec(BaseInterfaceInputSpec):
+    in_file = File(exists=True, mandatory=True)
+    out_file = File('cmatrix.mat', usedefault=True)
+
+
+class ConmapTxt2MatOutputSpec(TraitedSpec):
+    out_file = File(exists=True)
+
+
+class ConmapTxt2Mat(BaseInterface):
+    input_spec = ConmapTxt2MatInputSpec
+    output_spec = ConmapTxt2MatOutputSpec
+
+    def _run_interface(self, runtime):
+        d = dict(in_file=self.inputs.in_file,
+                 out_file=self.inputs.out_file)
+        # This is your MATLAB code template
+        script = Template("""in_file = '$in_file';
+                             out_file = '$out_file';
+                             ConmapTxt2Mat(in_file, out_file);
+                             exit;
+                          """).substitute(d)
+
+        # mfile = True  will create an .m file with your script and executed.
+        # Alternatively
+        # mfile can be set to False which will cause the matlab code to be
+        # passed
+        # as a commandline argument to the matlab executable
+        # (without creating any files).
+        # This, however, is less reliable and harder to debug
+        # (code will be reduced to
+        # a single line and stripped of any comments).
+        mlab = MatlabCommand(script=script, mfile=True)
+        result = mlab.run()
+        return result.runtime
+
+    def _list_outputs(self):
+        outputs = self._outputs().get()
+        outputs['out_file'] = os.path.abspath(self.inputs.out_file)
+        return outputs

doc/devel/matlab_example2.py

@@ -0,0 +1,54 @@
+from nipype.interfaces.base import traits
+from nipype.interfaces.base import TraitedSpec
+from nipype.interfaces.matlab import MatlabCommand, MatlabInputSpec
+
+
+class HelloWorldInputSpec(MatlabInputSpec):
+    name = traits.Str(mandatory=True,
+                      desc='Name of person to say hello to')
+
+
+class HelloWorldOutputSpec(TraitedSpec):
+    matlab_output = traits.Str()
+
+
+class HelloWorld(MatlabCommand):
+    """Basic Hello World that displays Hello <name> in MATLAB
+
+    Returns
+    -------
+
+    matlab_output : capture of matlab output which may be
+                    parsed by user to get computation results
+
+    Examples
+    --------
+
+    >>> hello = HelloWorld()
+    >>> hello.inputs.name = 'hello_world'
+    >>> out = hello.run()
+    >>> print out.outputs.matlab_output
+    """
+    input_spec = HelloWorldInputSpec
+    output_spec = HelloWorldOutputSpec
+
+    def _my_script(self):
+        """This is where you implement your script"""
+        script = """
+        disp('Hello %s Python')
+        two = 1 + 1
+        """ % (self.inputs.name)
+        return script
+
+    def run(self, **inputs):
+        # Inject your script
+        self.inputs.script = self._my_script()
+        results = super(MatlabCommand, self).run(**inputs)
+        stdout = results.runtime.stdout
+        # Attach stdout to outputs to access matlab results
+        results.outputs.matlab_output = stdout
+        return results
+
+    def _list_outputs(self):
+        outputs = self._outputs().get()
+        return outputs

doc/devel/matlab_interface_devel.rst

@@ -11,115 +11,17 @@ Example 1
 This is a minimal script for wrapping MATLAB code. You should replace the MATLAB
 code template, and define approriate inputs and outputs.
 
-.. testcode::
-
-    from nipype.interfaces.matlab import MatlabCommand
-    from nipype.interfaces.base import TraitedSpec, \
-        BaseInterface, BaseInterfaceInputSpec, File
-    import os
-    from string import Template
-    
-    
-    class ConmapTxt2MatInputSpec(BaseInterfaceInputSpec):
-        in_file = File(exists=True, mandatory=True)
-        out_file = File('cmatrix.mat', usedefault=True)
-    
-    
-    class ConmapTxt2MatOutputSpec(TraitedSpec):
-        out_file = File(exists=True)
-    
-    
-    class ConmapTxt2Mat(BaseInterface):
-        input_spec = ConmapTxt2MatInputSpec
-        output_spec = ConmapTxt2MatOutputSpec
-    
-        def _run_interface(self, runtime):
-            d = dict(in_file=self.inputs.in_file,
-                     out_file=self.inputs.out_file)
-            # This is your MATLAB code template
-            script = Template("""in_file = '$in_file';
-                                 out_file = '$out_file';
-                                 ConmapTxt2Mat(in_file, out_file);
-                                 exit;
-                              """).substitute(d)
-    
-            # mfile = True  will create an .m file with your script and executed.
-            # Alternatively
-            # mfile can be set to False which will cause the matlab code to be
-            # passed
-            # as a commandline argument to the matlab executable
-            # (without creating any files).
-            # This, however, is less reliable and harder to debug
-            # (code will be reduced to
-            # a single line and stripped of any comments).
-            mlab = MatlabCommand(script=script, mfile=True)
-            result = mlab.run()
-            return result.runtime
-    
-        def _list_outputs(self):
-            outputs = self._outputs().get()
-            outputs['out_file'] = os.path.abspath(self.inputs.out_file)
-            return outputs
+.. literalinclude:: matlab_example1.py
 
+:download:`Download the source code of this example <matlab_example1.py>`.
 
 Example 2
 +++++++++
 
-By subclassing **MatlabCommand** for your main class, and **MatlabInputSpec** for your input and output spec, you gain access to some useful MATLAB hooks
+By subclassing :class:`nipype.interfaces.matlab.MatlabCommand` for your main class, and :class:`nipype.interfaces.matlab.MatlabInputSpec` for your input spec, you gain access to some useful MATLAB hooks
 
-.. testcode::
+.. literalinclude:: matlab_example2.py
 
-    from nipype.interfaces.base import traits
-    from nipype.interfaces.matlab import MatlabCommand, MatlabInputSpec
-    
-    
-    class HelloWorldInputSpec(MatlabInputSpec):
-        name = traits.Str(mandatory=True,
-                          desc='Name of person to say hello to')
-    
-    
-    class HelloWorldOutputSpec(MatlabInputSpec):
-        matlab_output = traits.Str()
-    
-    
-    class HelloWorld(MatlabCommand):
-        """Basic Hello World that displays Hello <name> in MATLAB
-    
-        Returns
-        -------
-    
-        matlab_output : capture of matlab output which may be
-                        parsed by user to get computation results
-    
-        Examples
-        --------
-    
-        >>> hello = HelloWorld()
-        >>> hello.inputs.name = 'hello_world'
-        >>> out = hello.run()
-        >>> print out.outputs.matlab_output
-        """
-        input_spec = HelloWorldInputSpec
-        output_spec = HelloWorldOutputSpec
-    
-        def _my_script(self):
-            """This is where you implement your script"""
-            script = """
-            disp('Hello %s Python')
-            two = 1 + 1
-            """ % (self.inputs.name)
-            return script
-    
-        def run(self, **inputs):
-            # Inject your script
-            self.inputs.script = self._my_script()
-            results = super(MatlabCommand, self).run(**inputs)
-            stdout = results.runtime.stdout
-            # Attach stdout to outputs to access matlab results
-            results.outputs.matlab_output = stdout
-            return results
-    
-        def _list_outputs(self):
-            outputs = self._outputs().get()
-            return outputs
+:download:`Download the source code of this example <matlab_example2.py>`.
 
+.. include:: ../links_names.txt