8 Teaching with R
R, RStudio and GitHub provide tools for teaching.
The learnr package allows you to make interactive tutorials.
We will also see how to use GitHub Classrooms which allow to distribute to a class (a list of students with a GitHub account) a repository model (a draft of an R project) that each student will have to develop and publish. The classroom tools allow to evaluate the work done quite easily.
8.1 learnr
learnr allows you to make code snippets of any document produced by R Markdown in HTML interactive, by transforming them into Shiny applications. The documentation on the RStudio website123 is very clear and will not be repeated here: we will only see how to start and how to distribute the tutorials.
8.1.1 First tutorial
With the menu “File > New File > RMarkdown…” create a new document from an “Interactive Tutorial” template. The wizard creates a folder with the chosen name, to be transformed into an R project and put under source control, as for all documents seen previously (see section 4.3.2).
To run the tutorial, click on the “Run Document” button, which is in the usual place of the “Knit” button.
Tutorials can include exercises, which are code snippets with the exercise=TRUE option.
These exercises are displayed as a window of code that can be edited and executed by the user.
Hints can be given124, a button added to display the solution, a time limit can be set125, and both the code and its result can be compared to an expected value126.
Quizzes127 can be added, in the form of multiple or single choice quizzes.
The user’s progress in the tutorial (code entered, answers to questions…) is saved by learnr on the workstation. A tutorial can be stopped and resumed without loss of data. On the other hand, there is no easy way to recover this data for an evaluation by the trainer for example.
8.2 GitHub Classrooms
GitHub Classrooms allows to distribute to a student audience GitHub repositories to modify and control the result. The applications are as well the learning of R as the production of documents, for a personal work or an exam for example.
8.2.1 Registration
To start using the tool, you need to open an account. On the GitHub Classrooms website129, click on “Sign in” and use your GitHub account to authenticate.
8.2.2 Organizations
The next step is to create a GitHub organization.
A GitHub organization basically contains members (GitHub account holders) and repositories that can be accessed at https://github.com/
The simplest way to work is to create an organization per course, but other approaches are possible in structures that use the tool extensively. The organization created for the example here is “Cours-R”130.
An email address is required (use the same as that of your GitHub account) and the organization must be declared as belonging to your personal account.
If the organization is not visible on the GitHub Classrooms page, click on “Grant us access”.
8.2.3 New Classroom
A classroom is populated with students who will receive tasks to perform.
Click on New Classroom. Select the organization in charge of administering the classroom.
Enter the name of the classroom: a good practice is to prefix it with the name of the course and add the name of the session, for example “Cours-R-2020”.
Do not add collaborators (this will be possible later), and eventually enter the list of students (one name per line, also possible later). The class is created.
All classrooms are visible from the GitHub Classrooms homepage131. Click on a name to open one. The “Settings” button allows to change its name or to delete it. The “TAs and Admins” button allows you to add collaborators, i.e. other GitHub users who will be able to administer the classroom.
The “Students” button allows to add students. The list of names is free, with no mandatory format. Click on “Create Roster” to activate it. The names must then be linked to GitHub accounts: this work can be done by the administrator or by the students themselves when they receive the first task to be done. Each student must have an account on GitHub.
8.2.4 Prepare a repository template
A task is a GitHub repository to modify. For example132, create a repository containing an R project with a Markdown file describing the work to be done and possibly some of the code needed to do it, the other files in the R Markdown template used and a data file.
Open the repository properties on GitHub and check the Template Repository box to make it a template.
8.2.4.1 Assign a task
Open a classroom and click on “New Assignment”.
Enter an explicit title for the students, an optional deadline and choose “Individual Assignment”.
By default, the assignment name is used as a prefix for the students’ submission names, but it can be replaced by a prefix of your choice. When students turn in their work, all repositories for all tasks will be stored in the organization.
The repository created on each student’s account can be private or public, depending on whether you want students to be able to see each other’s work or not. Give the administration right and make the site public if the students should be able to activate GitHub pages to present the results of their work. Click on “Continue”.
Select the model repository (starter code) then click on “Continue” then “Create Assignment”.
The new task is created. It is associated with an invitation link that must be copied and sent to the students. When they click on the link, they will reach a GitHub page that will allow them to associate their account with a name in the list (no control is possible: the first one connected can associate with any name). They will then be able to create a new RStudio project from the GitHub repository automatically created by GitHub Classrooms, modify that project according to the work instructions and push it to GitHub. The repository is on the account of the organization the class is connected to, and is suffixed with the student’s GitHub ID.
8.2.4.2 Controlling student work
It is possible to view each repository created by students from the assignment page on GitHub Classrooms. If the assignment to be produced is a written document, have students place it in the repository’s GitHub pages to read it directly online.
The GitHub Classrooms wizard133 allows you to download all student repositories at once to correct them on your workstation.