Sweave is a tool for embedding R code in a LaTeX file. Pweave is an analogous tool for Python. By putting your code in your document rather than the results of running your code somewhere else, results are automatically recomputed when inputs change. This is especially useful with graphs: rather than including an image into your document, you include the code to create the image.
To use either Sweave or Pweave, you create a LaTeX file and include source code inside. A code block begins with <<>>= and ends with @ on a line by itself. By default, code blocks appear in the LaTeX output. You can start a code block with <<echo=FALSE>>= to execute code without echoing its source. In Pweave you can also use <% and %> to mark a code block that executes but does not echo. You might want to do this at the top of a file, for example, for import statements.
Sweave echos code like the R command line, with > for the command prompt. Pweave does not display the Python >>> command line prompt by default, though it will if you use the option term=TRUE in the start of your code block.
In Sweave, you can use Sexpr to inline a little bit of R code. For example, $x = Sexpr{sqrt(2)}$ will produce x = 1.414…. You can also use Sexpr to reference variables defined in previous code blocks. The Pweave analog uses <%= and %>. The previous example would be $x = <%= sqrt(2) %>$.
You can include a figure in Sweave or Pweave by beginning a code block with <<fig=TRUE, echo=FALSE>>= or with echo=TRUE if you want to display the code that produces the figure. With Sweave you don’t need to do anything else with your file. With Pweave you need to add usepackage{graphicx} at the top.
To process an Sweave file foo.Rnw, run Sweave("foo.Rnw") from the R command prompt. To process a Pweave file foo.Pnw, run Pweave -f tex foo.Pnw from the shell. Either way you get a LaTeX file that you can then compile to a PDF.
Here are sample Sweave and Pweave files. First Sweave:
\documentclass{article}
\begin{document}
Invisible code that sets the value of the variable $a$.
<<<echo=FALSE>>=
a <- 3.14
@
Visible code that sets $b$ and squares it.
<<bear, echo=TRUE>>=
b <- 3.15
b*b
@
Calling R inline: $\sqrt{2} = Sexpr{sqrt(2)}$
Recalling the variable $a$ set above: $a = Sexpr{a}$.
Here's a figure:
<<fig=TRUE, echo=FALSE>>=
x <- seq(0, 6*pi, length=200)
plot(x, sin(x))
@
\end{document}
And now Pweave:
\documentclass{article}
\usepackage{graphicx}
\begin{document}
<%
import matplotlib.pyplot as plt
from numpy import pi, linspace, sqrt, sin
%>
Invisible code that sets the value of the variable $a$.
<<echo=FALSE>>=
a = 3.14
@
Visible code that sets $b$ and squares it.
<<term=True>>=
b = 3.15
print b*b
@
Calling Python inline: $\sqrt{2} = <%= sqrt(2) %>$
Recalling the variable $a$ set above: $a = <%= a %>$.
Here's a figure:
<<fig=True, echo=False>>=
x = linspace(0, 6*pi, 200)
plt.plot(x, sin(x))
plt.show()
@
\end{document}
Org users can use the excellent Org Babel (http://orgmode.org/worg/org-contrib/babel/)
The iPython notebook somewhat obviates the need for this in many cases. Markdown is so much nicer to work with day-to-day than LaTeX.
The way I see it is you can be somewhere along a continuum between code with a little documentation and documentation with a little code.
If you’re coming from the code end and want to add documentation, IPython is the way to go. But if you’re coming from the document end, wanting to make a document a little more dynamic, Pweave may be preferable.
I ran into this when I wrote up a LaTeX report the other day that contained a few simple calculations. I had to change some data, and I changed most of the computed values that needed to change as a result, but missed some. Then I wished I’d used Pweave.
At the risk of asking a silly question, is there a Python equivalent of Knuth’s Tangle and Weave?
Yes. Pweave is like Knuth’s Weave, and Ptangle is like Knuth’s Tangle.
Many thanks John. I trust you’ll have a Merry Christmas and a Happy New Year.
It’s nice seeing this side-by-side comparison with Sweave (which I have heard about for some time) and Pweave (which I did not know about). @Chris’s comment about the IPython notebook was my initial take, too. John’s distinction about which angle you are coming to technical documentation from is a good one though, and the next time I am writing a longer report with some code, I’ll remember Pweave.
For those looking for basic “executable documentation” (or perhaps “publishable calculations”) with a WYSIWYG interface, consider the MathCad-like CompPad plugin for LibreOffice/OpenOffice: http://comppad.sourceforge.net/
It isn’t actively maintained at present, but still provides a great tool for quick projects.
There is a utility, nbconvert, that will create LaTeX from an ipython notebook. It should be straightforward to add a Pweave export capability.
I’ll second the use of Org Babel in Emacs. I do all my LaTeX editing through Org Mode anyway…
You might be interested in my PythonTeX package for LaTeX. It is similar to Pweave, but the document you write is actually a valid .tex document, so editing and compiling can be a bit more convenient. PythonTeX saves or caches all output, allows user-defined sessions that automatically run in parallel, synchronizes error line numbers with the .tex document, and can be set to automatically check for modified external dependencies such as data files. It also provides syntax highlighting of typeset code via Pygments.
Hi John,
I find that I need to do:
Recalling the variable $a$ set above: $a = \Sexpr{a}$.
in order to get the Sweave example to work. That is, I need to include the backslash prefix to \Sexpr. While this is probably obvious to most, I am only just starting to learn LateX and so it is easy to get tripped up.
Cheers
Mark
Quick note to say that the Pweave example Boolean values should be “True” and “False” rather than “TRUE” and “FALSE”.
John, have you actually used pweave to generate dynamic documents/reports? If so, what command did you run to process a pmd file (i.e. pweave file with python code and markdown in it) in order to automatically generate a rich document like pdf?