Chapter 8 Design a how-to

We define a “how-to” as a step-by-step recipe for a specific problem; light on narrative and teaching “why”. R Markdown is a great tool for this kind of lesson, and we recommend (surprise!) HTML output with the following options.

8.1 Share the source code

You can also make it easy for others to download the raw R Markdown file that produced the page on the your site that they’re viewing.

Add code_download: true underneath html_document:. This particular YAML option is one that you might consider only applying to .Rmd files where it’s relevant (in which case, you would include in the .Rmd’s YAML and not the _site.yml.)

---
name: YUM-101
output:
  html_document:
    toc: true
    toc_float: true
    code_download: true
---

8.2 Show the data

library(DT)
datatable(iris)

8.3 Share the data

For a how-to that involves some local data file that you need to share, it is nice to create an easy way for learners to download that data to a place on their computer.

xfun::embed_file() link
DT buttons link

library(DT)
datatable(iris, 
  extensions = 'Buttons', options = list(
    dom = 'Bfrtip',
    buttons = 
      list('copy', 'print', list(
        extend = 'collection',
        buttons = c('csv', 'excel', 'pdf'),
        text = 'Download'
      ))
  )
)

8.4 Code Folding

If you have a lot of code chunks, and you want to option for them to expand or fold with a click then:

Add code_folding: as an option underneath html_document:. The options are either show or hide, depending on whether or not you want code chunks to be expanded by default.

output_dir: "docs"
output: 
  html_document:
    code_folding: show

8.5 Show code, hide results

The default global chunk option is echo=TRUE, which means that by default all code in code chunks is printed in the output. But sometimes you may want to suppress the output for pedagogical reasons on individual code chunks. You could set eval = FALSE as a global chunk option, but this would mean that all the code chunks will not get evaluated at all. Thus, you could have errors in your code that learners could stumble upon. Instead, we suggest setting results='hide' as a global chunk option to ensure that when you knit, you’ll run into the same errors your learners will before they do.

```{r, results='hide'}
library(tidyverse)
glimpse(starwars)
```

8.6 Show code, hide plots

If your code produces plots, though, results='hide' will not suppress the plot. To suppress printing a plot, you’ll need to use fig.show='hide'.

```{r, results='hide', fig.show='hide'}
library(tidyverse)
glimpse(starwars)
ggplot(starwars, aes(x = height)) +
  geom_histogram(colour = "white", fill = "#3fb5bd") +
  theme_minimal()
```

8.7 Show results, hide code

Sometimes you may want to shield your learners from all the code and just focus their attention on the output, whether it is printed or it produced a plot. This requires a single switch to echo=FALSE to “mute” the code from being output.

```{r, echo=FALSE}
library(tidyverse)
glimpse(starwars)
```

This is all the learner sees:

## Rows: 87
## Columns: 14
## $ name       <chr> "Luke Skywalker", "C-3PO", "R2-D2", "Darth Vader", "Leia Or…
## $ height     <int> 172, 167, 96, 202, 150, 178, 165, 97, 183, 182, 188, 180, 2…
## $ mass       <dbl> 77.0, 75.0, 32.0, 136.0, 49.0, 120.0, 75.0, 32.0, 84.0, 77.…
## $ hair_color <chr> "blond", NA, NA, "none", "brown", "brown, grey", "brown", N…
## $ skin_color <chr> "fair", "gold", "white, blue", "white", "light", "light", "…
## $ eye_color  <chr> "blue", "yellow", "red", "yellow", "brown", "blue", "blue",…
## $ birth_year <dbl> 19.0, 112.0, 33.0, 41.9, 19.0, 52.0, 47.0, NA, 24.0, 57.0, …
## $ sex        <chr> "male", "none", "none", "male", "female", "male", "female",…
## $ gender     <chr> "masculine", "masculine", "masculine", "masculine", "femini…
## $ homeworld  <chr> "Tatooine", "Tatooine", "Naboo", "Tatooine", "Alderaan", "T…
## $ species    <chr> "Human", "Droid", "Droid", "Human", "Human", "Human", "Huma…
## $ films      <list> <"The Empire Strikes Back", "Revenge of the Sith", "Return…
## $ vehicles   <list> <"Snowspeeder", "Imperial Speeder Bike">, <>, <>, <>, "Imp…
## $ starships  <list> <"X-wing", "Imperial shuttle">, <>, <>, "TIE Advanced x1",…

8.8 Interactively hide/show code

whole document

8.9 Hide everything

Useful for you as you develop a lesson sometimes to save your code but hide the code and all output from learners. You can achieve the same thing with the combination of echo=FALSE, results='hide', fig.show='hide'. But the easier way is to use the include chunk option, which is by default set to TRUE.

```{r, include=FALSE}
library(tidyverse)
glimpse(starwars)
```

8.10 Reuse your code

Once you embrace code chunk options, you may often find yourself copying and pasting code chunks so that you can use different options on the same code chunk. Like maybe you want the code to appear once, but you

Special use case: plot first, code second

Chunk 1: {r plot-first, echo = FALSE}
Chunk 2: {r ref.label = 'plot-first', eval = FALSE}

8.11 Two plots side-by-side

ggplot(mtcars, aes(factor(cyl), fill = factor(vs))) +
  geom_bar(position = position_dodge(preserve = "total"))

ggplot(mtcars, aes(factor(cyl), fill = factor(vs))) +
  geom_bar(position = position_dodge2(preserve = "total"))

8.12 Include verbatim code chunks

You may have noticed that the code chunk output, even when echo=TRUE, does not show the actual code chunk options that you see in your .Rmd file. In order to print the full code chunk, you’ll need to

verbatim code chunks
knitr ref.label to reuse code chunks
the fig.path thing: https://yihui.name/knitr/options/#plots (see also: name your code chunks!)
making sure that your package warnings/messages don’t print!
how to control numbers of digits that print
control significance stars

options(
  show.signif.stars = FALSE,     
  digits = 2
  )