Creating a New Course

Swirlify is always aware of your working directory. Make sure that your working directory is where you want to create your new course. Once you’ve navigated to an appropriate working directory use new_lesson("[Course Name]", "[Lesson Name]") to create a new course. For example:

getwd()
#> [1] "/Users/sean/"

# Don't forget to load swirlfiy!
library(swirlify)

# The name of the new lesson is 'My First Lesson'
# The name of the new course is 'My New Course'
new_lesson("My First Lesson", "My New Course")

Let’s examine what new_lesson() did in the example above:

  1. A new directory was created in /Users/sean/ called My_New_Course.
  2. A new directory was created in /Users/sean/My_New_Course called My_First_Lesson.
  3. Several files were created inside of /Users/sean/My_New_Course/My_First_Lesson:
    • lesson.yaml is where you will write all of the questions for this lesson. (Example)
    • initLesson.R is an R script that is run before the lesson starts which is usually used to load data or set up environmental variables. (Example)
    • dependson.txt is the list of R packages your lesson will require. swirl will install these packages if the user doesn’t already have them installed. (Example)
    • customTests.R is where you can write your own tests for student’s answers. This is further discussed in Writing Custom Tests. (Example)

The structure of these files looks like this:

My_New_Course
└── My_First_Lesson
    ├── lesson.yaml
    ├── initLesson.R
    ├── dependson.txt
    └── customTests.R

If everything is set up correctly then new_lesson() should have opened up the new lesson.yaml file in a text editor. If you want to start writing your first lesson then you should move on to reading our guide to writing lessons.

Creating a New Lesson in an Existing Course

Make sure you’re working directory contains the course you want to add a lesson to. Use the new_lesson() function to start working on a new lesson:

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

Resuming Work on an Existing Lesson

Swirlify needs to be aware of what lesson you’re working on in order to properly function. You can set the current lesson using the set_lesson() function:

# If you don't provide any arguments to the function you can choose the 
# lesson.yaml file you wish to work on interactively.
set_lesson()

# Or you can explicitly specify the path to the lesson.yaml file.
set_lesson("My_New_Course/My_First_Lesson/lesson.yaml")

Find Out What Lesson You’re Working On

In case you lose track of what lesson you’re working on, you can remind yourself:

get_current_lesson()
You are currently working on...

Lesson: My First Lesson
Course: My New Course

This lesson is located at /Users/sean/Desktop/My_New_Course/My_First_Lesson/lesson.yaml

Organizing Lessons

Let’s revisit the general structure of a swirl course. This is the structure of a course with two lessons:

My_New_Course
├── My_First_Lesson
|   ├── lesson.yaml
|   ├── initLesson.R
|   ├── dependson.txt
|   └── customTests.R
└── My_Second_Lesson
    ├── lesson.yaml
    ├── initLesson.R
    ├── dependson.txt
    └── customTests.R

By default each folder in My_New_Course will be displayed to the student as a lesson they can select. If you want to explicitly specify the order in which lessons are displayed you will need to add a MANIFEST file to your course. You can do this with the add_to_manifest() function, which will add the lesson you are currently working on to the MANIFEST. You can also edit the MANIFEST yourself in a text editor. The MANIFEST file below belongs to Team swirl’s R Programming course:

Basic_Building_Blocks
Workspace_and_Files
Sequences_of_Numbers
Vectors
Missing_Values
Subsetting_Vectors
Matrices_and_Data_Frames
Logic
Functions
lapply_and_sapply
vapply_and_tapply
Looking_at_Data
Simulation
Dates_and_Times
Base_Graphics

Specifying a MANIFEST file also allows you to put data or other files or folders in the course folder without the name of those files or folders being displayed as if they were lessons. After adding a MANIFEST file to My_New_Course the structure of the files will look like this:

My_New_Course
├── My_First_Lesson
|   ├── lesson.yaml
|   ├── initLesson.R
|   ├── dependson.txt
|   └── customTests.R
├── My_Second_Lesson
|   ├── lesson.yaml
|   ├── initLesson.R
|   ├── dependson.txt
|   └── customTests.R
└── MANIFEST

Including Data

You may want to include data or files in your course for a student to manipulate or analyze. If you want to load data at the beginning of your course we recommend adding the following function to initLesson.R:

.get_course_path <- function(){
  tryCatch(swirl:::swirl_courses_dir(),
           error = function(c) {file.path(find.package("swirl"),"Courses")}
  )
}

You can then use .get_course_path() and file.path() in order to construct the path to data or files you’ve included in your course so that they can be loaded. Here’s an example initLesson.R that loads a csv called “data.csv” which is in the lesson folder of a lesson called “Lesson 1” in a course called “My Course”:

.get_course_path <- function(){
  tryCatch(swirl:::swirl_courses_dir(),
           error = function(c) {file.path(find.package("swirl"),"Courses")}
  )
}

dataset <- read.csv(file.path(.get_course_path(), "My_Course", "Lesson_1", "data.csv"))

The dataset data frame will then be in the student’s global environment when the lesson begins.