/
03-rmd-basics-cites-and-refs.Rmd
161 lines (112 loc) · 8.91 KB
/
03-rmd-basics-cites-and-refs.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
---
output:
#bookdown::html_document2: default
#bookdown::word_document2: default
bookdown::pdf_document2:
template: templates/template.tex
documentclass: book
#bibliography: [bibliography/references.bib, bibliography/additional-references.bib]
---
# Citations, cross-references, and collaboration {#cites-and-refs}
\chaptermark{Citations and cross-refs}
\minitoc <!-- this will include a mini table of contents-->
## Citations
The usual way to include citations in an *R Markdown* document is to put references in a plain text file with the extension **.bib**, in **BibTex** format.[^bib-formats]
Then reference the path to this file in **index.Rmd**'s YAML header with `bibliography: example.bib`.
[^bib-formats]: The bibliography can be in other formats as well, including EndNote (**.enl**) and RIS (**.ris**), see [rmarkdown.rstudio.com/authoring_bibliographies_and_citations](https://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html).
Most reference managers can create a .bib file with you references automatically.
However, the **by far** best reference manager to use with *R Markdown* is [Zotero](https://www.zotero.org) with the [Better BibTex plug-in](https://retorque.re/zotero-better-bibtex/), because the `citr` plugin for RStudio (see below) can read references directly from your Zotero library!
Here is an example of an entry in a **.bib** file:
```bibtex
@article{Shea2014,
author = {Shea, Nicholas and Boldt, Annika},
journal = {Trends in Cognitive Sciences},
pages = {186--193},
title = {{Supra-personal cognitive control}},
volume = {18},
year = {2014},
doi = {10.1016/j.tics.2014.01.006},
}
```
In this entry highlighed section, 'Shea2014' is the **citation identifier**.
To default way to cite an entry in your text is with this syntax: `[@citation-identifier]`.
So I might cite some things [@Shea2014; @Lottridge2012; @Mill1965].
### Appearance of citations and references section (pandoc) {#citation-appearance}
By default, `oxforddown` lets [Pandoc](https://pandoc.org) handle how citations are inserted in your text and the references section.
You can change the appearance of citations and references by specifying a CSL (Citation Style Language) file in the `csl` metadata field of **index.Rmd**.
By default, `oxforddown` by the Americal Psychological Association (7th Edition), which is an author-year format.
With this style, a number of variations on the citation syntax are useful to know:
- Put author names outside the parenthesis
- This: `@Shea2014 says blah.`
- Becomes: @Shea2014 says blah.
- Include only the citation-year (in parenthesis)
- This: `Shea et al. says blah [-@Shea2014]`
- Becomes: Shea et al. says blah [-@Shea2014]
- Add text and page or chapter references to the citation
- This: `[see @Shea2014, pp. 33-35; also @Wu2016, ch. 1]`
- Becomes: Blah blah [see @Shea2014, pp. 33-35; also @Wu2016, ch. 1].
If you want a numerical citation style instead, try `csl: bibliography/transactions-on-computer-human-interaction.csl` or just have a browse through the [Zotero Style Repository](https://www.zotero.org/styles) and look for one you like.
For convenience, you can set the line spacing and the space between the bibliographic entries in the reference section directly from the YAML header in **index.Rmd**.
If you prefer to use `biblatex` or `natbib` to handle references, see [this chapter](#customising-citations).
\clearpage
<!-- clearpage ends the page, and also dumps out all floats.
Floats are things like tables and figures. -->
### Insert references easily with RStudio's Visual Editor
For an easy way to insert citations, use RStudio's [Visual Editor](https://rstudio.github.io/visual-markdown-editing/citations.html).
Make sure you have the latest version of RStudio -- the visual editor was originally really buggy, especially in relation to references, but as per v2022.02.0, it's great!
## Cross-referencing
We can make cross-references to **sections** within our document, as well as to **figures** (images and plots) and **tables**.
The general cross-referencing syntax is **`\@ref(label)`**
### Section references
Headers are automatically assigned a reference label, which is the text in lower caps separated by dashes. For example, `# My header` is automatically given the label `my-header`. So `# My header` can be referenced with `\@ref(my-section)`
Remember what we wrote in section \@ref(citations)?
We can also use **hyperlink syntax** and add \# before the label, though this is only guaranteed to work properly in HTML output:
- So if we write `Remember what we wrote up in [the previous section](#citations)?`
- It becomes Remember what we wrote up in [the previous section](#citations)?
#### Creating custom labels
It is a very good idea to create **custom labels** for our sections. This is because the automatically assigned labels will change when we change the titles of the sections - to avoid this, we can create the labels ourselves and leave them untouched if we change the section titles.
We create custom labels by adding `{#label}` after a header, e.g. `# My section {#my-label}`.
See [our chapter title](#cites-and-refs) for an example. That was section \@ref(cites-and-refs).
### Figure (image and plot) references
- To refer to figures (i.e. images and plots) use the syntax `\@ref(fig:label)`
- **GOTCHA**: Figures and tables must have captions if you wish to cross-reference them.
Let's add an image:
```{r captain, fig.align='center', fig.cap="A marvel-lous meme", out.width="65%"}
knitr::include_graphics("figures/sample-content/captain.jpeg")
```
We refer to this image with `\@ref(fig:captain)`.
So Figure \@ref(fig:captain) is [this image](#fig:captain).
And in Figure \@ref(fig:cars-plot) we saw a [cars plot](#fig:cars-plot).
### Table references
- To refer to tables use the syntax `\@ref(tab:label)`
Let's include a table:
```{r cars-table2}
knitr::kable(cars[1:5,],
caption="Stopping cars")
```
We refer to this table with `\@ref(tab:cars-table2)`.
So Table \@ref(tab:cars-table2) is [this table](#tab:cars-table2).
And in Table \@ref(tab:cars-table) we saw more or less [the same cars table](#tab:cars-table).
### Including page numbers
Finally, in the PDF output we might also want to include the page number of a reference, so that it's easy to find in physical printed output.
LaTeX has a command for this, which looks like this: `\pageref{fig/tab:label}` (note: curly braces, not parentheses)
When we output to PDF, we can use raw LaTeX directly in our .Rmd files. So if we wanted to include the page of the cars plot we could write:
- This: `Figure \@ref(fig:cars-plot) on page \pageref(fig:cars-plot)`
- Becomes: Figure \@ref(fig:cars-plot) on page \pageref{fig:cars-plot}
#### Include page numbers only in PDF output
A problem here is that LaTeX commands don't display in HTML output, so in the gitbook output we'd see simply "Figure \@ref(fig:cars-plot) on page ".
One way to get around this is to use inline R code to insert the text, and use an `ifelse` statement to check the output format and then insert the appropriate text.
- So this: `` ``r ''`r ifelse(knitr::is_latex_output(), "Figure \\@ref(fig:cars-plot) on page \\pageref{fig:cars-plot}", "")` ``
- Inserts this (check this on both PDF and gitbook): `r ifelse(knitr::is_latex_output(), "Figure \\@ref(fig:cars-plot) on page \\pageref{fig:cars-plot}", "")`
Note that we need to escape the backslash with another backslash here to get the correct output.
## Collaborative writing
Best practices for collaboration and change tracking when using R Markdown are still an open question.
In the blog post [**One year to dissertate**](https://livefreeordichotomize.com/2018/09/14/one-year-to-dissertate/) by Lucy D'Agostino, which I highly recommend, the author notes that she knits .Rmd files to a word document, then uses the `googledrive` R package to send this to Google Drive for comments / revisions from co-authors, then incorporates Google Drive suggestions *by hand* into the .Rmd source files.
This is a bit clunky, and there are ongoing discussions among the _R Markdown_ developers about what the best way is to handle collaborative writing (see [issue #1463](https://github.com/rstudio/rmarkdown/issues/1463) on GitHub, where [CriticMarkup](http://criticmarkup.com) is among the suggestions).
For now, this is an open question in the community of R Markdown users.
I often knit to a format that can easily be imported to Google Docs for comments, then go over suggested revisions and manually incorporate them back in to the .Rmd source files.
For articles, I sometimes upload a near-final draft to [Overleaf](https://www.overleaf.com/), then collaboratively make final edits to the LaTeX file there.
I suspect some great solution will be developed in the not-to-distant future, probably by the RStudio team.
## Additional resources
- *R Markdown: The Definitive Guide* - <https://bookdown.org/yihui/rmarkdown/>
- *R for Data Science* - <https://r4ds.had.co.nz>