1 Introduction to R Markdown

R Markdown is an essential tool for reproducible research in biostatistics. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. This document will guide you through:

  • Creating professional statistical reports
  • Combining narrative text with analysis
  • Generating publication-ready tables and figures
  • Documenting your statistical methods
  • Ensuring reproducibility of your research

For more details, visit the R Markdown website

1.1 Getting Started

To work with R Markdown, if necessary:

  • Install R
  • Install the latest version of RStudio
  • Install the latest version of the knitr package: install.packages("knitr")

1.2 Document Structure

1.2.1 YAML Header

The YAML header (at the top between ---) configures your document. Key settings include:

  • Output format (HTML, PDF, Word)
  • Document styling
  • Table of contents options
  • Bibliography settings

1.2.2 Text Formatting

R Markdown supports various text formatting options:

  • Italics: Surround text with single asterisks *italic* or underscores _italic_
  • Bold: Use double asterisks **bold** or underscores __bold__
  • Code: Use backticks for inline code
  • Strikethrough: Use double tildes ~~strikethrough~~
  • Superscript2: ^2^
  • Subscript2: ~2~

1.2.3 Lists

Unordered lists use asterisks, plus, or minus signs:

  • Item 1
  • Item 2
    • Sub-item 2.1
    • Sub-item 2.2

Ordered lists use numbers:

  1. First item
  2. Second item
    1. Sub-item 2.1
    2. Sub-item 2.2

2 Code Chunks and Options

The following document is mainly based on https://bookdown.org/yihui/rmarkdown/r-code.html.

2.1 Basic Code Chunk Structure

You can insert R code chunks using:

  • RStudio toolbar (the Insert button)
  • Keyboard shortcut: Ctrl + Alt + I (Cmd + Option + I on macOS)

2.2 Important Chunk Options

There are many chunk options in knitr documented at https://yihui.name/knitr/options. Here are some important ones:

  • eval: Controls whether to execute the code chunk

  • echo: Shows/hides source code (some may prefer to see only the results and not the source code)

  • results: Controls output display:

    • Set to 'hide' to hide text output.
    • Set to 'asis' to write text output "as-is". e.g., you can write raw Markdown text from R code (like cat('*Markdown** is cool.\n')). By default, text output will be wrapped in verbatim elements.

  • collapse: Controls whether text output and source code are merged into a single code block in the output. This is mostly cosmetic: collapse = TRUE makes the output more compact by displaying R source code and its text output in a single block. The default collapse = FALSE separates R expressions and their text output into different blocks.

  • warning, message, and error: Control display of warnings/messages/errors

  • include: Controls chunk inclusion in output. When include = FALSE, the entire code chunk is excluded from the output, but will still be evaluated if eval = TRUE. When you want to set echo = FALSE, results = 'hide', warning = FALSE, and message = FALSE, you might simply use the single option include = FALSE.

  • Figure dimensions: Use fig.width, fig.height

When you click the Knit button, a document will be generated that includes both content and the output of any embedded R code chunks within the document.

You can produce various outputs in a code chunk: text output, tables, or graphics. You have fine control over all these outputs via chunk options, which can be provided inside the curly braces (between ```{r} and }).

The value of a chunk option can be any valid R expression, which makes chunk options extremely flexible. For example, the eval option controls whether to evaluate (execute) a code chunk, and you can conditionally evaluate a chunk using a previously defined variable.

3 Practical Examples

# Execute code if the date is later than a specified day
do_it = Sys.Date() > '2018-02-14'
# Generate random normal data and create histogram
x = rnorm(10000)
x[1:5]  # Display first 5 values
## [1] -0.56047565 -0.23017749  1.55870831  0.07050839  0.12928774
hist(x, breaks = 55, main = "Distribution of Random Normal Data")

Besides code chunks, you can also insert values of R objects inline in text. For example:

For a circle with the radius r x, its area is r round(pi * x^2, 2).

4 Writing LaTeX

You can write LaTeX code easily. For example: \(y_{i} = \mathbf{x}_{i}^{\top}\mathbf{\beta} + \epsilon_{i}\), \(\epsilon_{i} \sim N(0, \sigma^{2})\).

\(\left(\int_{a}^{b} f(x) \; dx\right)\), \(\displaystyle\sum_{x = a}^{b} f(x)\), \(\displaystyle\prod_{x = a}^{b} f(x)\), \(\log(x)\), \(\exp(x)\)

Greek letters: \(\epsilon \varepsilon E\)

To write an equation:

\[ \sum_{n = 1}^{10} n^2 \]

5 Citations and References

5.1 Adding Citations

To effectively cite references, start by creating a reference file named references.bib. Here’s how to format your citations:

5.1.1 Basic Citations

  • Single inline citation: @smith2020example
  • Parenthetical citation: [@smith2020example]
  • Multiple citations: [@smith2020example; @brown2021manual]
  • With page numbers: [@smith2020example, pp. 33-35]
  • Author in text: @smith2020example argues that...

5.2 Managing Citations

5.2.1 Tools for Bibliography Management

Consider using the following tools to manage your bibliography: * Zotero with Better BibTeX extension * JabRef * Mendeley * EndNote