swirl-tbp: template-based practice problems and automated grading in swirl

The swirl-tbp extension introduces template-based practice problems and automated grading to the swirl framework. The base swirl package is described at http://swirlstats.com. Specifically, swirl-tbp extends swirl by allowing instructors to include template-based problems in swirl lessons. Template-based problems are problems that include numbers, variable names, or other features that are randomly generated at run-time. As a result, a user can be provided with an endless supply of practice problems that differ, e.g., with respect to the numbers used. This allows users to repeatedly practice problems in order to reinforce concepts and practice their problem-solving skills. In addition, swirl-tbp allows instructors to generate assignments which can be automatically graded.

Instructions

1. Install the swirl package by typing the following from within R:

# install the devtools package, if necessary
install.packages("devtools")

# install swirl-tbp 
library(devtools)
install_github("gdancik/swirl-tbp", ref = "assign")

2. Optionally, install example lessons by typing the following:

library(swirl)
install_course_github("gdancik", "swirl-tbp", "swirl-tbp_example")

3. Lessons are run in the same fashion as standard swirl lessons. However, at any time the student can type rpt() to repeat the previous question (with different dynamic values), if desired. To begin swirl, type the following from within R:

library(swirl)
swirl()

Creating lessons

    - Class: cmd_question
      NumTimes: 2
      Token: |
        num1 = sample(1:10)
        num2 = sample(11:20)
      Output: Create a vector named 'values' that holds the values <num1> and <num2>.
      CorrectAnswer: values <- c(<num1>,<num2>)
      AnswerTests: omnitest(correctExpr='values <- c(<num1>,<num2>)')
      HintFunction: createVectorHint()

The main addition is that a Token line is specified which uses R code to dynamically generate tokens (values). Elsewhere in the YAML file, these tokens are surrounded by angle brackets (e.g., <num1>) and will be replaced by their values when the lesson is run.

For example, the above segment generates a question of the form 'Create a vector named values that holds the values num1 and num2', where num1 will be a random integer between 1 and 10 and num2 a random integer between 11 and 20.

Note that in the Token line above, the vertical line (|) is necessary to indicate that the R code spans multiple lines. Each line must begin with a number of blank spaces, as tabs are not allowed in YAML files. Alternatively, the R code can be specified on a single line with statements separated by semi-colons.

A developer can also provide a NumTimes value. When a lesson is run, the question will be repeated (using dynamically generated values) the specified number of times (if not specified, NumTimes defaults to 1).

The HintFunction specifies a function call that can be used to provide tailored hints based on the student's answer. See the lesson.yaml and accompanying initLesson.R files in the examples.

Creating and grading assignments

1. Create a swirl "lesson", optionally with templates, by following the instructions above.


2. Type the following code to create the assignment

   
   createAssignment("lesson.yaml", "directory", "assignment.R")
   

   where "lesson.yaml" is the name (and path) to the yaml file containing the lesson, "directory" is the (path and) name of the directory where the assignment should be saved, and "assignment.R" is the name of the assignment. Three directories will be created, "instr" containing the assignment and the yaml file in a csv format, "submissions" where student submissions can be stored, and "feedback" where student reports will be generated.


3. After an assignment has been completed and moved to the "submissions" folder, the following command will grade the assignment:

   
   gradeAssignment("directory")
   

   where "directory" is the directory created by the "createAssignment" function. Graded assignments are stored in the "feedback" folder, in the form of an html document.

Contributors

• Main contributor: Garrett Dancik (send questions/comments to )
• Additional contributors: Kyle Marrotte, Ryan Shooner, Sarah Fuller

Acknowledgements