In kbodwin/demoR: demoR: Tools for presenting and teaching R code

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

library(demoR)
library(dplyr)
library(ggplot2)
library(stringr)

Introduction

The primary goal of the demoR package is to simplify the presentation of R code.

It is common to show source code, in addition to code output, as part of a conference talk, workshop, or lecture. Often, we want to call attention to certain aspects of the code.

For example, suppose you want to illustrate to a new learner the use of the pipe %>%. You might want to create a slide that shows the following:

demo_code('

iris %>%
  group_by(Species) %>%
  summarize(mean(Sepal.Length))

') %>%
  hlt_regexp(fixed("%>%"))

Without demoR, your approach might be to type your code into your code chunk, copy-paste it to a string, and manually format that string using html. What a headache!

In this vignette, we will show you how to use the demoR package to simultaneously run and format code.

demo_code Objects

The core element of the demoR package is an object of the class demo_code. These objects contain both the natural output of your R code and information to let knitr know how display the source code.

Demoing from a code chunk

The cleanest way to make a demo_code object is by referencing a named code chunk in R Markdown.

iris %>%
  group_by(Species) %>%
  summarize(mean(Sepal.Length))

For example:

```r`r ''`

iris %>%
  group_by(Species) %>%
  summarize(mean(Sepal.Length))

```

You can use the chunk label to automatically create a demo_code object using create_demo(). Here we pass the object to hlt_fixed() to show our source code with the pipe operators highlighted in yellow.

```r`r ''`

demo_chunk("how_to_pipe") %>% hlt_fixed("%>%")

```

Note that the create_demo step should be in a separate chunk from the code you are demoing, since it is not itself part of the source code you wish to display.

With the above two code chunks in our source file, the resulting knitted output looks like this:

demo_chunk("how_to_pipe") %>% 
  hlt_fixed("%>%") 

Demoing from a code string

You can also use the demo_code() function to create a demo_code object directly from a string of R code. For example

demo_code('

iris %>%
  group_by(Species) %>%
  summarize(mean(Sepal.Length))

') %>%
  hlt_fixed("%>%")

produces

demo_code('

iris %>%
  group_by(Species) %>%
  summarize(mean(Sepal.Length))

') %>%
  hlt_fixed("%>%")

This option for demo_code creation is particularly nice if you want to show "bad" code that cannot normally be evaluated in a chunk. For example:

demo_code('

mean(1:10

') %>%
  hlt_fixed("(")

The hlt_* functions

The advantage of a demo_code object is that you can add formatting to the source code without altering the output, through the suite of highlightint (hlt) functions

hlt_regexp

The main function you will use is hlt_regexp(). This takes as arguments:

• A string or a demo_code object

• A regular expression

• Any number of formatting parameters

If no formatting parameters are supplied, hlt_* will default to ordinary yellow-background highlighting.

hlt_regexp returns a demo_code object, so it is pipe friendly!

Suppose you want to highlight the pipe (%>%) in yellow, highlight the variable name Sepal.Length in pink, and change the text color of Species to blue

Your code chunk:

demo_code('

iris %>%
  group_by(Species) %>%
  summarize(mean(Sepal.Length))

') %>%
  hlt_regexp(fixed("%>%")) %>%
  hlt_regexp("Sepal.Length", background = "pink") %>%
  hlt_regexp("Species", color = "CornflowerBlue")

Your knitted output:

demo_code('

iris %>%
  group_by(Species) %>%
  summarize(mean(Sepal.Length))

') %>%
  hlt_regexp(fixed("%>%")) %>%
  hlt_regexp("Sepal.Length", background = "Pink") %>%
  hlt_regexp("Species", color = "CornflowerBlue")

Syntax highlighting

demoR also includes a few shortcuts for highlighting specific aspsects of R source code. Currently, these functions are:

• hlt_funs() for functions

• hlt_args() for arguments to functions

• hlt_input_vals() for values assigned to function arguments

For example:

demo_code('

ggplot(iris, aes(x = Sepal.Length, fill = Species)) +
  geom_histogram(alpha = 0.5)

') %>%
  hlt_args(color = "CornflowerBlue") %>%
  hlt_funs(color = "Coral", underline = TRUE) %>%
  hlt_input_vals(background = "Aquamarine") %>%
  hlt_regexp("Sepal.Length", background = "pink")

Errata

Defining objects

One nice feature of a demo_code object, as compared to a string, it that it evaluates when run. This means that you can define objects in your demo code, and use them later in your analysis as you normally would:

demo_code('foo <- mean(1:10)') %>% hlt_funs()

foo + 5

A word of caution: Make sure you define your objects in your code string, not outside the demo_code() function! For example, the following approach has two problems:

1. foo contains the demo_code object, not the result of mean(1:10), so foo + 5 throws an error.

2. The demo_code object is stored as foo rather than printed, so no highlighted code is included in the knitted output.

foo <- demo_code('mean(1:10)') %>% hlt_funs()

foo + 5

A note about colors

demoR gives you complete freedom to choose the colors of your highlighted elements, so long as the color name is a recognized html name or a hex code.

However, please remember to be judicious in your color choices, and to keep in mind how your colors appear to colorblind individuals.

kbodwin/demoR documentation built on Nov. 10, 2019, 11:30 p.m.