Instructor Guide
How to run the R Hands-on Workshop Series
This guide is for anyone teaching the workshop. The lessons contain everything learners see; the pages here add timing, teaching notes, and answers to the questions to ask the class.
The teaching rhythm
Every part of every lesson follows the same three steps:
- 👀 Follow along — you live-code the new skill on the workshop dataset (the outbreak linelist). Learners type the same code into their student script.
- ✏️ TRY IT — learners immediately do the same thing on the practice dataset (the measles outbreak). Each TRY IT takes 1–10 minutes and has a ✅ Check so learners know they got it right.
- Show the answer (or ask a learner to show theirs), then move on.
This is the approach used by The Carpentries: short demonstrations followed straight away by practice, so problems surface while they are still easy to fix.
Live coding tips
- Type, don’t paste. Learners need to see code being written — and your typos and fixes are useful teaching moments.
- Go slower than feels natural, and say what you’re typing as you type it.
- Use a big font (Positron: View → Appearance → Zoom In, or Cmd/Ctrl +
+) and a light color theme for the projector. - Run every line and talk about the output before moving on.
- Read errors out loud and fix them together — learners will meet the same errors.
Sticky notes and helpers
- Give every learner a green and a red sticky note.
- Green on the laptop = “I’m done with the TRY IT”
- Red = “I need help”
- Start the answer when most notes are green. Helpers go to red notes first.
- Aim for one helper for every 8–10 learners. Helpers don’t need to be experts — they need to have done the lesson.
- Early finishers can work on the ⭐ BONUS at the end of each lesson.
Before the workshop
- One week before: send learners the link to the Setup page and ask them to run the test at the end. Ask anyone who sees an error to contact you before the first session.
- Before each session: remind learners to open the workshop folder in Positron (File → Open Recent) and to run that session’s test (on the Setup page).
- Have a few copies of the workshop folder (
cwml-r-workshop.zip, from the Setup page) on a USB stick, in case of network problems.
Session overview
| Session | Lesson | Time | Starts from |
|---|---|---|---|
| 1 | R basics, importing, and inspecting data | 90 min | raw_data/ |
| 2 | Cleaning | 104 min | raw_data/ |
| 3 | Missing data, joins, and export | 87 min | processed_data/linelist_clean.rds |
| 4 | Data structures | 86 min | processed_data/combined_linelist.rds |
| 5 | Summarizing | 92 min | processed_data/combined_linelist.rds |
| 6 | Plotting basics | 87 min | processed_data/combined_linelist.rds |
| 7 | Plotting further | 87 min | processed_data/combined_linelist.rds |
| 8 | Programming (optional) | 85 min | processed_data/combined_linelist.rds |
Each session is planned for about 90 minutes including the TRY ITs. Real sessions with beginners often run long, so each session page lists what to cut if you’re short on time.
Every session starts from a file that is already in the repository, so learners who missed the previous session can still join.
The materials
| Folder | What’s in it |
|---|---|
pages/lessons/ |
The lesson pages on this website (the source .qmd files) |
student_scripts/ |
Student scripts: notes, Pattern lines, and TRY ITs with space to type |
solutions/ |
The student scripts with every answer filled in |
raw_data/ |
The workshop and practice datasets |
tools/build_student_zip.sh |
Builds cwml-r-workshop.zip, the student download: only the student scripts, solutions, the data Sessions 1–8 use, an empty outputs/, and the .here file. A GitHub Action rebuilds and republishes it automatically whenever those files change, so the Setup page’s link always has the latest version. |
instructor scripts/make_practice_data.R |
Recreates the measles practice data exactly (kept out of the public repository) |