You’re an instructor!

swirl is a platform for teaching R programming and data science. However, an educational platform is only as good as the content it delivers to students. Although we have contributed some content ourselves, swirl is designed in such a way that you can create your own interactive content and share it freely with students in your classroom or around the world.

The swirlify R package provides a comprehensive toolbox for swirl instructors. Our authoring tools will guide you effortlessly through the process of creating interactive content, so that you can focus on the message you want to convey to students. The instructions that follow will have you writing your own interactive content with swirlify in just minutes! For more complete instructions about writing swirl courses please see the swirlify documentation.

Step 1: Get R

In order to run swirl and swirlify, you must have R 3.1.0 or later installed on your computer. If you are on a Linux operating system, please visit our Installing swirl on Linux page.

If you need to install R, you can do so here.

For help installing R, check out one of the following videos (courtesy of Roger Peng at Johns Hopkins Biostatistics):

• Installing R on Windows
• Installing R on Mac

Step 2 (recommended): Get RStudio

In addition to R, it’s highly recommended that you install RStudio, which will make your experience with R much more enjoyable.

If you need to install RStudio, you can do so here. Select the appropriate installer for your operating system.

Step 3: Install swirl and swirlify

Open RStudio (or just plain R if you don’t have RStudio) and copy and paste the following commands into the console to install everything you need:

install.packages(c("swirl", "swirlify"))

Step 4: Start swirlify

Type library(swirlify) at the R prompt to load the package. You’ll have to repeat this step every time you restart R or RStudio.

Step 5: Create a new lesson or edit an existing one

swirl courses are collections of individual lessons. It’s up to you how long you’d like each lesson to be, but we think it’s better to have many short, focused lessons than a few long, very general ones.

To create a new lesson:

new_lesson("My Lesson", "My Course")

This will create a course directory in your current working directory that looks like this (notice the underscores):

─ My_Course
  └─ My_Lesson
     ├─ lesson.yaml
     ├─ initLesson.R
     ├─ dependson.txt
     └─ customTests.R

To start working on an existing lesson:

set_lesson() # Set the lesson interactively

## OR...

set_lesson("path/to/My_Course/My_Lesson/lesson.yaml") # Set the lesson directly

Regardless of whether you use new_lesson() to create a new lesson or set_lesson() to open an existing one, swirlify should open the lesson file automatically for you to start editing.

Step 6: Create your interactive content!

For more complete information see the swirlify documentation, but here some helpful hints to get you on your way:

• Save your lesson file often as you edit it!
• To demo your lesson in swirl, save the lesson file, then type demo_lesson() at the prompt. You may wish to use the from and to arguments with demo_lesson() for testing specific portions of your lesson. Check out ?demo_lesson for more information.
• Use Git and GitHub! If you’re new to version control, GitHub provides excellent tutorials for beginners. swirl even has a built-in function (install_course_github()) that allows students to download a course directly from your GitHub repository!
• A great way to get comfortable with authoring your own content is by forking our course repository on GitHub and loading one of our R Programming lessons into swirlify (using set_lesson()). Experiment by making changes to the lesson, then use demo_lesson() to run the lesson in swirl with your changes.
• Read ?AnswerTests for more information on how answer testing works.
• Keep your answer tests simple at first (e.g. omnitest('x <- rnorm(10)')), so that you can focus on writing content. You can always go back and make them more sophisticated later.
• Any variables you define in initLesson.R will appear in the user’s workspace upon starting the lesson.
• For examples of how to include data in a lesson, install and run the Including Data lesson from our development repository via install_from_swirl("Including Data", dev = TRUE).
• swirl lessons are written in YAML. If you haven’t used YAML before, have no fear! We chose it for its simplicity and ease of use. However, if you want to use certain special characters like :, you need to surround your text with single or double quotes. Here’s a simple example:

- Class: text
  Output: "The following command assigns the mean of x to y: y <- mean(x)."

• If you are using RStudio to edit lesson.yaml, set the file type to Text File in the bottom righthand corner of the editor. This will enable text wrapping.

Step 7: Ask questions and get involved

To ask and answer questions about authoring swirl content, check out our swirl discussion group.