MATweave: Integrating MATLAB Software with LaTeX Documents

I believe very strongly in the ideas of reproducible research. These ideas arise from Jon Claerbout and were summarized by Buckheit and Donoho:

An article about computational science in a scientific publication is not the scholarship itself, it is merely advertising of the scholarship. The actual scholarship is the complete software development environment and the complete set of instructions which generated the figures.

For some time my group has been practising what they preach with making software available for reproducing all figures in the papers we produce. This should be true for all papers we are the principal authors on since about 2003. One problem that arises is that the code for reproducing the figures is normally kept in a separate file from the paper itself. If you write papers in LaTeX and produce figures in a package like R, then there is the elegant solution of using Sweave for integrating your code and your report. However, in machine learning many people use MATLAB and increasingly I'm using Octave, an open source alternative for MATLAB. MATweave is a solution for integrating Octave or MATLAB code in a LaTeX environment. I say solution, rather than software, because currently it is a couple of tricks and a couple of lines of code.

1. The first trick is to make use of block comments, introduced in Octave 3.2 and MATLAB R14. Block comments are of the form:

   %{ This is a comment!  
   This line is also commented!  
   %} 
   for i = 1:10 % Code here is outside the block comment.  
     disp(i) 
   end 
   

   And the great thing is that a block comment in MATLAB is also a LaTeX comment (but not a block comment!) because it starts with a %.
2. The second trick is to include the verbatim package and define new MATLAB/Octave environments based on comment and verbatim using the following commands.

   \usepackage{verbatim}
   \newenvironment{matlab}{\comment}{\endcomment}    
   \newenvironment{octave}{\comment}{\endcomment}    
   \newenvironment{matlabv}{\verbatim}{\endverbatim} 
   \newenvironment{octavev}{\verbatim}{\endverbatim} 
   

   This allows you to include MATLAB/Octave code that won't be read by LaTeX using e.g. \begin{octave} ... \end{octave} and code that will be shown in a verbatim environment using \begin{octavev} ... \end{octavev}. Below there is a short example.

Neil Lawrence
4th October 2010

Example

The full source code of the example is at the bottom of this page, but you may also find it in this file.

Octave

You need to use at least Octave 3.2 for the block comments to work, but then you can simply write

octave --eval source\ myexample.tex

and results will be written into files in your directory. You can achieve the same result by opening an interactive Octave session and simply type

source myexample.tex

The resulting files can be processed by LaTeX or pdfLaTeX.

pdflatex myexample

giving a result like this.

MATLAB

The absence of a source command in MATLAB makes usage less wieldy. However, a couple of tricks can be used. Under unix-like systems a symlink of the form

ln -s myexample.tex myexample.m

will allow you to treat the LaTeX code like a regular m-file. Alternatively

matlab < myexample.tex 

will cause the contents of myexample.tex to be run through the MATLAB engine.

Full Example Source Code

For the compiled version of the example see this PDF.