05_Deploy Problem Sets as Package on Github.Rmd
Once you have created and tested one or several RTutor problem sets, you want to distribute them to users. There are different ways for doing so.
Just provide the users a zip file that contains the .rps, and for RMarkdown based problem sets the .rmd file, as well as needed data sets. Let users manually extract those files in their working directory. It can also be nice to put everything into a folder to which you add a RStudio project file, and then zip the folder.
Create an R package that contains one or more problem sets (including supplementary data) and host it on Github or CRAN.
Host the problem set directly in the web using shinyapps.io or another web server that runs shiny server.
This vignette describes the second option.
This process describes how to create an R package for your problem set. Currently the infrastructure is designed for Shiny-based problem sets, but it can also be extended to RMarkdown-based problem sets.
The RTutor package has a function
rtutor.package.skel that creates a package skeleton for a problem set package. You first need to call
create.ps to create all problem set files from your solution files. Here is an example:
# Working folder that contains your solution file setwd("D:/libraries/RTutor/examples") # First generate your problem set in the usual manner ps.name = "Example"; sol.file = paste0(ps.name,"_sol.Rmd") libs = c() # character vector of all packages you load in the problem set create.ps(sol.file=sol.file, ps.name=ps.name, user.name=NULL,libs=libs, stop.when.finished=FALSE) # This function creates a skeleton for your problem set package rtutor.package.skel(sol.file=sol.file, ps.name=ps.name,libs=libs, pkg.name="RTutorExample", # Name of the problem set package pkg.parent.dir = "D:/libraries/RTutorExample", # Parent directory author="Sebastian Kranz", # Your name github.user="skranz", # Your github user name extra.code.file=NULL, # name of extra.code.file var.txt.file=NULL, # name of var.txt.file overwrite=FALSE # Do you want to override if package directory exists? )
The call to
rtutor.package.skel creates a package folder with your package name below the specified pkg.parent.dir folder. In your example above, the created package folder would be
(Note: I personally often find it convenient to put the package as a subfolder of a folder with the same name. This allows me to store in the parent directory, here
D:/libraries/RTutorExample/, files that I locally use, e.g. for testing something out, but that shall not be part of the Github project.)
It would be good to have a package name of the Form “RTutorXXX”. To quickly identify RTutor problem set packages. Please don’t use any special characters, nor spaces in your package name. If your name consists of words, use the Camel case conventiton to separate them, e.g. “RTutorBankRuns”. Don’t choose a package name that is too long.
Now create in RStudio a new package project for your folder using the menus:
File -> New Project … -> Existing Directory
Chose as project folder your package folder, e.g. in our example, we would choose the folder
See also the description here:
If you want to distribute the data sets used in your problem set directly with your problem sets, copy those data sets into the following subfolder of your package folder:
Also take a look at the /inst/ps/problemset_name folder. It should contain at least the .rps, _sol.rmd file. If your problem set uses an extra.code.file or var.text.file, those files should also be there, to be able to rebuild the .rps file from the solution file.
If you want to avoid that students can easily access the solution, you have to remove the _sol.rmd file from the /inst/ps/problemset_name folder. The drawback is that then the problem set cannot be changed or rebuild from source by other researchers. Also make sure that you set the argument
rps.has.sol = FALSE in your call to
create.ps, since otherwise a sample solution can be created from the .rps file.
Edit the file “DESCRIPTION” - generate or update the problem set description / title - check the DATE and possibly update it - check and correct your name and email in the AUTHOR and MAINTAINER fields - check whether you agree with the licences and possibly adapt them - Here is an overview of different types of Creative Commons licenses:
Edit the file “README.MD” - Add a brief description (2-3 lines) of the problem set.
Try to build the package with RStudio with the menu point
Build -> Build and Reload
A package can contain more than one problem set. Currently
rtutor.package.skel only generates a package structure for a single problem set. Adding more problem sets requires manual adaption of the package.
The R folder of your new package contains a file
package_info.r that has a content similar as follows:
If you want to have several problem sets, you must adapt the line
ps = c("Example"). Say we want to add a second problem set “Example2”. We then must write
You manually have to create a folder for your new problem set under inst/ps. For example if we add a problem set
Example2, you need to create the folders
In the first folder, you copy your .rps file (and if you like other .rmd files like your solution file). In the material subfolder you copy data sets that your problem set uses.
You finally should adapt the file README.MD to make the user aware of the multiple problem sets. In particular the command
run.ps needs to specify the name of the problem set if another than the first problem set shall be run, e.g.
If you want to update the problem sets in your package, simple copy manually the new files into the problem set folder under /inst/ps. Then build your new package, test it and upload the changes to Github. There is no need to create the whole package with the package skeleton again.
It is easiest to distribute your package if you host it as an open source project on Github.
There are different ways to host your package on Github. I just describe the way I use on Windows.
An alternative way to use Github is described here: http://r-pkgs.had.co.nz/git.html
Create a user account on Github by signing up here: https://github.com/
If you use Windows install and start Github for Windows as explained here:
To add your package folder as github repository open github for windows and your windows explorer and drag’n’drop your package folder from the explorer on the left your github for windows window. See
After you have created your github project or you have changed it, you can commit your changes and then synchronize your local changes with the Github version. See here:
Check whether you can see your package on the github webpage, as a repository under your username.
Check whether your package can be installed and run from Github in the way described in the README.md file.