In WdeNooy/UsingRTutorials: Provides learnr Tutorials for a Using R Course

# Ensure that libraries are loaded.
library(tidyverse)
library(learnr)
library(gradethis)
library(knitr)
library(kableExtra)
library(RColorBrewer)

tutorial_options(exercise.timelimit = 20, exercise.checker = gradethis::grade_learnr)
knitr::opts_chunk$set(echo = FALSE, warning = FALSE, message = FALSE)

# Note: A (new) R Markdown document can be knitted while a learnr tutorial is
# running both if the tutorial is started from the console and from the Tutorial tab.

# Ensure that the data is loaded for the remainder of this tutorial.
glbwarm <- UsingRTutorials::glbwarm

Overview

Course Content

• Report Layout.
• Polishing Your Graphics.
• Finalizing the Group Project.

Report Layout With R Markdown

Let us explore the main features and options of R Markdown step by step.

- In RStudio, open a new R Markdown document and have a look at _Output Options..._ in the settings menu (see below image).

knitr::include_graphics("images/OutputOptions.png")

YAML

In this menu you can change several features including:

• Table of contents.
• Section numbering.
• Figure width and height.
• Adding figure captions.

Change the options. - How does the YAML (first part of the R Markdown document) change? - How does the knitted document change?

__Tip__ - Knit a document to HTML and check it before you knit to PDF or Word. HTML knitting is much faster.

Many more YAML options can be set manually:

• See the R Markdown Cheat Sheet (page 2).

- Change the YAML of the R Markdown document such that a floating table of contents is shown if the document is knitted to HTML.

__Programming Tip__ - Mind the indentation and use of `:` in the YAML; R Markdown is very strict here. Use menu _Output Options..._ whenever possible because it structures the YAML correctly.

Visual editor

knitr::include_graphics("images/VisualEditor.png")

Use the visual editor for easy:

• Text formatting.
• Table and figure insertion.
• Table formatting.
• Insertion of footnotes.
• Insertion of references.

References

To include literature references in an R Markdown document, you need four things:

1. A bibliography file containing the referenced literature, preferably in BibTex format: references.bib.
2. A line in the YAML specifying the bibliography file(s) to use, for example, bibliography: references.bib.
3. A line in the YAML specifying the format to be used for the references, for example, csl: apa.csl.
4. A citation key in the text where you want to insert the reference, for example, "As argued by [@McQuail2005], Communication Science deals with ...".

knitr::include_graphics("images/InsertCitation.png")

Adding a reference within the visual editor:

• Put the cursor where you want the reference.
• Select Citation from the Insert menu.
  1. Select your reference software (if any) to select a reference.
  2. Or select the R packages that you are using, to acknowledge the work of the authors.
  3. The default file name of the references file is references.bib.
  4. Insert the selected references in the R Markdown document.

RStudio then:

1. Inserts the reference in the document.
2. Creates or expands the file references.bib.
3. Adds this file to the YAML, so a list of references is created when you knit the document.

- Add a footnote on the first page to cite the following R packages: `base`, `tidyverse`, `knitr`, and `kableExtra`.

To get the literature references in APA style, we need a citation style file.

- Download the file with the APA journal citation style `apa.csl` from [https://www.zotero.org/styles](https://www.zotero.org/styles). - Save it in your working directory. - Reference the APA journal citation style `apa.csl` in the YAML of the R Markdown file. Add the line: `csl: apa.csl` - Knit the document to HTML and inspect the references. All okay?

Figure code chunk options

Figures usually demand additional attention:

• not too small and not too large,
• have a caption,
• are shown in the right place.

Output Options... sets for all figures:

• Whether they have captions. Note that figure captions are numbered automatically only in PDF output.
• Default width.

Adjust a single figure with code chunk options (R Markdown Cheat Sheet, p. 1, bottom):

• fig.cap = figure caption as string.
• fig.align = 'left', 'right', or 'center'.
• out.width = width of figure in output in percentage of line width ("80%") or as a fixed width in pixels for HTML ("300px") or inches, centimeters for PDF and Word ("4.5in", "6cm").
• fig.asp = ratio of height to width.

Don't use:

• fig.width and fig.height: specify the actual size (whatever that may be) of the figure instead of the output size.

Note:

• If the size of a figure in the document is too small, knitr may end with the error message that the margins are too large.

- Reduce the size of the figure in the R Markdown file to 50 percent (half the line width), make it square, and add the caption "Pressure at different temperature levels."

Custom tables

Table menu in visual editor:

• Helps including a table that you type from scratch.
• Only use for a diagram.
• Never use for R results!

Present summary results as a table with knitr::kable() in a code chunk.

- Make sense of the below pipe (add comments).

glbwarm %>% 
  group_by(sex) %>% 
  summarise(sex_mean = round(mean(govact), digits=2), 
            sex_sd = round(sd(govact), digits=2)) %>%
  kable(col.names = c("Sex", "Average Score", "Standard Deviation"),
        caption = "Table: Support for government intervention across the sexes.")

For additional table layout options:

• Package kableExtra::
• Documentation: kableExtra vignette.

Cross-references with bookdown::

Figures are not automatically numbered in HTML or Word output.

To accomplish this, you need the bookdown:: package.

Follow these steps:

1. Install and load the bookdown package from CRAN.
2. In the YAML below date:, add the line site: "bookdown::bookdown_site".
3. Under output: in YAML replace:
   • html_document by bookdown::html_document2,
   • pdf_document by bookdown::pdf_document2, and
   • word_document by bookdown::word_document2.
4. In the text, use the following code to refer to a
   • section: \@ref(<section ID>) - Create Section ID: {#label}.
   • table: \@ref(tab:<chunk ID>) - Chunk ID: chunk name.
   • figure: \@ref(fig:<chunk ID>) - Chunk ID: chunk name.
5. Knit the document to html_document2, pdf_document2, or word_document2.

- Add a section label to the __R Markdown__ Section in the R Markdown file and use it to refer to this section in a sentence "As we have seen in Section 0.1, we can show statistical results in an R Markdown document." that you add to the __Including Plots__ Section. - Add a sentence with a reference to the pressure plot: "Figure 1 is beautiful, isn't it?"

__Programming Tip__ - Don't use blanks in Section ID labels or names of code chunks that create a table or figure.

Knitting Problems

Problems with knitting to HTML:

• Probably errors in your code (also applies to Word and PDF).
• Spot and fix them.
• Use code chunk option eval=FALSE to see if a code chunk causes the problem.

Problems with knitting to Word:

• Functions for tables and figures may not work for Word.
• Knit to HTML and import HTML in Word.

Problems with knitting to PDF:

• Characters like %, \, / have special meaning in LaTeX, which is the language used to create the PDF.
• Ensure that variable names or captions do not include them.

Polishing Your Graphics

Labels and legend position

Setting plot labels:

• labs() layer: basic adjustments.
• theme() layer: fine tuning of all details, including the legend. Note: features of graphical elements are specified with functions (with their own help page):
• element_text(), e.g., theme(plot.title = element_text(size = 10))
• element_rect(), e.g., theme(plot.background = element_rect(fill = "green"))
• element_line(), e.g., theme(axis.line = element_line(linewidth = 3, colour = "grey80"))

ggplot(data = glbwarm, mapping = 
    aes(x = age, y = govact, 
        color = partyid)) +
  geom_jitter() +
  labs(title = "Support for intervention by age", 
    x = "Age", y = "Support for government intervention",
    color = "Party identification"
    ) +
  theme(legend.position = "bottom")

- Create the above plot using tibble `glbwarm`, which is available in this tutorial. Pay special attention to the labels and legend position.

__Hint:__ Remember that the answer checker checks the presence of all layers before it checks the contents of the layers, so first add all layers if you want to use the automatic feedback for building the plot. __Hint:__ Check out help on function `theme()` to find the argument that sets the position of the legend.

ggplot(data = glbwarm, mapping = aes(x = age, y = govact, color = partyid)) + geom_jitter() + labs(title = "Support for intervention by age", x = "Age", y = "Support for government intervention", color = "Party identification") + theme(legend.position = "bottom")

gradethis::grade_code(
  correct = "", 
  incorrect = "You may have the layers in a different order, e.g., first theme() and then labs(). That is OK."
  )

Themes

Some plot characteristics are combined into theme types, e.g.:

• theme_bw(),
• theme_classic(),
• theme_dark(),
• theme_void(),
• theme_minimal().

You can set some overall plot characteristics within these theme layers, e.g.:

• base_size (size of fonts used)
• base_family (font type used: "serif", "sans", or "mono").

- Experiment with `base_size` and `base_family` in the code below.

ggplot(data = glbwarm, mapping = 
    aes(x = age, y = govact, 
        color = partyid)) +
  geom_jitter() +
  labs(title = "Support for intervention by age", 
    x = "Age", y = "Support for government intervention", 
    color = "Party identification") +
  theme_classic(base_size = 14, base_family = "sans") +
  theme(legend.position = "bottom")

__Programming Tip__ - Use `theme()` after, not before a theme type (such as `theme_bw()`), otherwise the theme type overrides the `theme()` settings.

Argument base_size sets a base size for all texts displayed in a plot.

If you want to set the size of a particular type of text within the plot, for example, the text values displayed in the legend, you can do that within a theme() layer.

- Complete the code below to set the size of the legend title to 10 and the size of the legend entries to 8.

ggplot(data = glbwarm, mapping = 
    aes(x = age, y = govact, 
        color = partyid)) +
  geom_jitter() +
  labs(title = "Support for intervention by age", 
    x = "Age", y = "Support for government intervention", 
    color = "Party identification") +
  theme_classic(base_size = 14, base_family = "sans") +
  theme(legend.position = "bottom",
        legend.
        legend.
        )

# The arguments to change legend title or legend entries are among the ones
# starting with legend. ; makes sense, doesn't it?
?theme

# The arguments that address properties of the text, use function element_text(). Check out help on this function.
?element_text

ggplot(data = glbwarm, mapping = aes(x = age, y = govact, color = partyid)) + geom_jitter() + labs(title = "Support for intervention by age", x = "Age", y = "Support for government intervention", color = "Party identification") + theme_classic(base_size = 14, base_family = "sans") + theme(legend.position = "bottom", legend.title = element_text(size = 10), legend.text = element_text(size = 8))

gradethis::grade_code(
  correct = "", 
  incorrect = ""
  )

Custom colors

For marking groups by colors , ggplot() uses a vector of colors, assigning the first group to the first color, and so on.

Custom colors:

• Create a vector of colors that matches (number and order) the groups in your plot.
• RColorBrewer offers nice color palettes (book, p. 458).
• Function brewer.pal in this package creates such a vector.

Democrats should be blue, Republicans red, and let us use green for Independents.

- Use the `scale_color_manual()` layer and the RColorBrewer `Accent` palette to assign the right colors to party identification in the plot.

ggplot(data = glbwarm, mapping = 
    aes(x = age, y = govact, 
        color = partyid)) +
  geom_jitter() +
  labs(
    title = "Support for intervention by age", 
    x = "Age", 
    y = "Support for government intervention",
    color = "Party identification"
    ) +
  theme_classic(base_size = 14, base_family = "sans") +
  theme(legend.position = "bottom") +
  scale_color_manual()

# Look up the Accent palette in the book or with the code below.
display.brewer.pal(8, name = "Accent")
# It has 8 colors ordered from green [1] to darkgrey [8].
# Which entries do you need from this vector?

# Extract the codes of the three desired colors from the palette.
brewer.pal(8, "Accent")[c( )]
# Note: 8 specifies the number of colors in this palette.

# The `values =` argument in scale_color_manual() assigns colors to groups.
scale_color_manual(values = brewer.pal(8, "Accent")[c(5, 1, 6)])

ggplot(data = glbwarm, mapping = aes(x = age, y = govact, color = partyid)) +
  geom_jitter() + labs(title = "Support for intervention by age", x = "Age", y = "Support for government intervention", color = "Party identification") + theme_classic(base_size = 14, base_family = "sans") + theme(legend.position = "bottom") + scale_color_manual(values = brewer.pal(8, "Accent")[c(5, 1, 6)])

gradethis::grade_code(
  correct = "", 
  incorrect = ""
  )

__Programming Tip__ - Discrete scales, for example, distinguishing between groups, are quite different from continuous scales. As a consequence, palettes for discrete scales do not work for continuous scales and the other way around.

Scales and ticks

Fine-tuning the ticks (value labels) on axes:

• Use layers scale_x_continuous() and scale_y_continuous(),
• to set the breaks, minor breaks, limits, and, if you like, axis label.

- Adjust the plot axes such that the vertical axis shows a grid line and label for each possible value of the original 7-point scale (1 to 7) and the horizontal axis shows labels and grid lines for decades (20, 30, 40, ..., 90) and only a grid line for each 2.5 years within a decade starting at 15 (15, 17.5, 22.5, 25, ..., 87.5).

ggplot(data = glbwarm, mapping = 
    aes(x = age, y = govact, color = partyid)) +
  geom_jitter() +
  theme_bw(base_size = 14) +
  theme(legend.position = "none") 

# Add the two layers.
ggplot(data = glbwarm, mapping = 
    aes(x = age, y = govact, color = partyid)) +
  geom_jitter() +
  theme_bw(base_size = 14) +
  theme(legend.position = "none") +
  scale_y_continuous() +
  scale_x_continuous()

# Use `breaks =` for labels with grid lines and `minor_breaks =` for grid lines only.
ggplot(data = glbwarm, mapping = 
    aes(x = age, y = govact, color = partyid)) +
  geom_jitter() +
  theme_bw(base_size = 14) +
  theme(legend.position = "none") +
  scale_y_continuous(breaks = , minor_breaks = ) +
  scale_x_continuous(breaks = , minor_breaks = )

# Use an efficient way to get sequences of numbers for the axis values.
1:7
seq(from = 20, to = 90, by = 10)

# And don't forget to switch off minor breaks on the Y axis.
minor_breaks = NULL

ggplot(data = glbwarm, mapping = aes(x = age, y = govact, color = partyid)) + geom_jitter() + theme_bw(base_size = 14) + theme(legend.position = "none") + scale_y_continuous(breaks = 1:7, minor_breaks = NULL) + scale_x_continuous(breaks =  seq(from = 20, to = 90, by = 10), minor_breaks = seq(from = 15, to = 87.5, by = 2.5))

gradethis::grade_code(
  correct = "", 
  incorrect = "Perhaps, you added the scale layers in a different order or in a different place. That is OK if you see the required axis values and grey lines."
  )

Manual additions

Use graphical primitives and geom_label() or geom_text() to touch up a graphic.

There are two ways of manually positioning graphical primitives within a plot

• If the axes are numerical, use axis values as coordinates.
• Otherwise, use a number between 0 and 1 as relative position.

ggplot(data = glbwarm, mapping = 
    aes(x = age, y = govact, 
        color = partyid)) +
  scale_color_manual(values = 
    brewer.pal(8, "Accent")[c(5, 1, 6)]) +
  geom_jitter() +
  geom_text(x = 90, y = 4, 
    label = "Source: Global warming data set by Eric Nisbeth.
    Author: Yah Tutor.",
    angle = 90, size = 2.5,
    color = "black") +
  scale_x_continuous(limits = c(15, 90)) + 
  theme_classic(base_size = 11) +
  theme(legend.position = "bottom")

- Use a text geom to add the source ("Source: Global warming data set by Eric Nisbeth.") and author ("Author: Yah Tutor.") to the plot as shown in the above figure.

ggplot(data = glbwarm, mapping = 
    aes(x = age, y = govact, 
        color = partyid)) +
  scale_color_manual(values = 
    brewer.pal(8, "Accent")[c(5, 1, 6)]) +
  geom_jitter() +
  geom_text( ) +
  scale_x_continuous(limits = c(15, 90)) + #ensures that the text fits within the plot
  theme_classic(base_size = 11) +
  theme(legend.position = "bottom")

# Check out section Aesthetics in the help on geom_text() to find the
# arguments that you need.

# You are supposed to provide the coordinates manually in the ggplot code
# (instead of calculating it from the data set.)
# For this reason, do not put the coordinates within an aes() function.

# Divide the label over two lines in your code to get the source and author on
# different lines.
label = "Source: Global warming data set by Eric Nisbeth.
    Author: Yah Tutor."

ggplot(data = glbwarm, mapping = aes(x = age, y = govact, color = partyid)) + scale_color_manual(values = brewer.pal(8, "Accent")[c(5, 1, 6)]) + geom_jitter() + geom_text(x = 90, y = 4, label = "Source: Global warming data set by Eric Nisbeth.
    Author: Yah Tutor.", angle = 90, size = 2.5, color = "black") + scale_x_continuous(limits = c(15, 90)) +  theme_classic(base_size = 11) + theme(legend.position = "bottom")

gradethis::grade_code(
  correct = "", 
  incorrect = ""
  )

Fancy Stuff

APA format article with papaja::

Instead of adapting a standard R Markdown document, you can use the papaja package, which contains an APA6 article template. Once you have installed this package, an APA article template is available if you create a new R Markdown file using the From Template option (see figure).

knitr::include_graphics("images/template.png")

If you didn't do so, install papaja. Run the command remotes::install_github("crsh/papaja") from the RStudio console.

papaja uses bookdown but you do not have to load this package separately.

- Create a new R Markdown document from the APA journal template. - Inspect the contents of the template, check out the options. - Knit it to pdf (`output : papaja::apa6_pdf`) or Word (`output : papaja::apa6_word`) and inspect the knitted document. - Apply your skills for cross-referencing sections, tables, and figures.

A manual for papaja is available at https://crsh.github.io/papaja_man/ .

Templates for other journals

The rticles package offers R Markdown templates for several journals and some journal publishers.

If you install this package, the journal or publisher templates are shown in the list of templates when you create a new R Markdown document.

Dashboards

A dashboard is used to show a group of related data visualizations. Below is a screen shot of an example created with package flexdashboard. It uses HTML widgets to show pop-ups when you hover over a graph (in the original dashboard, not in the screen shot below).

knitr::include_graphics("images/dashboard.png")

Read more about flexdashboard at https://RMarkdown.rstudio.com/flexdashboard/index.html .

Another package is shinydashboard, which uses shiny to create interactive dashboards. See https://rstudio.github.io/shinydashboard/index.html for more information.

Finalizing the Group Project

What to submit

Report:

• Submit knitted R Markdown document (HTML, PDF, or Word) & R Markdown file via Canvas.
• Knitted file must be reproducible from the R Markdown file.

Presentation (15 or 20 minutes per group, not necessarily in R Markdown):

• Brief description of the data set.
• Each group member presents a draft of their graph.
• Goal: get feedback from the group.

Group work on the project

WdeNooy/UsingRTutorials documentation built on Jan. 25, 2023, 2:39 a.m.