Sweave
Sweave se inscribe en lo que se ha venido a denominar Literate Statistics. El objetivo es tener en un único fichero de sintaxis el texto de LaTeX y el código de R entremezclados. Cuando se procesa el código, el output mezcla automáticamente el texto de LaTeX con las tablas y otros objetos de R, lo que facilita enormemente algunas tareas como la generación periódica de informes o de textos cuando se cambian, aunque sea mínimamente, los datos de origen.
Requerimientos
- Una distribución LaTeX instalada y funcionando (teTex en GNU/Linux o MiKTeX en M$).
- Tener instalado y funcionando el sistema R.
- Un editor de sintaxis, preferentemente Emacs aunque bajo M$ se puede usar también WinEdt.
- Si se trabaja en Emacs, es aconsejable tener instalado el módulo Noweb que permite el coloreado de la sintaxis de Sweave (chunks). Ningún otro editor permite esta función.
Sintaxis básica
Los archivos de sintaxis de Sweave deben guardarse con la extensión .Rnw.
La mayor parte del fichero tendrá la apariencia de un archivo de LaTeX (incluidos los encabezados), aunque con la particularidad de contener chunks (Inglés: Trozo), que pueden entenderse como partes diferenciadas de la sintaxis correspondientes a distintos tipos de código.
Los chunks de texto, que serán procesados por LaTeX, son identificados por el signo @ antes del texto simple o antes del texto marcado con etiquetaje de LaTeX:
@ Aquí empieza el texto
Los chunks de código R, que seran evaluados por R, son identificados por el signo <<>>= antes del código:
<<>>= Código de R
El identificador de Código de R puede contener o no argumentos.
Si no se especifica ningun argumento (como en el codigo anterior) se usaran los valores por defecto que muestran tanto el input (órdenes de R), como el output (resultados de R).
Estos argumentos funcionan a manera de interruptores para:
- Mostrar o no las ordenes de R: echo=TRUE o echo=FALSE
- Mostrar o no los resultados de R: results=show o results=hide
y deben estar contenidos entre los simbolos que identifican el código R:
<<Argumento1=ValorDelArgumento1, Argumento2=ValorDelArgumento2, ...>>= Código de R
Otros posibles argumentos para estos chunks son:
- <<fig=TRUE, width=, height=>>= : Para indicar que el código que sigue a continuación generá como output un gráfico, con un ancho (width=) y altura (height=)
- results=tex : Para indicar que el código de R generará como resultado (output) directo un código de Latex, habitualmente mediante el uso de funciones de la librería xtable
- eval=FALSE : Para que el código no se evalúe en ese momento sino cuando se vuelva a llamar a ese chunk mediante su nombre, que se asigna con el argumento label=
- label= : Argumento optativo que asigna un nombre a ese chunk para poder referirnos a él posteriormente. Si el argumento label se especifica en primer lugar, no es necesario escribir la palabra label. En caso contrario debe escribirse:
<<resul2>>=
o
<<otroargumento=valorotroargumento,label=resul2>>=
Para referirnos posteriormente a ese chunk, usaremos el código:
<<argumentosdelnuevochunk>>= <<resul2>>
Es decir, crearemos un nuevo chunk con sus argumentos, y luego llamaremos al otro chunk mediante su label.
El ejemplo 5 ilustra el uso del argumento label.
Todos los argumentos que hemos revisado pueden establecerse por defecto con el código:
\SweaveOpts{argumentos}
los argumentos de código R establecidos mediante \SweaveOpts tendrán validez hasta que se especifique lo contrario, ya sea en un chunk concreto o estableciendo por defecto otros argumentos con un nuevo \SweaveOpts.
Por ejemplo, si queremos que por defecto no se muestren las ordenes de R (input):
\SweaveOpts{echo=false}
Aunque, como ya se ha dicho, la forma natural de insertar código de R es mediante el uso de chunks de código, si se trata de una única expresión el código puede ir dentro de un chunk de texto con el uso de Expresiónes de Lenguage S: \Sexpr{}. que se rellenan con ordenes de R, asi:
@
En el estudio se incluyeron \Sexpr{length(seq(1,115))} sujetos.
Si el primer chunk de texto está immediatamente después de los encabezados (es decir si no hay ningún chunk de código previamente), no es necesario especificar su inicio. En cambio, si el último chunk es de código de R, hay que especificar el inicio de un chunk de texto antes de los cierres del documento de LaTeX.
Las reglas basicas se resumen en:
- Los identificadores de cada tipo de chunk son: <<argumentos=>>= para codigo R y @ para codigo LaTeX ó texto simple.
- Para incluir ordenes de R en un chunk de texto: se utilizan \Sexpr{}
- Si se pretende construir un documento LaTeX, tanto el encabezado como el cierre deben ser formato LaTeX, para ello, si el ultimo chunk del contenido del documento es de código R, tendremos que marcar el inicio del código texto mediante @ antes de que aparezcan los códigos LaTeX de cierre de documento.
Algunos ejemplos
- Ejemplo 1:
\documentclass[12pt]{report}
\begin{document}
Se incluyeron \Sexpr{length(x<-c(rep(c(1,2),225),rep(1,114)))} sujetos, con una proporcion de hombres del
\Sexpr{100*round(prop.table(table(x))[1],2)} \%.
\end{document}
- Ejemplo 2:
\documentclass[12pt]{report}
\title{Document de prova}
\author{acrida}
\date{\today}
\begin{document}
\maketitle
<<example data 1,echo=FALSE>>=
x <- cbind(c(2,7),c(3,4))
@
Aquesta es la taula:
<<example output for data 1,results=tex,echo=FALSE>>=
library(xtable)
xtable(x)
@
\end{document}
- Ejemplo 3:
\documentclass[a4paper]{article}
\SweaveOpts{echo=true}
\begin{document}
First we define a figure hook:
<<results=hide>>=
options(SweaveHooks = list(fig = function() par(mfrow=c(2,2))))
@
Then we setup variable definitions without actually evaluating them
<<xydef,eval=false>>=
x <- 1:10
y <- rnorm(x)
@
Then we put the pieces together:
\begin{center}
<<fig=T>>=
<<xydef>>
lm1 <- lm(y~x)
summary(lm1)
plot(lm1)
@
\end{center}
\end{document}
- Ejemplo 4 (resultado aquí):
\documentclass[a4paper]{article}
\begin{document}
<<echo=false,results=hide>>=
library(lattice)
library(xtable)
data(cats, package="MASS")
@
\section*{The Cats Data}
Consider the \texttt{cats} regression example from Venables \& Ripley
(1997). The data frame contains measurements of heart and body weight
of \Sexpr{nrow(cats)} cats (\Sexpr{sum(cats$Sex=="F")} female,
\Sexpr{sum(cats$Sex=="M")} male).
A linear regression model of heart weight by sex and gender can be
fitted in R using the command
<<>>=
lm1 = lm(Hwt~Bwt*Sex, data=cats)
lm1
@
Tests for significance of the coefficients are shown in
Table~\ref{tab:coef}, a scatter plot including the regression lines is
shown in Figure~\ref{fig:cats}.
\SweaveOpts{echo=false}
<<results=tex>>=
xtable(lm1, caption="Linear regression model for cats data.", label="tab:coef")
@
\begin{figure}
\centering
<<fig=TRUE,width=12,height=6>>=
lset(col.whitebg())
print(xyplot(Hwt~Bwt|Sex, data=cats, type=c("p", "r")))
@
\caption{The cats data from package MASS.}
\label{fig:cats}
\end{figure}
\begin{center}
\end{center}
\end{document}
- Ejemplo 5:
\documentclass[a4paper]{article}
\begin{document}
Primero ponemos el input:
<<resultado,echo=TRUE,results=hide>>=
2+2
@
Y luego el output:
<<resultado2,echo=FALSE>>=
<<resultado>>
@
\end{document}
Procesamiento
El procesamiento (compilado) de un archivo de Sweave se compone básicamente de dos pasos:
- La función Sweave() de R, que evaluará los chunks con código de R y convertirá el archivo .Rnw a un archivo .tex convencional. Para realizar este paso hay que mandar la siguiente instrucción a R (desde el propio programa o desde Emacs o [1]]:
Sweave("c:/rutacompleta/nombredelarchivo.Rnw"
- Comipilar el documento .tex resultante del paso anterior para obtener, como es habitual en LaTeX, archivos .dvi, .ps o .pdf.
En sistemas M$ hay que realizar los dos pasos de forma independiente, ya sea con Emacs o con WinEdt.
En sistemas GNU/Linux, aunque también es posible realizar los pasos por separado, ambas tareas pueden automatizarse con el sistema que se explica a continuación.
Automatización del proceso con Emacs bajo GNU/Linux
Antes de poder procesar automáticamente documentos de Sweave hay que realizar el siguiente procedimiento, que deberá llevarse a cabo sólo una vez en cada ordenador y que permitirá ejecutar la función Sweave() de R sin necesidad de ejecutar manualmente el programa:
- Descargar este shell script, copiarlo a la ubicación /usr/local/bin/ y desde una ventana de terminal ejecutar:
sudo chmod +x /usr/local/bin/Sweave.sh
Una vez hecho esto, ya estamos en disposición de compilar documentos Sweave. Para ello, debemos descargar este archivo Makefile y ediarlo para sustituir la expresión:
nombrearchivo
presente en las dos primeras líneas, por el nombre de nuestro fichero Sweave sin la extensión .Rnw.
El fichero Makefile debe situarse en el mismo directorio donde tengamos el archivo .Rnw.
Así, para cada proyecto Sweave que tengamos, deberemos tener un directorio independiente con dos archivos: fichero.Rnw y un Makefile que en las dos primeras líneas contenga el nombre del archivo .Rnw (sin la extensión).
Una vez hecho esto, debemos editar el archivo .Rnw en Emacs, grabarlo y pulsar:
M-x
compile {Ret}
make -k {Ret}
Este procedimiento va a generar dos archivos con el documento final, un .pdf y otro .ps. El fichero Makefile descargado es fácilmente costumizable para que cree sólamente uno de los dos ficheros resultado.
Se acpnseja visualizar ambos tipos de archivos con el programa Gnome Ghost Viewer (es el visualizador por defecto de ficheros .ps), que actualiza directamente la vista de los archivos cuando estos cambian (es decir cada vez que se produce una nueva compilación) sin necesidad de tener que cerrar y volver a abrir el programa. Para que esto suceda, hay que marcar la opción Mira un fitxer en las preferencias del programa.
Todo lo anterior tiene la ventaja de permitir compilar archivos Sweave con una sola orden, lo que facilita la realización de compilaciones sucesivas para ir comprobando cómo está quedando nuestro documento, y detectar de forma temprana los errores en el código de R.
La compilación realizada con el procedimiento descrito tiene además otras ventajas, como por ejemplo que compila tantas veces como sea necesario el archivo .tex hasta que esté completo, lo que evita tener que recompilar manualmente los archivos que contienen, por ejemplo, referencias bibliográficas tal y como se explica en el artículo correspondiente.