Chapter 2 Writing in R Markdown
R Markdown documents use the markdown language to format plain text in the final document. The bookdown package (Xie, 2020a) extends the R Markdown language to include additional features. For a full description of all the features available to you, see the Components chapter of the bookdown book (Xie, 2016). In this chapter I’ll highlight some of the key features that are most likely to be used.
2.1 Formatting text
Font can be made bold or italic by using asterisks or underscores. Make words bold by using two (i.e., **bold** or __bold__) and italic using one (i.e., *italic* or _italic_).
You can create headings by using the # sign. Each # is an additional level.
You can also create bulleted or numbered lists. Bulleted lists can be created with *, -, or +. For example,
Yields the following list:
- item one
- item two
- sub item
- item three
Similarly,
Yields a numbered list:
- item one
- item two
- sub item
- item three
You can also add code text that will be rendered in a typewriter font. This can be done inline by using single back ticks. You can also put an entire block of text in code by use three back ticks before and after the block begins and ends.
2.2 Latex Equations
Equations can be added seemlessly by using syntax. For example:
Yields the following equaiton: \[ P(X_{ij} = 1|\theta) = \frac{1}{1-e^{(-a_j (\theta_i-b_j))}} \]
Double dollar signs will center the equation on its own line. A single dollar sign before and after will include the equation inline (i.e., \(A = \pi r^2\)).
2.3 Cross References
One of the extensions provided by the bookdown package is easy cross references. To reference a figure, simply add the fig.cap arugment as a chunk option with a relevant caption.
library(ggplot2)
mtcars <- read.csv("data/mtcars.csv", stringsAsFactors = FALSE, row.names = 1)
ggplot(mtcars, aes(disp, mpg, colour = factor(cyl))) +
geom_point()
Figure 2.1: Here is a figure caption to describe this graph
This will automatically number the figure and add the caption. Figure 2.1 can then be referenced using \@ref(fig:plot), where plot is the name of the code chunk. All figures that are generated in R will be saved to the figure directory. Alternatively, you can add your own images to figure/ and add them using knitr::include_graphics().
You can similarly add references to tables. Table 2.1 is created using knitr::kable(), which allows a caption to be specified. This will number the table, which then can be referenced using similar syntax (i.e., \@ref(tab:tab-summary)). There are many different packages that will create tables for you, each with their own strengths and weaknesses. For example the rockchalk (Johnson, 2016) and texreg (Leifeld, 2017) packages will both create APA style regression tables, which can be modified to include cross references.
library(dplyr)
mtcars %>%
group_by(cyl) %>%
select(cyl:hp) %>%
summarize_all(mean) %>%
knitr::kable(caption = "Here's a table of summary statistics",
booktabs = TRUE)| cyl | disp | hp |
|---|---|---|
| 4 | 105.1364 | 82.63636 |
| 6 | 183.3143 | 122.28571 |
| 8 | 353.1000 | 209.21429 |
The third type of cross referencing is for equations. This requires a little bit more work. Recall that to create an equation above we used the following syntax:
In order to create a cross reference, we have to define the equation and then add the reference:
\begin{equation}
P(X_{ij} = 1|\theta) = \frac{1}{1-e^{(-a_j (\theta_i-b_j))}}
(\#eq:irt-model)
\end{equation}That code will render the equation and give it a number, which can then be referenced using the label provided (i.e., \@ref(eq:irt-model) will create the reference for equation (??)).
The final type of cross referencing that I’ll discuss here is referencing sections of the paper. This is done by using the section headings (i.e., we talked about equations in section 2.2). By default, references for section headings are defined by the section name. For example to reference the section on equations using , I use \@ref(latex-equations), because the name of the section is “Latex Equations”. However, you can also define your own labels by add {#label} after the section heading. For example, the section heading for section 2.1 looks like this:
So to create a reference for this section I can use \@ref(format). You can also create links. For example, the following code will create a link where the word “instructions” links to the “Getting started” section in Chapter 1:
This template comes with instructions. However, it is probably more useful to reference the specific section number using the \@ref(getting-started) syntax.
2.4 Citations
Citations are also straightforward to add in the markdown language. All that is required is a BibTeX file to be placed in the bib/ directory. You can add as many BibTeX files as you would like, as long as you list them in the bibliography: options under the YAML metadata in the main R Markdown document. To reference a citation in the text use [@reference-key] or @reference-key, where reference-key is the name given to the reference in the BibTeX file. Putting the key inside of brackets will make the entire citation appear within parentheses, whereas no brackets will put only the year in parentheses.
You can include multiple citations within a single set of brackets by separating them with a semicolon. Finally, you can suppress the author’s name by using a - sign before the key (i.e., [-@bookdown]).
By default, references for all R packages that are loaded with your session are will be written to bib/packages.bib. They key for packages will be “R-packagename”. For example, I used ggplot to generate Figure 2.1, so I could cite the package by using [@R-ggplot2] (Wickham et al., 2019).
All citations in the body of your document will automatically be included in the references chapter. If you would like to include additional references without citing them in your text, add the keys to the nocite: field of the YAML metadata.