For these activities we will use code and data from this excellent article:
Hoggard, C. S., McNabb, J., & Cole, J. N. (2019). The Application of Elliptic Fourier Analysis in Understanding Biface Shape and Symmetry Through the British Acheulean. Journal of Paleolithic Archaeology. https://doi.org/10.1007/s41982-019-00024-6
The authors have made their materials online at https://osf.io/g29eu/. I have slightly modified the code from the original to use in this workshop: Hoggard_et_al_2019_BM.R
Code chunks, in-line code
We are going to do live-coding demonstration of how to import data into R in our paper.Rmd. You need to save this to your computer (click to download):
Hoggard_et_al_2019_raw_data.zip
Then upload to analysis/data/raw-data, it will unzip into two files.
Now add a chunk of code to your paper.Rmd that looks exactly like this:
```{r get-ch-data}
database <-
read_csv(here::here('analysis/data/raw_data/Hoggard_et_al_2019.csv'))
tpsfile <-
read_rds(here::here('analysis/data/raw_data/Hoggard_et_al_2019_tps.rds'))
```
To use in-line R code, we can write short sentence in our paper.Rmd like this, with the single backticks:
The data has `r nrow(database)` specimens
Now knit the document and inspect the output.
Using external code
Now we will insert into our paper.Rmd some external R code that is in an R script file. Sometimes we don’t want to have all our R code in the paper.Rmd because it makes it hard to read and navigate. You need to save this R script file to your computer (right-click, ‘save link as’ to download):
Then upload it to analysis/paper.
Here is the pattern to include code from the R script file into your paper.Rmd: First we use knitr::read_chunk to identify our R script file. Then in the R code chunks we can reference the names of sections in that R script file. To try this, you need to copy and paste these lines into your paper.Rmd:
```{r}
knitr::read_chunk('Hoggard_et_al_2019_BM.R')
```
```{r Compute-symmetry-and-PCA}
```
```{r figure-1}
```
```{r figure-3}
```
```{r table-3}
```
Then knit the Rmd document right away to see how the output looks.
The new code uses some R packages that we should register in our compendium. We can use the function rrtools::add_dependencies_to_description() that will scan the Rmd file, identify libraries used in there, and add them to the DESCRIPTION file. This will register all used R packages in the compendium.
Please run rrtools::add_dependencies_to_description() now, and commit & push to GitHub
Captions & cross-references
There are two commonly used methods to add captions. First is in the code chunk header, like this:
```{r figure-1, fig.cap = "An exploration of biface shape and Marine Isotope Stage (MIS) through an elliptic Fourier principal component analysis (EFA-PCA). Confidence ellipses are here set to two-thirds (66.66%)"}
```
And the second way is outside of the code chunk using the (ref:xxx) pattern. This method is useful if you want to format the text or use inline R code in the caption:
(ref:figure-3-caption) An examination of symmetry (AD harmonic coefficients/amplitude) through a histogram (a), and two box-and-whisker plots (Tukey style) examining symmetry against individual Marine Isotope Stage (b), and against individual sites (c)
```{r figure-3, fig.cap = '(ref:figure-3-caption)'}
```
To cross-reference a plot produced by a code chunk, we use the pattern \@ref(fig:label), where label is the code chunk ID. To cross-reference Figure 3, we would write this:
- Please see Figure
\@ref(fig:figure-3)
And after we knit, we will see ‘Please see Figure 3’
Figures and tables
Often we want to include figures in our paper that are not generated by R code. For example, photographs or drawings. Let’s practice this with an image of a biface. You need to save this image file to your computer (right-click, ‘save link as’ to download):
And then upload it to your RStudio folder analysis/data/figures.
Then add this chunk of code to your paper.Rmd:
```{r my-photo, fig.cap = "Flint biface that retains small patch of cortex on edge just above butt. Found in Aveley, UK. Registration number1995,0401.284. Source: British Museum"}
knitr::include_graphics(here::here('analysis/figures/British-Museum-Biface.jpg')))
```
We can adjust the size and position of the image using the options in the chunk header, such as fig.width=2. Usually we want to set the size of the image satisfy the requirements of the journal we are submitting to, such as one column wide or two columns wide. Sometimes re-sizing photos for publication is easiest to do in other software, such as Inkscape.
Knit your paper.Rmd and take a look at the image in your document.
We can add add a table to our document using knitr::kable function. This will take a data frame and convert it into a markdown table that is basic, but looks nice in our output document. There are other packages for more complex tables, such as kableExtra, gt and many others.
Adding a caption to a table is a bit different from adding a caption to a figure. We use the caption argument in the kable function, instead of the chunk header. Cross-referencing tables is the same for figures.
```{r my-table-3"}
knitr::kable(table_3, caption = "Descriptive statistics of symmetry values for each MIS")
```
Citations and references
Citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of ‘@’ + the citation identifier from the database, and may optionally have a prefix, a locator, and a suffix. Here are some examples from RStudio:
Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].
Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
Blah blah [@smith04; @doe99].
A minus sign (-) before the @ will suppress mention of the author in the citation. This can be useful when the author is already mentioned in the text:
Smith says blah [-@smith04].
You can also write an in-text citation, as follows:
@smith04 says blah.
@smith04 [p. 33] says blah.
Special characters for scientific writing
Typically in writing for research we need to include special symbols that are not part of the common character set. The following table shows how to generate commonly used symbols in a R Markdown document, the notation surrounded by dollar signs $ is LaTeX notation:
| Symbol | Markdown/LaTeX notation |
|---|---|
| per mille ‰ | $\text{\textperthousand}$ |
| delta δ | $\delta$ |
| plus-minus ± | $\pm$ |
| degree ° | $\text{\textdegree}$ |
| subscript CO2 | CO~2~ |
| superscript 14C | ^14^C |