01_RTutorOverview.RmdRTutor is an R package that allows to develop interactive R problem sets. The interactive tasks directly test a student’s solution and provide hints if not everything is correct. For an overview of the main features that distinguishes RTutor from similar projects like learnr, you can take a look at this blog entry RTutor problem sets can either be solved as RMarkdown files directly in RStudio or in a browser based interface powered by Shiny.
RTutor is used in several courses at Ulm University and other universities. I also have supervised several students who have created very nice web-based RTutor problem sets that allow to replicate the analyses of well published economic articles in an interactive fashion (a list is on the RTutor main page https://skranz.github.io/RTutor).
This document gives you a first overview of how to generate an interactive RTutor problem set.
To install RTutor just run
install.packages("RTutor",repos = c("https://skranz-repo.github.io/drat/",getOption("repos")))If you create problem sets that you want to host on shinyapps.io, you have to install all packages directly from Github. See the instructions on https://github.com/skranz/RTutor.
You create an interactive problem set by writing a solution file in R markdown format. In addition to the exercise description and a sample solution, the solution can contain manually adapted test, hints, quizzes or other commands e.g. to give awards. Where no manual hints or tests are specified, RTutor will automatically generate tests and hints.
Some examples can be found here in the example directory on Github. Below is the code of the example myps_sol.Rmd a simple example problem set that we name myps.
Important: If you want to run this example, copy the Rmd file on Github. Copy pasting the code below won’t work.
#< ignore
```{r "setup"}
library(RTutor)
# Adapt the working directory below and then run setup chunk in RStudio.
setwd("C:/folder_of_this_solution_file")
ps.name = "myps"; sol.file = paste0(ps.name,"_sol.Rmd")
libs = c("ggplot2") # character vector of all packages you load in the problem set
#name.rmd.chunks(sol.file)
create.ps(sol.file=sol.file, ps.name=ps.name, libs=libs, addons = "quiz")
# The following line directly shows the problem set
# in the browser
show.ps(ps.name,launch.browser=TRUE,
auto.save.code=FALSE,sample.solution=FALSE)
```
#>
## Exercise 1 -- Summary statistics
a) We often want to compute some summary statistic of a vector.
For example:
```{r "1 a)"}
#< task_notest
x = 10:20
# Computing the sum of x
sum(x)
#>
```
Now compute the mean of x.
```{r "1 a) 2"}
mean(x)
#< hint
display("Use Google, e.g. search for 'R compute mean'.")
#>
```
#< award "mean means mean"
Well, in some occasions one can just guess the name of an R function.
The function to compute the mean of a vector, or matrix is called 'mean'.
Usually, it is much quicker to goggle than to guess function names, however.
#>
## Exercise 2 -- Computing with vectors
a) Let y be a vector that contains the squared elements of x.
Then show y.
```{r "2 a)"}
#< task
x = 1:5
#>
y = x^2
y
```
We can also plot in a problem set
```{r "2 a) 2"}
library(ggplot2)
qplot(x,y)
```
#< info "random numbers"
Here are examples for generating random numbers
```{r "1 "}
runif(3,0,100)
sample(1:100,5)
```
#>
Here is a quiz that will be nicely shown in the
shiny version.
#< quiz "prime"
question: What is the 'oddest' prime?
sc:
- 2*
- 3
- 5
- 7
success: Well, of course the answer is debatable...
failure: Try again.
#>
The lines starting with ## Exercise are very important. Every RTutor problem set must have at least one exercise.
The different blocks starting with #< are described in this manual and further details on customizing tests and hints are given here.
The functions create.ps and show.ps both have a large set of arguments that allow a lot of customization. Take a look at the corresponding help files.
To create an example problem set copy the example from here and save it in myps_sol.Rmd. Then set the right working directory in the setup chunk.
setwd("C:/folder_of_this_solution_file")"C:/folder_of_this_solution_file")Afterwards run the setup chunk in RStudio. (You may assign a keyboard shortcut to running the setup chunk.)
The call to
create.ps(sol.file=sol.file, ps.name=ps.name, libs=libs, addons = "quiz")generates several files:
myps.rps: a binary representation of the problem set structure
myps.Rmd: empty problem set in Rmarkdown format
myps_sample_solution.Rmd: A sample solution of the problem set in Rmarkdown format.
myps_output_solution.Rmd: An Rmd file that can be the basis to statically knit the solved problem set. (This file is mainly useful for students who want to write a Bachelor or Master thesis based on an RTutor problem set.)
Note: RTutor creates automatic chunk names for the created Rmd files. If you uncomment the line
#name.rmd.chunks(sol.file)in the setup chunk of your solution file myps_sol.Rmd, its chunk names will be set in the same way.
The call
show.ps(ps.name,launch.browser=TRUE, auto.save.code=FALSE,sample.solution=FALSE)shows the problem set in your default browser. You can enter some code in the first chunk and check your solution by pressing the “check” button.
If you set the argument sample.solution=TRUE all chunks are already filled with the sample solution.
Alternatively, the problem set can be solved by students working in RStudio with the created myps.Rmd file. You should give students a ZIP file that contains the files myps.Rmd (the unsolved problem set) and myps.rps (compiled version of the problem set structure and solution) and possible all additional files like data sets etc.
Students should extract the files into a directory and open myps.Rmd in RStudio. That is the file they work on. Students can check their solution by clicking on the RStudio Addin Check Problemset, which is available once RTutor has been installed.
A student can type stats() in the R console to get some information of how much of the problem set he has already solved.
Typing hint() provides hints about how to solve the current task that failed to pass the solution tests.
You can test yourself whether that works fine by opening Example_sample_solution.Rmd and then checking the problem set.
By default all variables from previous chunks of an exercise are known in later chunks of that exercise. Therefore all tasks within an exercise have to be solved in the given order.
Exceptions are chunks marked with the chunk option optional=TRUE. These chunks don’t have to be solved in order to proceed. Correspondingly, also the computed variables from optional chunks will not be available in later chunks, since we cannot generally expect that optional chunks have been solved.
Also variables created in task_notest blocks or notest blocks will not be available in later chunks of an exercise.
Different exercises are independent of
You can use RTutor problem sets just as interactive tutorials without the need for students to submit any solutions.
Or you can ask students who have finished their problem sets, to submit their solution. In the shiny version there is a button to create a submission file (with file type .sub) and in the RTutor version, students should call the function make.submission(). You should briefly described this at the end of a problem set.
The companion package RTutorSAGI contains tools to combine all submission files for grading purposes. Take a look at its README.md file for details.
As a teacher, you may just distribute problem sets as ZIP files to your students and ask them to solve at home and then submit the solutions (see explanation above).
It can also be very convenient to host RTutor problem sets in the rstudio cloud. Take a look at my blog entry for details.
You can also create an R package that contains the problem set and host it on Github. This is described in more detail in this vignette:
My students who created RTutor problem sets that allow to interactively replicate economic articles typically put their problem sets on Github and many also on shinyapps.io.
You can also host web-based problem sets on shinyapps.io. Users can then solve them without having to install R. This is explained in this vignette: https://github.com/skranz/RTutor/blob/master/vignettes/Deploy%20problem%20set%20on%20shinyapps.io.Rmd
In principle, you could also host the problem set as an app on your own shiny server. However, this seems a substantial security risk since users can run arbitrary R code, which allows them to access your file system and generate disaster. This problem can probably be overcome if you spin up a separate docker container for each student instance, but I have not implemented such a scheme.
I guess for the first version the most natural way to develop a problem set is to repeatedly perform the following 3 steps:
To improve problem sets used in courses where students submit solutions take a look at the README of https://github.com/skranz/RTutorSAGI
Distributing the problem set for RStudio use is simple: just give your students the structure file as .rps and the empty problem set as .rmd file and tell them to install RStudio and all packages as described above. Students can then go on solving the problem set. You can also ask them to upload the solutions and possible the log files that track their solution process.
It is planned to implement more functionality that facilitates grading. The goal is to put all solutions in a directory and quickly generate tables that show the total percentage solved for all students.
You can also create an R package that contains the problem set and host it on Github. This is described in more detail in this manual
You can also host web-based problem sets on shinyapps.io. Users can then solve them without having to install R. This is explained in this manual
In principle, you could also host the problem set as an app on your own shiny server. However, this seems a substantial security risk since users can run arbitrary R code. This could lead to desaster if you don’t carefully restrict access. This problem can probably be overcome if you spin up a separate docker container with limited rights for each student instance, but I have not implemented such a scheme. Shiny proxy may be helpful in this regard.
Most documentation can be found under Manuals on the RTutor page: https://skranz.github.io/RTutor.
In addition I wrote a PDF Guide for students who want to create an RTutor problem set about an economics article in their Bachelor or Master thesis.
Here is a PDF guide I give to students in my courses where RStudio based RTutor problem sets have to be solved. It provides some tips of how to deal with problems that might arise.