Sage-weave

Sage-weave provides a framework for mixing text and Sage code for automatic document generation, similar to Sweave for the R language.

Sage-weave allows you to create a single source file that contains both LaTeX text and Sage code. These are then 'woven' into a final LaTeX document containing the original text together with the output of calculations and/or graphics generated by Sage. This done by running the Sage code through Sage.

This is useful for re-generate reports if the input data change and documents the code to reproduce the analysis in the same file that also contains the report.

The Sage code of the complete analysis is embedded into a LaTeX document.

Usage

Assuming that you already have Sage installed, usage is quite simple. Just download the weave.sage script, and start using it. The workflow consists of two steps. The first step is to run Sage-weave on an input .Snw file (see demo/). This runs the Sage code inside the given .Snw file and produces LaTeX output. The second step is to compile this LaTeX output with your favorite LaTeX interpreter, e.g., pdflatex.

For example:

$ sage weave.sage input.Snw
$ pdflatex input.tex

(Note that it is also possible to make the file weave.sage executable and run it directly.)

Example

.Snw files are plain LaTeX files, with a little bit of extra syntax mixed in. Anything between the lines <<>>= and @ is interpreted as Sage code. Any output from this Sage code goes directly into the LaTeX output. For shorter expressions, the \sageexpr LaTeX command can be used: the Sage expression within the curly braces is evaluated and represented as LaTeX output.

For example, the following .Snw file:

\documentclass{article}

<<>>=
x, b, c = var('x b c')
sol = solve([x^2 + b*x + c == 0], x)
@

\begin{document}
Solutions: $\sageexpr{sol[0]}$
and $\sageexpr{sol[1]}$.
\end{document}

results in the following LaTeX output:

\documentclass{article}

\begin{document}
Solutions: $x = -\frac{1}{2} \, b - \frac{1}{2} \, \sqrt{b^{2} - 4 \, c}$
and $x = -\frac{1}{2} \, b + \frac{1}{2} \, \sqrt{b^{2} - 4 \, c}$.
\end{document}

This, in result, is rendered as follows by PdfLaTeX:

Inserting figures

Sage provides functionality to save figures as pdf files (or other file formats if necessary). This can directly be used to include Sage-generated figures.

For example:

\documentclass{article}
\usepackage{graphicx}

\begin{document}
<<>>=
x1 = var("x1", latex_name = 'x_1')
x2 = var("x2", latex_name = 'x_2')
p = contour_plot(x1^2 + x2^2 + x1*x2, (x1, -5, 5), (x2, -5, 5), cmap = 'Blues')
p.save('contour.pdf')
@
\begin{center}
\includegraphics[width=.75\textwidth]{contour.pdf}
\end{center}
\end{document}

Importing code from other Sage or python modules

Importing code from other Sage or python modules is done in exactly the same way as in regular Sage:

\documentclass{article}
<<>>=
from module import my_function
@

\begin{document}
My function returns: \sageexpr{my_function()}.
\end{document}

Demonstration

See the demo/ directory for a demonstration.

Contributing

Feel free to make pull requests, as I'm generally happy with contributions.

yozw / sage-weave