DOC: Added matlab_wrap example that allows for more control and access to MAtlabCommand inputs and outputs

Author: cindeem

Diff for: doc/devel/matlab_interface_devel.rst

@@ -7,6 +7,10 @@ How to wrap a MATLAB script
 This is minimal script for wrapping MATLAB code. You should replace the MATLAB
 code template, and define approriate inputs and outputs.
 
+
+Example 1
++++++++++
+
 .. testcode::
 
 	from nipype.interfaces.matlab import MatlabCommand
@@ -35,17 +39,95 @@ code template, and define approriate inputs and outputs.
 	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
+	        # 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()
+		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
 
+
+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
+
+.. testcode::
+ 
+	import os
+        from nipype.interfaces.base import File, 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(matlab_cmd = 'mymatlab')
+            >>> hello.inputs.name = 'Monty'
+            >>> hello.inputs.mfile = True #creates mfile
+            >>> hello.inputs.paths = '/path/to/matlab/toolbox'
+            >>> hello.inputs.script_file = 'helloworld_pyscript.m'
+            >>> out = hello.run()
+            >>> 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
+
+
+
+
+
+
+
+