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!
- Become familiar with the tutorial template
- Adapt the tutorial template to your needs
- Create beautiful and clear tutorials for learneRs
Editing this template
Accessing the template
If you do not use Github, go to the tutorials repository home page, click
Code, and click
Download ZIP. Open the
tutorial_template.Rmd file in RStudio.
This template is written in an R Markdown document. This type of document is best opened and edited in RStudio. R Markdown documents allow you to include text (like this), code (see below), and output of code, like figures, in a single document. You can learn more about R Markdown here (check out the Cheatsheet!).
If you haven’t already, replace the
Tutorial Title and
Author information in the metadata block at the top of this document with your information.
This section is titled Editing this template and the sub-section is titled Section titles, but your tutorial won’t necessarily need these sections. Consider the sections that you want in your tutorial and revise the headers throughout (the text that starts with ##) or create your own section headers.
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
- Solution code
- Information for reproducibility
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.
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.
Available datasets in R (run in RStudio to see list)
A popular example dataset is ‘iris’
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)
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)
We use the code chunk option “message = F” to suppress messages generated when packages load.
library(palmerpenguins) library(dplyr) library(ggplot2)
Include figure settings, saved variables, and create-your-own datasets.
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"))
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:
# commented out for website compatibility, uncomment on your computer # rstudioapi::versionInfo()$version
Sharing your tutorial
If you’re sharing your tutorial at an R-Ladies meeting, consider making slides to go along with it.
See the R-Ladies Gainesville presentations repository to download the the R Markdown file
tutorial_template.Rmd. The tutorial_template presentation is created with the xaringan package and the RLadies theme by Alison Hill.
Now it’s time to add your tutorial to the R-Ladies Gainesville tutorials repository. This will make it easier for others to provide feedback and for people to use your tutorial!
If you do not use Github, email your
.Rmd file to R-Ladies Gainesville at firstname.lastname@example.org.