Tutorial Template

Introduction

This is a template for tutorials, which are instructive documents that guide a learner through a skill using examples.

Replace this text with a description of you tutorial. Include clear learning objectives. For example:

Have you ever learned a skill in R and wanted to share it with others? In this tutorial, we’ll walk through how to create tutorials so that you can easily share your skills!

Editing this template

Examples

Examples are key to meeting your learning objectives. Consider your audience, learning objectives, and narrative when writing examples (see The Carpentries Curriculum Development for tips). The learner needs to be able to reproduce examples from your tutorial on their computer. To do this, we look to advice on how to create a minimal, reproducible example. Examples may include:

• Problem or goal
• Dataset
• Solution code
• Information for reproducibility

Dataset

Almost all examples require an input. That is what is meant by “dataset”. You can create your own dataset or use one that is built into R.

Create-your-own:

Known values

x <- c(1, 5, 9, 10)

Random values (set seed to make it reproducible)

set.seed(20)
y <- rnorm(4)

See guidance on minimal, reproducible example for more examples.

Built-in:

Available datasets in R (run in RStudio to see list)

data() 

A popular example dataset is ‘iris’

head(iris)
#>   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
#> 1          5.1         3.5          1.4         0.2  setosa
#> 2          4.9         3.0          1.4         0.2  setosa
#> 3          4.7         3.2          1.3         0.2  setosa
#> 4          4.6         3.1          1.5         0.2  setosa
#> 5          5.0         3.6          1.4         0.2  setosa
#> 6          5.4         3.9          1.7         0.4  setosa

Another great example dataset is ‘penguins’

# install the package if it's not already installed
if(!("palmerpenguins" %in% installed.packages()[,"Package"]))
  install.packages("palmerpenguins")

# load package
library(palmerpenguins)

# show data
head(penguins)
#> # A tibble: 6 × 8
#>   species island bill_length_mm bill_depth_mm flipper_length_… body_mass_g sex  
#>   <fct>   <fct>           <dbl>         <dbl>            <int>       <int> <fct>
#> 1 Adelie  Torge…           39.1          18.7              181        3750 male 
#> 2 Adelie  Torge…           39.5          17.4              186        3800 fema…
#> 3 Adelie  Torge…           40.3          18                195        3250 fema…
#> 4 Adelie  Torge…           NA            NA                 NA          NA <NA> 
#> 5 Adelie  Torge…           36.7          19.3              193        3450 fema…
#> 6 Adelie  Torge…           39.3          20.6              190        3650 male 
#> # … with 1 more variable: year <int>

Solution code

We will use an example from the palmerpenguins vignette to demonstrate solution code. For this example, the goal is to create a scatterplot for data with different categories.

Install packages if they’re not already installed

This handy code is from Stackoverflow. List the packages a learner would need for your tutorial in the first line.

list.of.packages <- c("palmerpenguins", "dplyr", "ggplot2")
new.packages <- list.of.packages[!(list.of.packages %in% installed.packages()[,"Package"])]
if(length(new.packages)) install.packages(new.packages)

Load packages

We use the code chunk option “message = F” to suppress messages generated when packages load.

library(palmerpenguins)
library(dplyr)
library(ggplot2)

Settings

Include figure settings, saved variables, and create-your-own datasets.

theme_set(theme_minimal())

Solution

Code to create scatterplot. We use the option out.width to make the figure clearer and smaller.

ggplot(data = penguins, aes(x = flipper_length_mm, y = body_mass_g)) +
  geom_point(aes(color = species,
                 shape = species),
             size = 2) +
  scale_color_manual(values = c("darkorange","darkorchid","cyan4"))
#> Warning: Removed 2 rows containing missing values (geom_point).

If there are variations on your solution, provide more examples!

Information for reproducibility

R and R packages are continuously updated and examples that work under a certain set of conditions may not work under another set. Ideally, you would update your tutorial when key software is updated to maintain working examples. However, that may not be feasible, and the next best option is to provide learners with all the necessary information about your computing environment. This can help them identify differences with their computing environment that may be preventing the example from running as expected.

My computing environment:

Session information

sessionInfo()
#> R version 4.1.2 (2021-11-01)
#> Platform: x86_64-apple-darwin17.0 (64-bit)
#> Running under: macOS Big Sur 10.16
#> 
#> Matrix products: default
#> BLAS:   /Library/Frameworks/R.framework/Versions/4.1/Resources/lib/libRblas.0.dylib
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.1/Resources/lib/libRlapack.dylib
#> 
#> locale:
#> [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] ggplot2_3.3.5        dplyr_1.0.7          palmerpenguins_0.1.0
#> 
#> loaded via a namespace (and not attached):
#>  [1] highr_0.9        pillar_1.7.0     bslib_0.3.1      compiler_4.1.2  
#>  [5] jquerylib_0.1.4  tools_4.1.2      digest_0.6.29    gtable_0.3.0    
#>  [9] jsonlite_1.8.0   evaluate_0.15    lifecycle_1.0.1  tibble_3.1.6    
#> [13] pkgconfig_2.0.3  rlang_1.0.2      cli_3.2.0        DBI_1.1.2       
#> [17] rstudioapi_0.13  yaml_2.3.5       blogdown_1.7     xfun_0.30       
#> [21] fastmap_1.1.0    withr_2.4.3      stringr_1.4.0    knitr_1.37      
#> [25] generics_0.1.1   sass_0.4.0       vctrs_0.3.8      grid_4.1.2      
#> [29] tidyselect_1.1.1 glue_1.6.2       R6_2.5.1         fansi_1.0.2     
#> [33] rmarkdown_2.13   bookdown_0.24    farver_2.1.0     purrr_0.3.4     
#> [37] magrittr_2.0.2   scales_1.1.1     ellipsis_0.3.2   htmltools_0.5.2 
#> [41] assertthat_0.2.1 colorspace_2.0-2 labeling_0.4.2   utf8_1.2.2      
#> [45] stringi_1.7.6    munsell_0.5.0    crayon_1.5.0

RStudio version

# commented out for website compatibility, uncomment on your computer
# rstudioapi::versionInfo()$version

Sharing your tutorial