main.Rmd

---
# set bibliography path
bibliography: sample-bibliography.bib

# choose template format
format: manuscript   #or acmsmall, acmlarge, acmtog, sigconf, or sigplan
anonymous: false
screen: true
review: true

#conference and copyright meta
setcopyright: acmlicensed #or acmcopyright, none, etc...
copyright-year: 2021
acm-year: 2018
acmDOI: 10.1145/1122445.1122456
conference-short: CHI'21
conference: CHI Conference on Human Factors in Computing Systems Proceedings
conference-date: May 8--13, 2021
conference-location: Yokohama, Japan
acm-booktitle: CHI Conference on Human Factors in Computing Systems Proceedings (CHI 2021), May 8--13, 2021, Yokohama, Japan
acm-price: 15.00
acmISBN: 978-1-4503-XXXX-X/18/06

# paper meta
title: Writing CHI Proceedings Papers With R Markdown
short-title: CHI Papers With R Markdown
author:
  - name: Ben Trovato
    authornote: Both authors contributed equally to this research.
    email: trovato\@corporation.com  #NOTE: you must escape the @
    orcid: 1234-5678-9012
  - name: G.K.M. Tobin
    authornotemark: 1 #use this if you just want a mark
    affiliation:
      institution: Institute for Clarity in Documentation
      streetaddress: P.O. Box 1212
      city: Dublin
      state: Ohio
      postcode: 43017-6221
    email: webmaster\@marysville-ohio.com
  - name: Lars Thørväld
    affiliation:
      institution: The Thørväld Group
      streetaddress: 1 The Thørväld Circle
      city: Hekla
      country: Iceland
    email: larst\@affiliation.org
  - name: Valerie Béranger
    affiliation:
      institution: Inria Paris-Rocquencourt
      city: Rocquencourt
      country: France
  - name: Aparna Patel
    affiliation:
      institution: Rajiv Gandhi University
      streetaddress: Rono-Hills
      city: Doimukh
      state: Arunachal Pradesh
      country: India
  - name: Huifen Chan
    affiliation:
      institution: Tsinghua University
      streetaddress: 30 Shuangqing Rd
      city: Haidian Qu
      state: Beijing Shi
      country: China
  - name: Charles Palmer
    affiliation:
      institution: Palmer Research Laboratories
      streetaddress: 8600 Datapoint Drive
      city: San Antonio
      state: Texas
      postcode: 78229
    email: cpalmer\@prl.com
  - name: John Smith
    affiliation:
      institution: The Thørväld Group
    email: jsmith\@affiliation.org
  - name: Julius P. Kumquat
    affiliation:
      institution: The Kumquat Consortium
    email: jpkumquat\@consortium.net
#short-authors: Trovato and Tobin, et al.
keywords: datasets, neural networks, gaze detection, text tagging
teaser-figure: figures/sampleteaser.pdf
teaser-caption: Seattle Mariners at Spring Training, 2010.
teaser-description: Enjoying the baseball game from the third-base seats. Ichiro Suzuki preparing to bat.
teaser-label: teaser

# output options
output: 
  bookdown::pdf_document2: 
    template: acmart-master/chi_2021_template.tex
    keep_tex: true
    citation_package: natbib
    includes:
      in_header: ccsxml.tex

---

```{r load_pkgs, include=FALSE}
# Packages required to use this template
pkg <- c("tidyverse", "knitr", "bookdown")
# Check if packages are not installed and assign the
# names of the packages not installed to the variable new.pkg
new.pkg <- pkg[!(pkg %in% installed.packages())]
# If there are any packages in the list that aren't installed,
# install them
if (length(new.pkg))
  install.packages(new.pkg, repos = "http://cran.rstudio.com")
```

```{r setup_output, include=FALSE}
library(knitr)
#library(Cairo) #required if you need figures to be saved as pdfs with fonts embedded; see below
##### YOU MUST INCLUDE THE BELOW IN A CHUNK AT THE TOP OF YOUR .RMD SOURCE
##### TO CREATE ADDITIONAL CHUNK OPTIONS FOR E.G FIGURE DESCRIPTIONS
# 1. If you want figures to be saved as pdfs with fonts embedded, set dev = "cairo_pdf" instead of dev = "pdf", and load the 'Cairo' library;
# if you are on a Mac, the Cairo library requires XQuartz which you can install from https://www.xquartz.org
# 2. out.extra ensures that knitr uses LaTeX code for figures, cf. https://stackoverflow.com/questions/42486617/knitr-ignoring-fig-pos
if (knitr::opts_knit$get('rmarkdown.pandoc.to') == 'latex') {
  knitr::opts_chunk$set(out.extra = '')
}
# create additional chunk options
hook_chunk = knit_hooks$get('chunk')
knit_hooks$set(chunk = function(x, options) {
  txt = hook_chunk(x, options)
  # add chunk option 'vspaceout' to position chunks vertically with \vspace
  if (!is.null(options$vspaceout)) {
    latex_vspace <- paste0("\\1\\\\vspace\\{", options$vspaceout, "\\}")
    txt <- sub('(\\\\begin[^}]+})', latex_vspace, txt)  
  }
  # add chunk option 'description' which adds \Description{...} to figures
  if (!is.null(options$description)) {
    latex_include <- paste0("\\1\\\\Description\\{", options$description, "\\}")
    gsub('(\\\\includegraphics[^}]+})', latex_include, txt) 
  } else {
    return(txt)  # pass to default hook
  }
})
```

# Introduction
Using a tool like [R Markdown](https://rmarkdown.rstudio.com) to write scientific papers makes your work more transparent and reproducible. 
It also reduces the risk of errors, because you can dynamically insert tables, figures, and summary statistics directly from the data they are generated from insted of transferring results manually from statistical software to manuscript.

This example illustrates how to use the ACM Master LaTeX template with R Markdown to write papers for the [CHI conference](https://sigchi.org), in the CHI proceedings format. 
The content in this example is adapted and adjusted from content in the **sample-sigchi.tex** template included with the ACM template, to illustrate how to create the same content through the R Markdown workflow as well as to showcase additional features enabled by R Markdown.


# Paper meta data
Set meta data (copyright, authors, keywords, title, keywords, optional teaser figure, etc.) in the YAML header of the .Rmd file in which you write the manuscript.
This is done in the form of `key: value` pairs, e.g. `title: Writing CHI Proceedings Papers With R Markdown`. 
When compiling to a PDF (in RStudio, just click the 'Knit' button), the information in the YAML header is plugged into the CHI Extended Abstracts LaTeX template. (If you were to take a look at this template file inside of the rticles package, you would see e.g. `\title[$short-title$]{$title$}` where stuff between dollar signs is interpreted as a variable to be searched for in the YAML header and plugged into the template when generating a PDF).

**Note the sole exception for adding paper meta data**:
The CCS Concepts are messy to insert from the YAML header, so you should manually insert this into the **ccsxml.tex** file from which it will be included into your manuscript.

# The Body of The Paper
Typically, the body of a paper has a hierarchical structure, with numbered or unnumbered headings for sections, subsections, sub-subsections, and paragraphs. 
Whereas in LaTeX you use the command `\section` for main sections, in R Markdown you simply use `#`, as in `# The Body of The Paper`. For subsections, or sub-subsections, use additional hashes, as in `## This Become a Subsection`, and `#### This Becomes a Paragraph Heading`.^[By the way, this is how to insert footnotes.] 

If you want some section to be unnumbered in the output, add `{-}` after the section name, as in `# Unnumbered Section{-}`.

Indicate the start of a new paragraph with a blank line in your input file; that is why this sentence forms a separate paragraph.
This line, however, does not form a separate paragraph.

## Type Changes and *Special* Characters
Make words or phrases *italicized* by surrounding them with a single \*; **embolden** them by surrounding them with \*\***two**\*\*. `Typewriter-style` (for instance, for computer code) you create by surrounding text with `` `backticks` ``.^[Another footnote here. Let's make this a rather long one to see how it looks.]

## Citations
Citations to articles [@bowman:reasoning; @braams:babel; @Cohen07], conference proceedings [@clark:pct] or maybe books [@lamport:latex; @salas:calculus] listed in the Bibliography section of your article will occur throughout the text of your article. To insert a reference in the R Markdown syntax, type \@ followed by the citation key. 
The key is a short reference uniquely identifying each entry in in the `.bib` file for your article, in which your references are listed in [BibTex](http://www.bibtex.org) format.

For example, to cite the article "Deciding equivalances among conjunctive aggregate queries" from our `.bib` file, write `[@Cohen07]`. If you drop the `[]`'s, you get author names, as well as the citation: @Cohen07. 
See [this short guide for more](https://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html).

# Dynamic reporting
One of the most important benefits of writing in R Markdown (aside from being able to compile to other formats than PDF, such as HTML or even Microsoft Word), is the ability to insert results dynamically into your manuscript using code chunks or inline code. 
This means that you can do analyses **directly** in your manuscript or, probably better, read file(s) with data, summaries, or results directly into your manuscript and refer to them dynamically.

This is important for two (related) reasons:
1. You avoid initial manual transfer of results from statistical software to manuscript, which reduces the risk of error.
2. If at a later stage you update the analysis files, the results reported in your manuscript are automatically also updated - this again reduces the risk of mistakes, because you don't need to manually update figures and tables.

In R Markdown syntax, **code chunks** have the following form (cf. [_R Markdown: The Definitive Guide_](https://bookdown.org/yihui/rmarkdown/r-code.html)):

````r
`r ''````{coding_language chunk-label, chunk_options}
# your code goes here
```
````

**Inline code** has the form `` `coding_language #code here` ``.

## Setup chunks and figure descriptions
The first chunk in an R Markdown document is usually used to load packages and set default chunk options, for example like so (we normally add the chunk option `include=FALSE` to not include output from this chunk in the manuscript; here we just add `message=FALSE` to suppress the message that the tidyverse package has been loaded):

```{r setup, message=FALSE}
library(tidyverse)
knitr::opts_chunk$set(echo = FALSE, 
  message = FALSE, warning = FALSE)
# these options will exclude code output, 
# messages, or warnings in knitted manuscript
```

In addition, the ACM Master template adds the ability to provide descriptions of figures via the latex command `\Description{my description}`. 
To be able to add these descriptions easily, as well as an option to position chunks vertically, include this code in your initial setup chunk:

```r
# create additional chunk options
hook_chunk = knit_hooks$get('chunk')
knit_hooks$set(chunk = function(x, options) {
  txt = hook_chunk(x, options)
  # add chunk option 'vspaceout' which positions 
  # chunks vertically with \vspace
  if (!is.null(options$vspaceout)) {
    latex_vspace <- paste0("\\1\\\\vspace\\{", 
                      options$vspaceout, "\\}")
    txt <- sub('(\\\\begin[^}]+})', 
                      latex_vspace, txt)  
  }
  # add chunk option 'description' which adds 
  # \Description{...} to figures
  if (!is.null(options$description)) {
    latex_include <- paste0("\\1\\\\Description\\{", 
                      options$description, "\\}")
    gsub('(\\\\includegraphics[^}]+})', 
                      latex_include, txt) 
  } else {
    return(txt)  # pass to default hook
  }
})
```

You can then add descriptions to your figures by setting `description="my description"` as a chunk option to images and plots as you will see below.

## Inline results
You might read in a made-up data set of goals scored by basketball players like so:

```{r, echo=TRUE}
data <- read_csv("data/fakeBasketData.csv")
```

We can use inline code to dynamically report properties of this data set. For example, "there are a total of `r nrow(data)` observations of goals scored. The mean number of goals made by any player in a given game is: `r mean(data$goals)`".

## Tables
For tables, you could use LaTeX syntax directly. This might be useful if your table itself contains LaTeX syntax, as in Table \@ref(tab:freq).

\begin{table}
  \caption{Frequency of Special Characters}
  \label{tab:freq}
  \begin{tabular}{ccl}
    \toprule
    Non-English or Math&Frequency&Comments\\
    \midrule
    \O & 1 in 1,000& For Swedish names\\
    $\pi$ & 1 in 5& Common in math\\
    \$ & 4 in 5 & Used in business\\
    $\Psi^2_1$ & 1 in 40,000& Unexplained usage\\
  \bottomrule
\end{tabular}
\end{table}

However, the power of writing in R Markdown is that you can read in data and automatically create corresponding LaTeX tables. The easiest way is probably to use the [`kable` function](https://rdrr.io/cran/knitr/man/kable.html). For example, Table \@ref(tab:basket-data) shows the first 5 rows in our basket data set.

```{r basket-data}
data %>%
    head(5) %>%
    knitr::kable(booktabs = TRUE, caption = "The first 5 rows of some made-up basket data.")
```

You can reference Table \@ref(tab:basket-data) with `\@ref(tab:basket-data)`.

You can also do arbitrary transformations and analyses of the data before creating a table, as in Table \@ref(tab:basket-summary).

```{r basket-summary}
data %>%
  group_by(Player) %>%
  summarise(`Total goals scored` = sum(goals)) %>%
  knitr::kable(booktabs = TRUE, caption = "Summary statistics of goals scored by top players in made-up basketball season.")
```

When using a two-column format you can create a wider table, which takes up the whole width of the page's live area, by adding the parameter `table.env = 'table*'` to the `kable` function, like in Table \@ref(tab:basket-summary-wide).
In the LaTeX output, this puts the table in a `\table*` environment.

```{r basket-summary-wide}
data %>%
  group_by(Player) %>%
  summarise(`Total goals scored` = sum(goals),
             `Goals per game` = `Total goals scored` / n()) %>%
  knitr::kable(booktabs = TRUE, caption = "Bigger display of more summary statistics of goals scored by top players in made-up basketball season.", table.env = 'table*') #note table.env = 'table*'
  
```

## Figures
### Static figures
Figures are similarly included via code chunks. You can include arbitrary image files, as in Figure \@ref(fig:static-image). 

```{r static-image, fig.cap="Here's a little pretty fly.", description="my description"}
knitr::include_graphics("figures/fly.png")
```

If you don't give it a caption in the chunk options (with something like `fig.cap="My caption"`), the figure does not float:

```{r static-image-non-float"}
knitr::include_graphics("figures/fly.png")
```

You can resize the figures with the chunk options `out.height` and `out.width`, as in Figure \@ref(fig:static-image-resized). 
If you only care about LaTeX output, you can resize e.g. in inches or relative to the column width (`out.height = '1in'` or `out.height = '0.50\\columnwidth'`), but if you want to get maximum value out of R Markdown and be able to output also to html formats, set it with a percentage (`out.height = '50%'` - when outputting to PDF via LaTeX, this will be translated into `out.height = '.5\linewidth'`, see the [bookdown reference](https://bookdown.org/yihui/bookdown/figures.html)).

(ref:static-image-resized) A sample black and white graphic that has been resized with the `out.height` and `out.width` chunk options.

```{r static-image-resized, fig.cap='(ref:static-image-resized)', out.height='15%', out.width='25%'}
knitr::include_graphics("figures/fly.png")
```

If you need to style text in a caption, or include references in the caption, you have two options (see [bookdown on 'text references'](https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html#text-references)):

1. set the caption with the chunk option `fig.cap` and use LaTeX rather than markdown syntax. As the figure caption is a string, you must escape the LaTeX syntax's `\` with another `\`. The caption for Figure \@ref(fig:static-image-resized) would then have been written like this: `fig.cap="A sample black and white graphic that has been resized with the \\texttt{out.height} and \\texttt{out.width} chunk options."`.

2. write the caption in the body text with the syntax `(ref:chunk_label) My caption here.` and then refer to it in the chunk options with `fig.cap='(ref:chunk_label)` as we did for the resized fly caption.

### Dynamic figures
Again, the power of R Markdown is that you can include e.g. plots that are dynamically generated from the underlying data. For example, Figure \@ref(fig:basket-plot) is a simple visualisation of the basket data.

```{r basket-plot, out.width='98%', fig.cap="Total number of goals by the top 3 players in made-up basketball season"}
data %>%
  group_by(Player) %>%
  summarise(total_goals = sum(goals)) %>%
  arrange(desc(total_goals)) %>%
  head(3) %>%
  ggplot() +
    geom_bar(aes(x = Player, y = total_goals), stat = "identity") +
    labs(x = "", y = "Total goals") + 
    theme_minimal()
```

As with tables, you may want a figure to span two columns. To do this, set the environment to `figure*` with the chunk option `fig.env = 'figure*'`. You can fiddle around with the size and aspect ratio of the generated plot with the chunk options `fig.height` and `fig.width`. If your image is very large, you may want to restrict its width with `out.width`.

```{r basket-plot-wide, fig.cap="Distribution of goals scored by game for players in made-up basketball season", fig.env = 'figure*', fig.height=4}
data %>%
  ggplot() +
    geom_boxplot(aes(y = goals, x = Player)) +
    geom_point(aes(y = goals, x = Player), position = "jitter") +
    coord_flip() +
    labs(x = "", y = "Goals in game") +
    theme_minimal()
```

## Math Equations
You may want to display math equations in three distinct styles: inline, numbered or non-numbered display. 
Each of the three are discussed in the next sections. You can use usual LaTeX syntax directly, or [R Markdown](https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html#theorems).

### Inline (In-text) Equations
A formula that appears in the running text is called an inline or in-text formula. 
In LaTeX it is produced by the **math** environment, which can be invoked by surrounding text with dollar signs: $. 
You can use any of the symbols and structures, from $\alpha$ to $\omega$, available in LaTeX. 
For example, here's a nice equation inline: $\lim_{n\rightarrow \infty}x=0$. If you're writing in RStudio, you can even hover over it to see the rendered output displayed!

### Display Equations
A numbered display equation---one set off by vertical space from the text and centered horizontally---is produced by using LaTeX syntax directly to put the content in an `equation` environment^[In fact, you can use any arbitrary LaTeX syntax directly in your .Rmd document.]. 
So here's that nice equation from above:
\begin{equation}
\lim_{n\rightarrow \infty}x=0
(\#eq:display-equation)
\end{equation}

They can be assigned labels with the syntax `(\#eq:label)`. Refer to the equation with `\@ref(eq:display-equation)`, e.g. see Equation \@ref(eq:display-equation).

To make an unnumbered display equation, surround the expression with two dollar signs:
$$
\lim_{n\rightarrow \infty}x=0
$$

## Theorem-like Constructs
To create theorems, use this syntax (echo=TRUE is only necessary if you've set echo=FALSE as the default):

````markdown
`r ''````{theorem, echo=TRUE}
Here is my theorem.
```
````

For example:

```{theorem, echo=TRUE}
Let $f$ be continuous on $[a,b]$.  If $G$ is an antiderivative for $f$ on $[a,b]$, then
$$\int^b_af(t)\,dt = G(b) - G(a).$$
```

Similarly for definitions, use the syntax
````markdown
`r ''````{definition}
Here is my theorem.
```
````

For example:

```{definition, echo=TRUE}
If $z$ is irrational, then by $e^z$ we mean the unique number that has logarithm $z$:
$$\log e^z = z.$$
```

In the ACM LaTeX template, pre-defined theorem-like constructs are **theorem**, **conjecture**, **proposition**, **lemma** and **corollary**. The pre-defined definition-like constructs are **example** and **definition**.

Unsurprisingly, for proofs use
````markdown
`r ''````{proof}
Here is my theorem.
```
````

For example:

```{proof, echo=TRUE}
Suppose on the contrary there exists a real number $L$ such that
$$\lim_{x\rightarrow\infty} \frac{f(x)}{g(x)} = L.$$
Then
$$
    l=\lim_{x\rightarrow c} f(x)
    = \lim_{x\rightarrow c}
    \left[ g{x} \cdot \frac{f(x)}{g(x)} \right ]
    = \lim_{x\rightarrow c} g(x) \cdot \lim_{x\rightarrow c}
    \frac{f(x)}{g(x)} = 0\cdot L = 0,
$$
  which contradicts our assumption that $l\neq 0$.
```


# Conclusions
This paragraph ends the body of this sample document. Remember that you might still have Acknowledgments or Appendices; brief samples of these follow.  There is still the Bibliography to deal with; and we will make a disclaimer about that here: with the exception of the reference to the LaTeX book, the citations in this paper are to articles which have nothing to do with the present subject and are used as examples only.

# More Help for the Hardy
For acknowledgements, you may want to use the LaTeX syntax for this from the ACM template example, in which case you'll put acknowledgement text in between `\begin{acks}` and `\end{acks}`. Alternatively, just start an unnumbered heading `# Acknowledgements{-}` and write your text, like this:

# Acknowledgements {-}
There's a lot of people to thank here.

# (APPENDIX) Appendix {-} 
# Headings in Appendices
The rules about hierarchical headings discussed above for the body of the article are different in the appendices. 
You begin the **appendix** section with the special header `# (APPENDIX) Appendix {-}`. 
Then, any subsequent top level headers (`#`) indicates the start of each Appendix, with alphabetic order designation (i.e., the first is A, the second B, etc.).  
So, if you need hierarchical structure *within* an Appendix, start with **subsection** (`##`) as the highest level.

## Research Methods
### Part One
Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
Morbi malesuada, quam in pulvinar varius, metus nunc fermentum urna, id sollicitudin purus odio sit amet enim. 
Aliquam ullamcorper eu ipsum vel mollis. 
Curabitur quis dictum nisl. 
Phasellus vel semper risus, et lacinia dolor. 
Integer ultricies commodo sem nec semper.

### Part Two
Etiam commodo feugiat nisl pulvinar pellentesque. 
Etiam auctor sodales ligula, non varius nibh pulvinar semper. 
Suspendisse nec lectus non ipsum convallis congue hendrerit vitae sapien. 
Donec at laoreet eros. 
Vivamus non purus placerat, scelerisque diam eu, cursus ante. 
Etiam aliquam tortor auctor efficitur mattis.

## Online Resources
Nam id fermentum dui. 
Suspendisse sagittis tortor a nulla mollis, in pulvinar ex pretium. 
Sed interdum orci quis metus euismod, et sagittis enim maximus. 
Vestibulum gravida massa ut felis suscipit congue. 
Quisque mattis elit a risus ultrices commodo venenatis eget dui. 
Etiam sagittis eleifend elementum.

Nam interdum magna at lectus dignissim, ac dignissim lorem rhoncus. 
Maecenas eu arcu ac neque placerat aliquam. 
Nunc pulvinar massa et mattis lacinia.