-
Notifications
You must be signed in to change notification settings - Fork 0
/
13-rmd-basics-cites-and-refs.Rmd
executable file
·171 lines (122 loc) · 8.76 KB
/
13-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
162
163
164
165
166
167
168
169
170
171
---
output:
#bookdown::html_document2: default
#bookdown::word_document2: default
bookdown::pdf_document2:
template: templates/brief_template.tex
citation_package: biblatex
bib-humanities: true
documentclass: book
bibliography: 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].
### PDF output
In PDF output, the bibliography is handled by the OxThesis LaTeX template.
If you set `bib-humanities: true` in **index.Rmd**, then in-text references will be formatted as author-year; otherwise references will be shown as numbers.
If you choose author-year formatting, 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].
### Gitbook output
In gitbook output, citations are by default inserted in the Chicago author-date format.
To change the format, add `csl: some-other-style.csl` in **index.Rmd**'s YAML header.
You can browse through and download styles at [zotero.org/styles](https://www.zotero.org/styles).
\clearpage
<!-- clearpage ends the page, and also dumps out all floats.
Floats are things like tables and figures. -->
### Insert references easily with the `citr` add-in
For an easy way to insert citations, try the [`citr`](https://github.com/crsh/citr) RStudio add-in (Figure \@ref(fig:citr)).
You can install this add-in by typing `install.packages("citr")` in the R Console.
```{r citr, echo=FALSE, fig.cap="The `citr` add-in", out.width="80%", fig.align='center'}
# include dynamic gif if output is HTML; otherwise screenshot
if (knitr::opts_knit$get('rmarkdown.pandoc.to') == 'html'){
knitr::include_graphics("https://raw.githubusercontent.com/crsh/citr/master/tools/images/addin_demo.gif")
} else {
knitr::include_graphics("figures/sample-content/citr.png")
}
```
## 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>