1 YAML Frontmatter

The biginning section of R Markdown file enclosed with triple dashes is called YAML frontmatter. This section specifies how the file is rendered into the final output. The hardwork is done by pandoc (bundled with RStudio).

If the final output is PDF, then pandoc passes LaTeX source file (.tex) to a LaTeX engine (pdflatex, xelatex, or lualatex) and the latter produces a PDF.

In writing an academic paper, I would recommend to exploit extended functionalities achieved with bookdown package. See https://bookdown.org/yihui/bookdown/ for more information.

Here are several samples of frontmatters. (To use one of these, you might need to create empty file, custom_style_file.sty and bibliography_file.bib, in the same folder with your .Rmd file.)

Short paper

Here is a header for a simple article.

---
title: 'Title of the paper'
author: | 
  | Your name
  | Affiliation
date: '08 June, 2017'
output:
  bookdown::pdf_document2:
    fig_caption: yes
    includes:
      in_header: custom_style_file.sty
    keep_tex: no
    latex_engine: pdflatex
    template: null
    toc: no
documentclass: scrartcl
link-citations: yes
bibliography: bibliography_file.bib
biblio-style: apalike
---

Long report

Modify documentclass field to get a report with a title page.

---
title: 'Title of the report'
author: |
  | Your name
  | Affiliation
date: '08 June, 2017'
output:
  bookdown::pdf_document2:
    fig_caption: yes
    includes:
      in_header: custom_style_file.sty
    keep_tex: no
    latex_engine: pdflatex
    template: null
    toc: yes
documentclass: scrreprt
link-citations: yes
bibliography: bibliography_file.bib
biblio-style: apalike
---

HTML Output

HTML output might be handier for drafting.

---
title: 'Title of the page'
author: |
  | Your name
  | Affiliation
date: '08 June, 2017'
output:
  bookdown::html_document2: default
link-citations: yes
bibliography: bibliography_file.bib
biblio-style: apalike
---

Combination

YAML header accepts multiple entries in output field. If your final output is PDF article but you want to draft it with HTML, then your header might look like

title: 'Title of the paper'
author: | 
  | Your name
  | Affiliation
date: '08 June, 2017'
output:
  bookdown::html_document2: default
  bookdown::pdf_document2:
    fig_caption: yes
    includes:
      in_header: custom_style_file.sty
    keep_tex: no
    latex_engine: pdflatex
    template: null
    toc: no
documentclass: scrartcl
link-citations: yes
bibliography: bibliography_file.bib
biblio-style: apalike

Book

I would recommend to read about bookdown, which allows you to separate the source file into multiple files for easy composing. See https://bookdown.org/yihui/bookdown/

2 Sections

Use pound symbols (#) for sectioning.

# Section
## Subsection
### Subsubsection
# Section without section number {-}
## Subsection without subsection number {-}
### Subsubsection without subsubsection number {-}

Cross reference

You might want to refer the reader to another section within your document. To do this, use the following syntax.

\@ref(section-header)

For example, the heading for the first section in the present document is “YAML Frontmatter”. Make upper-case letters lower-case and replace a white space for a dash to get “yaml-frontmatter”. Section \@ref(yaml-frontmatter) is rendered to Section 1.

3 Code chunk

There are different reasons you might want to include R code in a document.

It’s a very common error to forget to update a graph or table after updating code. It is a good idea to automatically produce, embed and update graphs and/or tables diplayed in the final output.1

knitr package does this perfectly. The basic syntax for including code is the following:

```{r chunk-label}
plot(pressure)
```

The area surrounded by ```{r} and ``` is called, R code chunk. The text string immediately after r is “chunk label”. You can use this for cross-referencing.

There are many options (chunk options) to control how the output looks like.

3.1 Show code and output

```{r chunk-label-1}
plot(pressure)
```

displays code and the output graph.

plot(pressure)

3.2 Show output but not code

```{r chunk-label-2, echo=FALSE}
plot(pressure)
```

produces

3.3 Show code but not output

```{r chunk-label-3, eval=FALSE}
plot(pressure)
```

produces

plot(pressure)

Notice that this code chunk is only for show and thus not run.

Inline code

You might want to manipulate the text body by a code. For example, if you have done a regression analysis

model <- lm(pressure ~ temperature, pressure)
smmry <- summary(model)

you might want to include important figures in your document. Instead of writing the raw numbers many times, you can write `r smmry$coefficients[2, 1]` to include the coefficient, 1.5124199 for the regressor. To include, standard error, 0.315846, `r smmry$coefficients[2, 2]` can be used.

This might seem a lot more tedious than simply copying and pasting the figures. It is however beneficial in the long run.

4 Figures

You can place a picture that is not produced with code. This might be useful when you want to include a conceptual diagram. Use knitr::include_graphics() in a code block for this purpose.

```{r utility, out.width="300px", fig.cap="Reduced Utility"}
knitr::include_graphics("utility.jpeg")
```
knitr::include_graphics("utility.jpeg")
Reduced Utility

Figure 4.1: Reduced Utility

For cross-referencing, use this syntax: \@ref(fig:chunk-label). Notice the special tag “fig:” appended before the chunk label. Fig. \@ref(fig:utility) is rendered to Fig. 4.1.

5 Tables

The following code chunk produces Table 5.1.

```{r euro-cross}
knitr::kable(euro.cross, 
             caption = "Conversion rates between the various Euro currencies")
```

in the source code becomes

knitr::kable(euro.cross, 
             caption = "Conversion rates between the various Euro currencies")
Table 5.1: Conversion rates between the various Euro currencies
ATS BEF DEM ESP FIM FRF IEP ITL LUF NLG PTE
ATS 1.0000000 2.9316149 0.1421357 12.0917422 0.4320931 0.4767025 0.0572345 140.714229 2.9316149 0.1601499 14.5695951
BEF 0.3411089 1.0000000 0.0484838 4.1246012 0.1473908 0.1626075 0.0195232 47.998880 1.0000000 0.0546285 4.9698190
DEM 7.0355297 20.6254634 1.0000000 85.0718109 3.0400035 3.3538549 0.4026751 989.999131 20.6254634 1.1267390 102.5048189
ESP 0.0827011 0.2424477 0.0117548 1.0000000 0.0357346 0.0394238 0.0047334 11.637217 0.2424477 0.0132446 1.2049211
FIM 2.3143163 6.7846841 0.3289470 27.9841163 1.0000000 1.1032405 0.1324588 325.657236 6.7846841 0.3706374 33.7186519
FRF 2.0977442 6.1497781 0.2981644 25.3653822 0.9064207 1.0000000 0.1200634 295.182459 6.1497781 0.3359534 30.5632839
IEP 17.4719769 51.2211071 2.4833918 211.2666399 7.5495198 8.3289358 1.0000000 2458.555749 51.2211071 2.7981345 254.5596294
ITL 0.0071066 0.0208338 0.0010101 0.0859312 0.0030707 0.0033877 0.0004067 1.000000 0.0208338 0.0011381 0.1035403
LUF 0.3411089 1.0000000 0.0484838 4.1246012 0.1473908 0.1626075 0.0195232 47.998880 1.0000000 0.0546285 4.9698190
NLG 6.2441519 18.3054485 0.8875170 75.5026750 2.6980546 2.9766031 0.3573810 878.641019 18.3054485 1.0000000 90.9747653
PTE 0.0686361 0.2012146 0.0097556 0.8299299 0.0296572 0.0327190 0.0039284 9.658074 0.2012146 0.0109921 1.0000000

The syntax used for cross-referencing tables is \@ref(tab:chunk-label).

  1. Another technique to achieve this goal is to make use of “make”. I refere the interested readers to “minimal make” by Karl Broman, http://kbroman.org/minimal_make/↩