Etiquetas

, , , , ,

This post provides technical details about the making of my book “Displaying time series, spatial, and space-time data with R”, a fully reproducible book including hundreds of code chunks and graphics. Hopefully this post will help others when writing a reproducible document.

Tools

Among the tools that can create reproducible documents with R, I decided to use these gems of open-source software:

Each chapter is a separate orgmode file

I use a different orgmode file for each chapter. Each file begins with a simple header. The first line uses #+PROPERTY to specify buffer-wide header arguments (it sets session to R). The second line uses #+OPTIONS to define export settings (^:nil disables TeX-like syntax for sub- and superscripts).

#+PROPERTY:  header-args :session *R*
#+OPTIONS: ^:nil

When I finished the code and figures in a chapter, but I need to make minor changes and corrections in the text, I need to disable code evaluation. Then the first line of the header is

#+PROPERTY:  header-args :session *R* :eval no-export

An example of an orgmode file follows. You have to export it with C-c C-e C-b l l. With C-c C-e the export dispatcher is started and l l chooses the LaTeX exporter and produces a file. C-b sets body-only on, and the LaTeX file will only include the body without headers.

The content of the file shows rendered by GitHub. Click here for the raw content.

Code blocks

<sec:sectionA>

Code is enclosed within #+begin_src/#+end_src
blocks.

x <- 1:10
y <- 1:10

These blocks are extracted creating a source code file (tangling)
with C-c C-v t. Without header arguments the code chunk is exported
and tangled as is. Use C-c’ to edit the current code block. This
brings up a language major-mode edit buffer containing the body of the
code block. Use C-c’ again to exit. If you need to evaluate it use
C-c C-c.

Header arguments

Using the header argument :exports none the next code chunk is not
included in the exported file (LaTeX or HTML) but is included in the
tangled file (R code). This option is useful to add configuration
code that you don’t want to show in the book.

Use :tangle no if you need to exclude a code chunk from the tangled
file.

References

Use C-c C-l or [[]] to insert a link or a reference: Section
sec:sectionA.

Figures

Figure fig:dummyGraphic is exported to a PDF file using the header arguments

xyplot(x ~ y)

LaTeX attributes

The next lines insert the PDF file with includegraphics inside a
float figure in the LaTeX file. Use #+CAPTION to define the caption
and #+ATTR_LATEX# to define the includegraphics arguments.

myFig.pdf

view raw

orgChapter.org

hosted with ❤ by GitHub

The exported LaTeX file is here:


\section{Code blocks}
\label{sec-1}
\label{sec:sectionA}
Code is enclosed within \texttt{\#+begin\_src/\#+end\_src}
\href{http://orgmode.org/manual/Structure-of-code-blocks.html}{blocks}.
\lstset{language=R,numbers=none}
\begin{lstlisting}
x <- 1:10
y <- 1:10
\end{lstlisting}
These blocks are \href{http://orgmode.org/manual/Extracting-source-code.html}{extracted creating a source code file} (\emph{tangling})
with \texttt{C-c C-v t}. Without header arguments the code chunk is exported
and tangled as is. Use =C-c `= to edit the current code block. This
brings up a language major-mode edit buffer containing the body of the
code block. Use \texttt{C-c '= again to exit. If you need to evaluate it use
=C-c C-c}.
\subsection{Header arguments}
\label{sec-1-1}
Using the \href{http://orgmode.org/manual/Specific-header-arguments.html#Specific-header-arguments}{header argument} \texttt{:exports none} the next code chunk is \textbf{not}
included in the exported file (\LaTeX{} or HTML) but is included in the
tangled file (\texttt{R}). This option is useful to add configuration
code that you don't to show in the book.
Use \texttt{:tangle no} if you need to exclude a code chunk from the tangled
file.
\section{References}
\label{sec-2}
Use \texttt{C-c C-l} or \texttt{[[]]} to insert a link or a reference: Section
\ref{sec:sectionA}.
\section{Figures}
\label{sec-3}
Figure \ref{fig:dummyGraphic} is exported to a PDF file using the header arguments
\begin{itemize}
\item \texttt{:results output graphics}. The \href{http://orgmode.org/manual/results.html#results}{results header argument} writes the
graphics output to the file specified in the \href{http://orgmode.org/manual/file.html#file}{\texttt{:file} header
argument}. You need this specification when using \texttt{lattice} and
\texttt{ggplot2} graphics.
\item \href{http://orgmode.org/manual/exports.html#exports}{\texttt{:exports both}}. Both the code and results are included in the \LaTeX{}
exported file.
\end{itemize}
\lstset{language=R,numbers=none}
\begin{lstlisting}
xyplot(x ~ y)
\end{lstlisting}
\includegraphics[width=.9\linewidth]{myFig.pdf}
\subsection{\LaTeX{} attributes}
\label{sec-3-1}
The next lines insert the PDF file with \texttt{includegraphics} inside a
float figure in the \LaTeX{} file. Use \texttt{\#+CAPTION} to define the caption
and \#+ATTR\_LATEX\# to define the \texttt{includegraphics} arguments.
\begin{figure}[htb]
\centering
\includegraphics[height=0.45\textheight]{myFig.pdf}
\caption{\label{fig:dummyGraphic}A dummy graphic}
\end{figure}

view raw

orgChapter.tex

hosted with ❤ by GitHub

A LaTeX file for each Part

Each of these exported files is a children of a LaTeX file with a very simple structure. It starts with \part and includes several \chapter. Under each \chapter you will find an \input statement that imports the LaTeX file produced with our orgmode file into its parent.


\part{My First Part}
\label{part:part1}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam nec
lacus nec dui semper aliquet sit amet in leo. Integer volutpat eu diam
sed iaculis.
\chapter{My First Chapter}
\label{cha:cha1}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam nec
lacus nec dui semper aliquet sit amet in leo. Integer volutpat eu diam
sed iaculis.
\input{orgChapter1}
\chapter{My Second Chapter}
\label{cha:cha2}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam nec
lacus nec dui semper aliquet sit amet in leo. Integer volutpat eu diam
sed iaculis.
\input{orgChapter2}
%%% Local Variables:
%%% TeX-master: "main.tex"
%%% End:

view raw

texPart.tex

hosted with ❤ by GitHub

A master LaTeX file for the book

Finally, there is a master file that includes the LaTeX preamble and several \include commands to import the previous parent files. It is important to note that the parent LaTeX files include three lines at the end.

%%% Local Variables:
%%% TeX-master: "main.tex"
%%% End:

This code is used by AUCTeX to work with a multifile structure and run commands on the master file.

The master file loads the memoir class, a powerful class extremely useful for designing books. It offers an extensive manual with more than 500 pages containing also examples for the design of a book and of a thesis.

The code blocks are highlighted with the listings package with this configuration:

\lstset{
  %keywordstyle=\color{Blue},
  commentstyle=\color{gray!90},
  % stringstyle=\color{OliveGreen},
  basicstyle=\ttfamily\small,
  columns=fullflexible,
  breaklines=true,
  linewidth=\textwidth,
  backgroundcolor=\color{gray!10},
  basewidth={0.5em,0.4em},
%  frame=single,
  literate={á}{{\'a}}1 {ñ}{{\~n}}1 {é}{{\'e}}1 {ó}{{\'o}}1 {º}{{\textordmasculine}}1
}

This is the master file:


\documentclass[smallroyalvopaper]{memoir}
\settypeblocksize{6.5in}{4.5in}{*}
\setlrmargins{*}{*}{1}
\checkandfixthelayout
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Misc packages
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage[english]{babel}
\usepackage[usenames,dvipsnames]{xcolor}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[noprefix]{nomencl}
\usepackage{url}
\usepackage{amssymb}
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{makeidx}
\usepackage{pifont}
\usepackage{fourier}
\usepackage{siunitx}
\usepackage{textcomp}
\usepackage{mathpazo}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Bibliography
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage[citestyle=authoryear,bibstyle=authoryear,doi=true,url=true]{biblatex}
\let\cite\parencite
\addbibresource{myBib.bib}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Memoir config
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{memhfixc}
\usepackage{mempatch}
\raggedbottom
\sloppybottom
\clubpenalty=10000
\widowpenalty=10000
\feetbelowfloat
\chapterstyle{ger}
\setlength{\afterchapskip}{35pt}
\maxtocdepth{section}
\setsecnumdepth{subsubsection}
\renewcommand{\topfraction}{0.85}
\renewcommand{\bottomfraction}{0.5}
\renewcommand{\textfraction}{0.15}
\renewcommand{\floatpagefraction}{0.7}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Hyperref
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{hyperref}
\hypersetup{
bookmarks=true, % show bookmarks bar?
bookmarksnumbered=false,
bookmarksopen=false,
breaklinks=true,
backref=true,
pdftoolbar=true, % show Acrobat’s toolbar?
pdfmenubar=true, % show Acrobat’s menu?
pdffitwindow=false, % window fit to page when opened
pdfstartview={FitH}, % fits the width of the page to the window
pdftitle={My Title}, % title
pdfauthor={My Name}, % author
pdfcreator={AucTeX/Emacs}, % creator of the document
pdfproducer={LaTeX}, % producer of the document
pdfnewwindow=true, % links in new window
pdfborder={0 0 0},
colorlinks=true, % false: boxed links; true: colored links
linkcolor=black, % color of internal links
citecolor=black, % color of links to bibliography
filecolor=black, % color of file links
urlcolor=Blue % color of external links
}
\usepackage{breakurl}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Figure and table environment and captions
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\captionnamefont{\scshape}
\makeatletter
\renewenvironment{figure}[1][]{%
\@float{figure}%
\precaption{\rule{\linewidth}{0.4pt}\par}
\centering
}{%
\end@float
}
\makeatother
\makeatletter
\renewenvironment{table}[1][]{%
\@float{table}%
\postcaption{\rule{\linewidth}{0.4pt}\par}
\centering
}{%
\end@float
}
\makeatother
\renewcommand{\textfloatsep}{10pt}%Espacio entre el flotante y el texto
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Code printing with listings
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{listings}
\lstset{
%keywordstyle=\color{Blue},
commentstyle=\color{gray!90},
% stringstyle=\color{OliveGreen},
basicstyle=\ttfamily\small,
columns=fullflexible,
breaklines=true,
linewidth=\textwidth,
backgroundcolor=\color{gray!10},
basewidth={0.5em,0.4em},
% frame=single,
literate={á}{{\'a}}1 {ñ}{{\~n}}1 {é}{{\'e}}1 {ó}{{\'o}}1 {º}{{\textordmasculine}}1
}
\renewcommand{\lstlistingname}{Code}
\usepackage{fancyvrb}
\DefineVerbatimEnvironment{verbatim}{Verbatim}{%
fontsize=\small,
formatcom = {\color{gray!97}}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Title, author and date format
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\pretitle{\vfill\begin{flushright}\bfseries\scshape\HUGE\color{BrickRed}}
\posttitle{\par\end{flushright}}
\preauthor{\begin{flushright}\large\scshape}
\postauthor{\par\end{flushright}}
\predate{\vfill\begin{flushright}\large\scshape}
\postdate{\par\end{flushright}\vfill}
\makeindex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Hyphenation rules for code inside texttt
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage[htt]{hyphenat}
\hyphenation{Spatial-Points}
\hyphenation{Spatial-Pixels}
\hyphenation{Spatial-Grid}
\hyphenation{Spatial-Lines}
\hyphenation{Spatial-Polygons}
\hyphenation{Spatial-Points-Data-Frame}
\hyphenation{Spatial-Lines-Data-Frame}
\hyphenation{Spatial-Polygons-Data-Frame}
\hyphenation{Raster-Layer}
\hyphenation{Raster-Stack}
\hyphenation{Raster-Brick}
\hyphenation{read-Shape-Poly}
\hyphenation{read-Shape-Points}
\hyphenation{read-Shape-Lines}
\hyphenation{write-Points-Shape}
\hyphenation{write-Lines-Shape}
\hyphenation{write-Poly-Shape}
\hyphenation{union-Spatial-Polygons}
\hyphenation{Open-Street-Maps}
\hyphenation{Java-Script}
\hyphenation{space-time}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%End of Preamble
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Body
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
\begin{titlingpage}
\title{The Title}
\author{My Name}
\date{March 10th, 2014}
\maketitle
\end{titlingpage}
\frontmatter
\tableofcontents
\clearpage
\mainmatter
\include{part1}
\include{part2}
\backmatter
\printbibliography
\clearpage
\printindex
\end{document}

view raw

master.tex

hosted with ❤ by GitHub