In mattwarkentin/CHL5202: CHL5202 - Biostatistics

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

R Markdown

As the name implies, R Markdown is the combination of two language. First, we have R a powerful language for statistics and data science. Markdown is a plain-text and easy-to-learn text formatting language. When we combine these two languages we get a powerful system for writing technical documents with nearly all of the normal formatting capabilities we expected from a word processing software (e.g. Microsoft Word) with the ability to include arbitrary amounts of R code. More importantly, when we render our document to a particular format, the R code is executed and the results are automatically embedded into the final document.

This vignette will provide a quick introduction to using Markdown. It is worth pointing out that there are different flavors of Markdown, some with more features than others. R Markdown uses pandoc-flavored Markdown which is a bit more full-featured. Don't worry, learning Markdown is relatively simple, and you will be up and running in no time.

An R Markdown document is broken down into two sections:

1. The YAML front-matter

2. The rest of the document

The start of every R Markdown document will begin with three hyphens, some meta-data about the document, and close with three hyphens, like this:

---
title: "My awesome title"
name: "Jane Doe"
output: pdf_document
---

This is called YAML front-matter. This is where you meta-data about the document. For the most part in this course you will just need to fill in the pre-populated fields in the YAML part of the document. YAML is very particular about spacing/indentation, so try not to change the spacing when entering your information.

For a more comprehensive coverage of all the powerful things you can do with R Markdown, check out the complete documentation: R Markdown: The Definitive Guide.

library(knitr)
library(rmarkdown)
library(dplyr)
library(ggplot2)

Using Pandoc's Markdown

Let's start with the some of the most basic types of text formatting. The way this section is organized is that each bullet point presents the syntax for achieving the formatting, and then shows what the result looks like.

• *italic* italic or _italic italic

• **bold** bold or __bold__ bold

• ***bold-italic*** bold-italic

• superscript^2^ superscript^2^

• subscript~2~ subscript~2~

• ~~strikethrough~~

This should get you started with providing some emphasis in your writing with some basic Markdown syntax.

Next, let's look at some other more intermediate text formatting syntax.

If you want to a horizontal rule to your page to you can use 3 or more hyphens, like so:

---

Becomes...

---

If we want to present text as a blockquote, we can use the > symbol, like so:

> roses are red, violets are blue

Becomes...

roses are red, violets are blue

If we want to create an unordered (i.e. unnumbered) list, you can start a line with either a * or -. For example:

* Item 1

* Item 2
    + Subitem

• Item 1

• Item 2

  • Subitem

For an ordered list, simply use numbers for top-level list items.

1. Ordered list

2. Ordered list
    + Subitem

1. Ordered list

2. Ordered list

   • Subitem

We may wish to provide hyperlinks in our document to external resources, like webpages. To do this, you can either include the full web path, or if you wish to hyperlink a specific word, you can wrap the keyword in square brackets and the link path in parentheses.

• http://google.com becomes http://google.com

• [Google](www.google.com) becomes Google

You may already be wondering how I am able to show you the Markdown syntax without it rendering to the proper format. To achieve this, we can wrap any text in back-ticks (usually found below the ESC key on a keyboard). These back-ticks indicate that the text should be translated verbatim, meaning they do not get executed.

There are two ways to display verbatim text, inline and in blocks. Wrapping text in single back-ticks let you display verbatim text right inside a sentence, like this. We could also display a stand-alone code block by wrapping text in 3 back-ticks.

Here is some sweet code

Later we will learn how to add code blocks that actually run the code!

R Code Chunks

The real power of R Markdown comes from being able to include executable R code into the document. You can include R code inline or in chunks.

x <- 10
print(x)

Notice that the output is included in the document automatically.

If you want to include R results in-line, you wrap in single back ticks like r ''r Sys.Date() ` becomesr Sys.Date()`.

Figures

Markdown syntax provides a native way to include external images into documents. However, I recommend using an R code chunk and the knitr package for better control over output.

knitr::include_graphics('Utoronto.png')

We can use chunk options for extra control. For example the code below will shrink the size and add a figure caption.

```r`r ''`
knitr::include_graphics('Utoronto.png')
```

knitr::include_graphics('Utoronto.png')

Of course, if your graphic is produced by running some R code, such as using plot() or ggplot(), the graphic is inserted automatically:

iris %>% 
  ggplot(aes(x = Sepal.Length)) +
  geom_histogram()

We can use chunk options to change the size, add a caption, or anything thing else we'd like. In later sections we will learn how to refer to figures in the text of our document.

Tables

There are many good packages in R to include tables in your PDF document. the kable function provided by the knitr package is the easiest implementation. You simply pass an R data frame to the function.

# Selecting the first 5 rows
# We use booktabs for better aesthetics
knitr::kable(iris[1:5,], 
             caption = 'This is my sweet table.', 
             booktabs = TRUE)

If we have our own data we want to include, we can build a table and feed it into kable:

data <- dplyr::tribble(
  ~Variable, ~Estimate, ~Pvalue,
  "Age (per year)", 1.23, 0.03,
  "Sex (female vs. male)", 4.52, 0.09
)

knitr::kable(data, 
             booktabs = TRUE, 
             caption = 'My custom table.')

With only a few simple options we can get a pretty good looking tables. In later sections we will learn how to refer to tables in the text of our document.

Document Sections

Next, we should discuss how we can break down our document into meaningful sections. In Markdown, these are called headers. Headers can be nested inside one another, create sub-sections among sections.

• To set a first-level header use # Header 1, which looks like:

Header 1

• To set a first-level header use ## Header 2, which looks like:

Header 2

• To set a first-level header use ### Header 3, which looks like:

Header 3

The headers in this document are unnumbered, but to get numbered headings you just need to change a setting in the YAML front-matter. This is done by default for your assignment submissions.

Lastly, we can assign labels to our sections so that we can reference them in the text, we will see how to do this in a later section. For now, let's just create a section and label it so we can refer to it later.

# Important Section {#impsec}

Important Section {#impsec}

Math Equations

Since this is a statistics course, we may wish to include complex mathematical equations in our work. Similar to including verbatim code, we can do inline or displayed equations. For math equations, we wrap the \LaTeX code in $ or $$ for inline and display equations, respectively.

Here is an example of an inline equation: $y = mx+b$ becomes $y = mx+b$

Or we could display an equation block:

$$x + y$$

Becomes...

$$x + y$$

For those with more experience with \LaTeX, you can include full math environments by wrapping them in $$.

$$ X = \begin{bmatrix}1 & x_{1}\ 1 & x_{2}\ 1 & x_{3} \end{bmatrix} $$

We can also number our equations so that we may reference to them specifically in the text. We will see this in a later section.

Citations and Cross-Referencing

For academic and technical writing, we need to be able to include citations, footnotes, and cross-referencing for tables, figures, and equations. The great part of using R Markdown is we can use some simple syntax to indicate where we can citations/cross-references, and the software does it all for us.

That means, for example, if we moved figures around inside the document, they are re-numbered automatically and all reference to those figures are updated. This can make your life A LOT easier.

Citations

In order to take advantage of the automatic citation management, we must have a BibTeX file (with the extension .bib) somewhere on our computer which contains our references. Most reference manager software can export a .bib file. Also, when searching for papers on Google Scholar, you can click the cartoon quotation mark below the entry and then select BibTeX to get a pre-formatted BibTeX entry. You can copy-and-paste this directly into your references file.

To actually cite a paper, we simply need to play an @ symbol before the keyword for the specific reference. For example, if we wanted to reference the rmarkdown software and book, here are the relevant BibTeX entries:

@Manual{R-rmarkdown,
  title = {rmarkdown: Dynamic Documents for R},
  author = {JJ Allaire and Yihui Xie and Jonathan McPherson and Javier Luraschi and Kevin Ushey and Aron Atkins and Hadley Wickham and Joe Cheng and Winston Chang and Richard Iannone},
  year = {2019},
  note = {R package version 2.0},
  url = {https://CRAN.R-project.org/package=rmarkdown},
}

@Book{rmarkdown2018,
  title = {R Markdown: The Definitive Guide},
  author = {Yihui Xie and J.J. Allaire and Garrett Grolemund},
  publisher = {Chapman and Hall/CRC},
  address = {Boca Raton, Florida},
  year = {2018},
  note = {ISBN 9781138359338},
  url = {https://bookdown.org/yihui/rmarkdown},
}

If we have this saved in a file, we could cite this entry with @R-rmarkdown or to place it in parentheses, [@R-rmarkdown]. This won't work for this example document, but it will work auto-magically for your assignment.

If you want to cite multiple references you can simply separate them by ; inside the square brackets, like this [@R-rmarkdown; @rmarkdown2018].

Footnotes

We can also include footnotes, which automatically get formatted and placed at the bottom of the page. To insert a footnote, you use the following syntax somewhere in your document:

^[This is an important footnote.]

Becomes...

^[This is an important footnote.]

Tables and Figures

We can refer to tables and figures in our writing by using the \@ref(type:label) syntax. The label is generated automatically if you name the R code chunk.

See Figure \@ref(fig:iris-plot) \@ref(fig:iris-plot).

```r`r ''`
plot(iris)
```

plot(iris)

And see Table \@ref(tab:mtcars) \@ref(tab:mtcars).

```r`r ''`
knitr::kable(mtcars[1:5, 1:5], caption = "The mtcars data.")
```

knitr::kable(mtcars[1:5, 1:5], caption = "The mtcars data.")

Equations

We can also refer to numbered equations:

See Equation \@ref(eq:mean) \@ref(eq:mean).

\begin{equation}
\bar{X} = \frac{\sum_{i=1}^n X_i}{n} (\#eq:mean)
\end{equation}

\begin{equation} \bar{X} = \frac{\sum_{i=1}^n X_i}{n} (#eq:mean) \end{equation}

Sections

Previously we created a section called Important Section which had the label impsec. We can use the following syntax to refer to a section: Please see Section \@ref(impsec) \@ref(impsec) for more details.

References {-}

mattwarkentin/CHL5202 documentation built on March 1, 2020, 2:28 a.m.