Use the R console as an interactive learning environment. Users receive immediate feedback as they are guided through self-paced lessons in data science and R programming.
swirl is a platform for learning (and teaching) statistics and R simultaneously and interactively. It presents a choice of course lessons and interactively tutors a student through them. A student may be asked to watch a video, to answer a multiple-choice or fill-in-the-blanks question, or to enter a command in the R console precisely as if he or she were using R in practice. Emphasis is on the last, interacting with the R console. User responses are tested for correctness and hints are given if appropriate. Progress is automatically saved so that a user may quit at any time and later resume without losing work.
swirl leans heavily on exercising a student's use of the R console. A callback mechanism, suggested and first demonstrated for the purpose by Hadley Wickham, is used to capture student input and to provide immediate feedback relevant to the course material at hand.
The program is initiated with
swirl(). Functions which control swirl's
bye() to quit,
skip() to skip a question,
return to the main menu,
play() to allow experimentation in the R console
without interference from swirl,
nxt() to resume interacting with swirl, and
info() to display a help menu.
The easiest way to install and run swirl is by typing the following from the R console:
install.packages("swirl") library(swirl) swirl()
As we continue adding new features and content, we will make new versions available on CRAN as appropriate (every 1-2 months, most likely).
To access the most recent features and content, you can install and run the development version of swirl using the devtools package:
install.packages("devtools") devtools::install_github("swirldev/swirl", ref = "dev") library(swirl) swirl()
If you'd like to get involved, please fork this repository and submit a pull request with your proposed changes. We're happy to chat if you have any questions about the source code.
Instructors around the world are using swirl in their classrooms. We think this is awesome. If you're an instructor, please feel free to do the same -- free of charge. While your students may be paying to take your course or attend your institution, we simply ask that you don't charge people directly for the use of our software or instructional content.
If you are not sure about a particular use case, don't hesitate to send us an email at [email protected].
Added new answer test:
Now compatible with versions of testthat later than 0.11.0.
Added support for multiple languages, including Spanish, French, German,
Turkish, Simplified Chinese, and Korean. The default language can be changed
using the function
install_course() in order to install swirl courses that are
distributed in the .swc format.
The directories where swirl courses and where user data is stored can now be
explicitly specified. These options can be set using the function
It's now possible to log and collect a student's progression
through a swirl course. Enable logging with
Improved support for displaying non-ASCII character sets through UTF-8 encoding.
Now compatible with
Add basic developer API to swirl, courtesy of @filipsch and @seankross.
Change license to MIT, which is slightly less restrictive than GPL-3 and will make it easy for developers to tap into the new API.
mirror argument to
install_from_swirl() to accommodate installing courses from the Bitbucket mirror of our swirl-courses GitHub repository. (Prompted by India's blocking of GitHub.)
Check for existence of variable in swirl.R to address issue with using
omnitestdue to typo (thanks to @reginaastri).
Fix small bug in
omnitest due to missing exclamation point (thanks to @wilcrofter).
delete_progress function (thanks to @seankross).
partner.coursera.org websites for Coursera submission is enabled.
match.call) to deal with legitimate variations of function and S3 method calls.
Fix bug in
install_from_swirl() that was causing
install_from_swirl("R Programming") to install both
R Programming and
R Programming Alt.
Fix troublesome links to the swirl_courses repo.
?InstallCourses, which gives a brief overview of installing swirl courses and includes links to all relevant help files.
email_admin() feature, which allows the user to automatically generate an email to be sent to
[email protected]. The email includes space for a description of the problem along with the output from
Clean up swirl's core function,
swirl() in swirl.R, so that we can view the administrative environment
as.list(e) without complaint from R.
Add empty cran-comments.md to appease new devtools
Add a new
script question type, which allows an instructor to present a preformatted R script to the user for editing and submission. swirl was originally designed for interactive programming at the prompt. It now accommodates multiline input, which allows for exploration of topics like writing functions and control structures, as well as more extended function calls.
Allow user to make swirl feedback less playful with
options(swirl_is_fun = FALSE).
welcome.default(), make sure the user doesn't put any special characters (using the
[[:punct:]] regex) in his or her name, as this might lead to an invalid file path for their user data. Thanks to @Sarpwus for bringing this to my attention.
Trim leading/trailing whitespace when reading lesson dependencies from dependson.txt.
dev argument to
install_from_swirl() to allow installation of courses in development from the swirl_misc repository.
Update phrases.R to include new praise and 'try again' phrases. Thanks to @sagevann for the suggestions.
capture.output() to avoid double printing due to second evaluation by
testit() to functions for callback to ignore, so that swirl plays nicely with swirlify.
Add from/to feature for testing specific units of content during course authoring.
Alternate user progress tracking strategy without previous lag or freeze problems. Backwards compatible with existing course content. Tracks large or small lesson data sets by default, but these may be excluded by sourcing with local=FALSE from the initLesson.R file.
Make course installation success/failure messages more robust.
Add documentation for
Create a file for manual submission to Coursera immediately after the user enters his or her credentials. This way, no matter what happens during the submission process, manual submission is still an option. The file is deleted if automatic submission succeeds.
any_of_exprs() to library of answer tests.
Fix bug related to user entering their Coursera Course ID with quotes.
Fix bug causing swirl to fail when exiting from course menu.
packageStartupMessage() that detects a cluttered workspace and warns the user that this may cause swirl to run slowly.
main() function, which allows user to return to the main menu while a lesson is in progress.
which_course argument to
install_course_zip() that will facilitate manual installation. In particular, if a student downloads a zip file from the swirl courses repo, it comes with all courses in it. This function will allow the user to install only those that she wants.
skip()count not resetting upon lesson completion.
Add confirmation step to Coursera submission process.
Stash Course ID along with other Coursera creds.
Display correct answer when user
skip()s a question.
Instructional content is no longer shipped with swirl. Instead, it is located in our course repo. When the user starts swirl, he or she is given the option to install the R Programming course automatically or be taken to the course repo page. Courses can also be installed with the
Content authoring tools have also been removed from the swirl package. We've created a new package called swirlify, which is a comprehensive toolbox for swirl instructors. Instructions for authoring content are on the Instructors page of the swirl website.
Package dependencies for a lesson are now managing by including a file called
dependson.txt in the lesson directory, which lists required packages one line at a time. This strategy is mainly for backwards compatibility and will take a different form for new content in future releases. When the user begins a lesson with package dependencies, swirl attempts to load each package in turn and prompts the user to automatically install any packages not found.
Added help files for answer tests contained in
Added progress bar feature using
test mode for compatibility with the swirlify package.
Integrated with Coursera API to allow enrolled students to receive credit for swirl lessons associated their Coursera course.
rmd2df() can finally handle
video units of instruction.
parse_content() now parses content (at runtime) in its original form (R Markdown, YAML, etc.), making conversion to CSV files unnecessary. The appropriate parsing method is called based on the extension of the lesson file. Creating a new course authoring format is as simple as writing a new method for
parse_content() that accepts the content as input and returns a properly structured
author_lesson() function creates and opens a customized lesson template for authoring content.
Suite of functions for installing (and uninstalling) swirl courses:
install_course_directory(): Install a course from a course directory
install_course_dropbox(): Install a course from a zipped course directory shared on Dropbox
install_course_github(): Install a course from a GitHub repository
install_course_google_drive(): Install a course from a zipped course directory shared on Google Drive
install_course_url(): Install a course from a url that points to a zip file
install_course_zip(): Install a course from a zipped course folder
uninstall_course(): Uninstall a course
zip_course(): Zip a course directory
Course authors can add custom tests for student responses.
Revised suite of answer tests (contained in answerTests2.R) using a more natural function call syntax.
Revised user progress tracking and restoration.
Message notifying the user when she's completed a lesson, just prior to returning to the main menu.
Miscellaneous big fixes
addTaskCallback() as a mechanism to capture user input directly from the R prompt.
info() brings up a menu of options including
skip() allows the user to skip the current question. swirl automatically evaluates the correct answer in the user's workspace in case future questions depend on the result.
Includes a library of answer tests based on testthat, an R package designed by Hadley Wickham for unit testing.
Tests user responses for correctness based various combinations of the aforementioned answer tests. A user is judged to have answered a question correctly when the answer tests specified for that question are satisfied.
The answer tests operate on the R expression entered by the user, as opposed to the string representation of it (see swirl 1.0). This avoids marking a user incorrect for stylistic discrepancies such as including single spaces between function arguments, etc.
Makes heavy use of R's S3 object oriented programming dialect to promote an easily extensible architecture. Incorporating new functionality simply requires writing new methods for existing "core" functions.
Instructors can now author content in an R Markdown (.Rmd) file, then use
rmd2csv() to create the CSV file from which swirl reads content. This is an experimental feature based on syntax employed by slidify, an R package designed by Ramnath Vaidyanathan for creating interactive web presentations.