In svraka/aswp: An opinionated LaTeX template for R Markdown working papers

library(aswp)
library(texreg)

First steps

This package provides an aswp() function which is an R Markdown document format creator. To use it, you need to add aswp::aswp to the output field in the YAML metadata block of your R Markdown file. The recommended way to use this template is however by

rmarkdown::draft("paper.Rmd", template = "aswp", package = "aswp")

Or use your editor's interface to this function:

• In RStudio, open a new R Markdown document (File → New File and choose R Markdown) and select this template ("Working Paper") under From Template.
• In Emacs, use M-x poly-r-rmarkdown-create-from-template with Polymode, which is also available from the iESS menu.

This provides a basic skeleton for the most important, and non-obvious features and helps setting up a more complex document with references and appendices which are often used in research papers.

Then knit and compile like any other R Markdown document and you'll get a nicely formatted PDF. TinyTeX should automatically take care of the required \LaTeX{} packages.

Metadata fields

The basic YAML metadata fields for title, subtitle, abstract, data and thanks are available and behave similarly to the standard R Markdown template used in rmarkdown::pdf_document(). The keywords field is also available and keywords are displayed after the abstract, not just added to the PDF's metadata fields. Additionally, a list of JEL Codes can be added in the same way using the jel field. These are also displayed after the abstract.

The author field works differently than in other templates, you need to add a name label, and an optional affiliation can be used to add affiliations and contact information.

author:
  - name: First Author
    affiliation: Institute of Whatever, <[e-mail]>
  - name: Second Author
    affiliation: Company, Inc., <[e-mail]>

Citations

Add a bibliography field to the YAML frontmatter with the name of your bibliography file and cite works in the text using Pandoc's standard citation forms, e.g. @Xie2019 for @Xie2019. Both Bib\LaTeX{} and Pandoc's default pandoc-citeproc can be used for citation rendering but pandoc-citeproc is recommended. It is the only way currently to put a "References" section before the appendices. Unfortunately Pandoc is not aware of \LaTeX{}'s concept of appendices so you need to do the following incantations to add all sections to the paper in the right order, and with the right numbering.[^1]

[^1]: I'm not aware of similar hacks for Bib\LaTeX{}.

This is the last sentence of the paper.

# References {-}

<div id="refs"></div>

\appendix
\clearpage

# Appendix

Start appendix here.

If you start your document with a template from this package (rmarkdown::draft()), references and an appendix section are already set up.

R Markdown {#sec:rmarkdown}

All the usual R Markdown features work but there are some extra functionalities.

This package builds on bookdown to produce a single long-form document. This means chapters are not available but you can use cross-references with the \@ref(...) syntax for equations and text references: See Section \@ref(sec:rmarkdown).

Figure and Table notes

It is often useful to add a paragraph below a figure, or table with notes, including explanations, or references. This allows self-contained figures and tables with short, concise captions yet you can still add more context. Standard R Markdown and knitr doesn't support this for floating environments, like \LaTeX{} figures and tables.

For this feature you need to load this package at the top your R Markdown document: library(aswp). This will set up knitr hooks to insert floatfoot macros from the floatrow \LaTeX{} package into floating environments using floatfoot chunk options. See Figure \@ref(fig:plot-note) for a simple example, produced by the following markup and code:

`r ''````{r chunk-label, fig.cap = "A figure caption.",
floatfoot = "A figure note."}
plot(cars)
```

par(mar = c(4, 4, .1, .1))
plot(cars)

It is however quite inconvenient to write longer sentences, or even full paragraphs as knitr chunk options. And you'd have to write raw \LaTeX{} code and escape all the backslashes. Fortunately bookdown has a nice feature where you can use text references anywhere. First, define them:

(ref:foo) Define a text reference **here**.

Then you can use (ref:foo) as caption, or note. Both the caption and the note of Figure \@ref(fig:text-ref) were written in Markdown.

par(mar = c(4, 4, .1, .1))
plot(cars)

n <- nrow(cars)

(ref:text-ref-cap) A scatterplot of the data cars using base R graphics. (ref:text-ref-note) Note: This my note from a text reference. It is a \emph{very} long note that should overflow into multiple rows. This is all possible thanks to bookdown [@Xie2019]. Figure \@ref(fig:plot-note) is much simpler. Let's mix some maths and R code, this dataset has $N = r n$ observations. Unfortunately this note cannot be split into separate paragraphs but that's probably OK.

knitr::kable(head(cars), booktabs = TRUE, caption = "This is a table")

The same option can be used with R code that generates other floating environments, like tables, see Table \@ref(tab:table-note). The list of floating environments that make use of floatfoot options is defined in the knitr chunk option floatfoot.envs:

knitr::opts_knit$get("floatfoot.envs")

It can be extended if needed:

knitr::opts_knit$set(floatfoot.envs = c("figure", "table", "myfloat"))

This can be useful for a number of packages and functions, like knitr::kable(), stargazer::stargazer(), and xtable::xtable() that don't support any from of notes. Make sure these functions generate table environments and not longtables, as they are not yet supported. Other packages, like huxtable and texreg use the threeparttable \LaTeX{} package for notes, while kableExtra has support for footnotes in tables. This package is mostly orthogonal to these features and the different notes they can be mixed. Here, we add notes with text at footnote size and the same width as the text column. This tends to look good with paragraph-long notes.

In these packages captions are defined using function arguments inside the code chunk. Support for markup in these captions varies but simple captions usually don't require additional markup, while notes can be written using text references.

See Appendix \@ref(sec:appendix-tables) for a complex example.

Miscellaneous

As an added convenience, knitr hooks are set up to evaluate after the code chunk.

References {-}

\appendix \clearpage

Tests

This is the appendix, which is numbered differently. This only serves for testing.

Typography

\newcommand{\blabla}{The quick brown fox jumped over the lazy dog. Now in Hungarian: Árvíztűrő tükörfúrógép, and a visual test: aáeéiíoóöőuúüő. "Simple quotes" “fancy quotes”, and in „continental European” -- just an aside -- and again – but with unicode dashes – to see if works. Now in an American fashion---with an m-dash. Ligatures and other OpenType features: prefix, quantitative, a maffia mafla fia.}

\begin{description} \item[Body:] \blabla \item[Emphasis:] \emph{\blabla} \item[Bold:] \textbf{\blabla} % \item[Small caps:] \textsc{\blabla} % Not used \item[Monospaced:] \texttt{\blabla} \end{description}

Subsubsection

r set.seed(123); paste(stringi::stri_rand_lipsum(2), collapse = "\n\n")

Paragraph

This is a paragraph that shouldn't be numbered.

Another paragraph

Default Pandoc templates redefine this but we're using standard \LaTeX{} titled paragraphs, where text starts on the same line as the title.

Link colours

This is a link to a web address, these are citations @Xie2019 and -@Xie2016, [@R2019; @XieAllaireGrolemund2018; @AllaireXieMcPhersonetal2019], this is an internal reference to Section \@ref(sec:rmarkdown), and this sentence ends with a footnote.[^fntest]

[^fntest]: This is the footnote.

Maths

Check spacing of indices and parentheses: $$ f_a(x) = \sum_{n=0}^{\infty} \frac{f^{(n)}(a)}{n!} (x - a)^n \qquad (x+a)^n = \sum_{k=0}^n \binom{n}{k} x^k a^{n-k} $$ Unicode and traditional symbols: $$\text{x} \mathbf{x} x \qquad \alpha \beta \gamma \delta \epsilon \Gamma \qquad \mbfalpha \mbfbeta \mbfgamma$$

Numbers

• In math mode: $123{,}456{,}789.0$
• The same in a math environment as text: $\text{123,456,789.0}$
• In text mode 123456789.

Tables {#sec:appendix-tables}

Table \@ref(tab:table-note) is a simple table, that doesn't require any additional setup, besides specifying captions and labels. In other cases table-generating functions might need more customizations. In general, functions should output only a basic skeleton, with a table (or similar) environment, without modifying formatting, or loading \LaTeX{} packages. The following code and markup generates Table \@ref(tab:texreg) (texreg was already loaded at the top of this document).

models <- list(
  lm(mpg ~ disp + cyl,        data = mtcars),
  lm(mpg ~ disp + cyl + carb, data = mtcars)
)

texreg(
  models,
  booktabs = TRUE,
  dcolumn = TRUE,
  use.packages = FALSE,
  caption = "A table from \\textbf{texreg}",
  label = "tab:texreg",
  center = FALSE
)

(ref:texreg-note) This is a note for a regression table generated by texreg.

svraka/aswp documentation built on Dec. 3, 2020, 10:52 p.m.