Chapter 4 Fourth week
4.1 Swirl Courses
Hello, I’m Sean Cross your instructor for this week’s content on Swirl. Swirl is an interactive tool designed to teach R programming and data science concepts directly within the R console. With Swirl, you can learn at your own pace, interactively, and without needing to switch between different environments. Swirlify is an R package that allows you to create your own Swirl courses and lessons. In this lesson, we will demonstrate how to create Swirl courses and lessons using Swirlify.
4.1.1 Swirl 1.1
We will demonstrate how to create Swirl courses and lessons with Swirlify. Swirl is an R package that transforms the R console into an interactive learning environment. In case you’re new to Swirl, we will give you a quick overview. First, you need to load the Swirl package library(swirl) and then start Swirl by calling swirl() in R consol. As you can see, the console starts prompting with questions. We can select a Swirl course to begin, and then within that course, we can pick a lesson. Swirl provides text prompts in the console and asks you to enter specific R commands. For example, it would ask you to type in 5 + 7. If you entered the correct answer, Swirl would move on to the next question. If you made a mistake, Swirl would provide a hint to guide you in the right direction.
Swirl offers various types of questions, and we can exit a lesson at any time by pressing the Escape key. Now, let’s move on to creating Swirl lessons using Swirlify.
4.1.2 Swirl 1.2
Here we are going to demonstrate how to write your own swirl courses and lessons using the swirlify package. To begin, you will need to load the swirlify package library(swirlify), if it is not installed on your computer you can install it with install.packages("swirlify"). Swirlify is always aware of your current working directory, so make sure you set the working directory to your desired directory. Here, we will set the directory to a special folder on the desktop called “Courses,” where we wish to keep our swirl courses and lessons.
You can start writing a new swirl course and lesson using the following template.
setwd(file.path("~", "Desktop/Courses"))
swirlify("Lesson 1", "My First Course")So we set the working directory and name the lesson “Lesson 1” and the course “My First Course”. Upon executing this function, several things happen. It generates a few template files for you to create your course, then it will start the Shiny lesson where you can start authoring the app. All swirl lessons are written in YAML, which is a simple markup language. In YAML, each question is demarcated by a hyphen and is followed by key-value pairs that specify each type of question and its content. To give you a look at what we mean, let’s go to my “Courses” folder after executing the above code. Inside, you’ll see the course that was just created “My First Course” which has one lesson inside it named “Lesson 1”. Each course is its own folder, and each lesson is its own folder inside a course.
My_New_Course
- My_First_Lesson
- lesson.yaml
- initLesson.R
- dependson.txt
- customTests.RAlternatively, you can use the new_lesson() function to create your course and lesson. With this approach, you should specify the directory where you want to create the course and lesson. Then run the new_lesson() function and specify the name of the lesson and course.
setwd(file.path("~", "Desktop/Courses"))
new_lesson("My First Lesson", "My First Course")The difference between this approach and the previous approach is that the new_lesson() function gives you access to the YML file through R consol, whereas the swirlify() function starts a Shiny app which contains YML file and it is self-explanatory. Any changes you make in the Shiny app will be reflected in the YML file. There is also a great tutorial on the swirlify package that you can access in Youtube.
In the lesson folder, the file, “customTests.R”, is where you can specify your own functions for testing the correctness of swirl questions, example. The “dependson.txt” text file allows you to list the names of R packages that are on Cran, example. This is where we check to ensure the R packages are installed before the lesson begins. The “initLesson.R” script is run before a lesson starts, allowing you to load data or create functions that will be used in the lesson, example. Lastly, the “lesson.yaml” file is where we specify the questions for the lesson, example.
We recommend using RStudio for writing swirl lessons because it allows you to have a text editor and R console side by side. However, different people have different workflows. To add questions, you can use the wq_ series of functions that come with swirl. To see the list of these questions you can just type in wq_ in the consol and the different types will automatically show up. There are several types of questions you can include in a lesson, including message questions wq_message() and command questions wq_command(). A message question is a simple prompt that displays a message to the student. A command question prompts the student to enter R code into the console. You either just execute wq_message() and then edit the put your text output here in the YML file Output: put your text output here or you can execute wq_message("Welcome to lesson 1") and it will automatically add the message to the YML file.
When writing a command question, you specify the correct answer and a function to test the correctness of the student’s answer. The function has a format like this:
wq_command(output = "explain what the user must do here",
correct_answer = "EXPR or VAL",
answer_tests = "omnitest(correctExpr='EXPR', correctVal=VAL)",
hint = "hint")The output argument is the prompt that is displayed to the student. The correct_answer argument is the correct answer to the question. The answer_tests argument is a function that tests the correctness of the student’s answer.The omnitest function is recommended for most questions. The hint argument is a hint that is displayed to the student if they answer incorrectly. You can either fill in the arguments with the correct values or you can just execute the function and then edit the YML file.
Here is an example of a command question:
- Class: cmd_question
Output: Add 2 and 2 together using the addition operator.
CorrectAnswer: 2 + 2
AnswerTests: omnitest(correctExpr='2 + 2')
Hint: Just type 2 + 2.Once you have written some questions, and you want to add the lesson to the course, you need to update the course manifest using the add to manifest function add_to_manifest(). This function creates a manifest file inside the course directory outside the lesson folder and it keeps track of the order of lessons in the course and prevents files that are not lessons from appearing in the lesson selection menu.
To check the lesson’s formatting, use the test lesson function test_lesson(). If no warnings or messages are returned, the lesson passed formatting checks. To preview the lesson, use the demo lesson function demo_lesson(), which takes you directly to the lesson without going through swirl’s menu. Once you’re in the lesson, you can answer the questions and complete it. In this case, the first question is “Welcome to lesson 1,” and the second question is “Add 2 and 2 using a plus operator.”
4.1.3 Swirl 1.3
Now that we have created and tested our first lesson, let’s move on to some more complex question types that we can include in a swirl lesson. If we want to start a new lesson, we can simply close the current lesson.yaml file and create a new lesson within the same course. To confirm that we are working in the correct course, we can use the get_current_lesson() function, which will return information about the current lesson and course. In this case, our course is called “My First Course” and we will create Lesson 2 within it. It’s important to note that the first question generated in a lesson is the meta question, which provides information about the lesson’s author and organization. This question is not visible to the students. We can fill out the author and organization fields within the meta question to provide this information. Okay, let’s dive into some more advanced question types. For instance, to create a multiple-choice question, we can use the wq_multiple() function and specify the question prompt and answer choices. Here is an example to add a multiple-choice question.
wq_multiple(output = "What is the capital of Canada?",
answer_choices = c("Toronto","Montreal","Ottawa","Vancouver"),
correct_answer = "Ottawa",
answer_tests = "omnitest(correctVal= 'Ottawa')",
hint = "This city contains the Rideau Canal.")
>Once we’ve created the question, we can add it to the course manifest and run the test_lesson() and demo_lesson() functions to ensure everything works properly.
To create a figure question, we can use the wq_figure() function and specify the message to display to the student, such as “This is a simple graph.”
Example:
wq_figure(output = "This is a simple graph.",
figure = "sourcefile.R",
figure_type = "new")To start a new lesson in the “My First Course” course, we can close the current “lesson.yaml” file. You can use the get_current_lesson() function to confirm which course you are working on.
Let’s start a new lesson and name it “Lesson 2” and create a multiple-choice question using the wq_multiple() function. We can provide the question prompt, answer choices separated by semi-colons, the correct answer, and a hint. After adding this lesson to the course manifest and running test_lesson() and demo_lesson() with no errors, we can move on to creating a figure type question. Using wq_figure(), we add a new figure question template with the Figure and FigureType fields. The Figure field specifies an R script that will generate the figure, while the FigureType field specifies whether the question will build on an existing figure or create a new one. We create a simple plot and save it as “fig1.R” in the lesson directory, then use demo_lesson() to display the plot.
wq_figure(output = "simple graph", figure = "fig1.R",
figure_type = "new")# fig1.R
plot(1:10)We can then add another figure question to modify the plot by adding a line. We save the code for adding the line in “fig2.R” and set the FigureType to add. Finally, we use demo_lesson() to display the modified plot with the added line.
wq_figure(output = "I added a line",
figure = "fig2.R",
figure_type = "add")# fig2.R
abline(h=5, col="red", lwd=2)For more information on creating swirl lessons, you can visit the swirl website. There you can the documentation. You can also find a link to the swirl course development guide, which contains more detailed information on creating swirl lessons.
4.1.4 Swirl 1.4
Swirlify makes sharing a swirl course easy. We recommend three different methods for sharing a swirl course.