Creating Tutorials with learnr & webexercises

Creating tutorials with learnr and webexercises

In this document, we will outline how to create interactive tutorials for learning materials using the learnr and webexercises. If you are new to R in general, or would like to get a feel for the type of tutorials and labs that can be created, we have some example labs for you to explore here:

learnr tutorials

• Exploring data in R
• Simple linear regression
• Inference for Numerical Data (and Optional RStudio)

webexercises tutorials

• Introduction to R and RStudio
• Inference for numerical data
• Simple linear regression

If you are interested in how to create these tutorials for yourself, please read the below sections.

Using RMarkdown for writing course materials

You might be used to running analyses in R (or some other software) and then copying and pasting the results (tables, plots, etc.) into a report written in Microsoft Word (or other software).

Though this might seem to be the simplest and quickest way of putting together a report, there are good reasons to move to a more unified (and more reproducible) way of producing reports.

• First of all, you might make mistakes when copying and pasting (or even retyping) the results into the Word document.
• Updating the report to take into account additions to or changes in the data can be a long process if you have replaced all the results you have copied into the document. The same applies if you find a mistake in your code and you need to rerun your analyses.
• If you want your report to be reproducible (by others or future you) you need to archive the R script that you have used to generate the report together with the report.

RMarkdown provides a tool to “weave” R code into rich text documents (and has been used to create these notes!). Not only does RMarkdown behave like a standard text editor, you can also incorporate LaTeX into an RMarkdown:

\[y = X\beta + \epsilon \] LaTeX in RMarkdown works in the same way as standard TeX, and the same conventions follow. The sample TeX used for the equation above is shown below:

Using LaTeX in RMarkdown

Generating interactive web-based exercises with learnr

The learnr package can help us incorporate interactive tutorials into a worksheet, which contain an embedded R console for students to work through, without having to use R directly. Tutorials can contain various elements, such as code exercises with hints included, quiz questions and interactive elements using the shiny package.

We will cover some of the basics of learnr here, but we thoroughly recommend reading the articles on the package information page, which includes information on advanced features and lots of examples. You can access these here.

Setting up learnr

Firstly, make sure you have installed the learnr package on your version of R. In order to create tutorials which use learnrcomponents, you will have to use an RMarkdown document (for those of you who have not used RMarkdown before, this allows us to integrate R code into a text based document. You can find more information on RMarkdown here).

To open a new learnr RMarkdown document, go to:

File > New file > R Markdown…

A dialog box will then open which will look like the following

learnr tutorial window

Select the Interactive Tutorial option. You can name the tutorial and set the location you would like to save it in. It is best to save your tutorials in their own folder.

Once opened, you will have a template tutorial to work from which contains some sample learnr material. At the top of the document, you will see a heading like the one shown below:

YAML data to generate a learnr tutorial

This is called YAML metadata, and tells RMarkdown what document to make. The only component here you will need to change is the title, which you can change to what you wish.

Creating interactive R consoles

Any time we wish to include an interactive R console in our document for a particular question, we must use the following syntax below to create a code chunk:

Sample code chunk for learnr tutorial

Firstly, we write our question in plain text as shown above. To open a learnr console to use to answer the question, we create a code chunk like shown above. Within the {}, we first specify the argument r to set up an R based coding window. Our second command is the label for our code chunk, which here is named two-times-five. It is important this is included so each interactive component is identified. exercise=TRUE should be included also so this becomes an interactive component. If we drop this part, this will just show the R code as text which can be copied across to R if you wish.

Once compiled, the tutorial will show a display like the one shown below:

Sample output in tutorial

Adding hints and solutions

When creating questions using learnr, it is possible to provide a series of coding hints to help students work through a problem. You can add separate code chunks by adding the prefix -hint to the tag used for the original chunk. For example, if we use our previous example two-times-five, this would correspond to two-times-five-hint. Within this coding chunk, you would simply supply the code that provides the hint below your initial chunk of code. In our RMarkdown document, this would look something like this:

Sample code chunk with hint for learnr tutorial

This will then include the hint to your code chunk question. In the published tutorial, the hint will now be available to view as follows:

Sample output in tutorial with hint

You can add multiple hints for one question using a sequence of indexed chunks, such as exercise-hint-1, exercise-hint-2 and so on.

Solutions can be provided too in a similar fashion, using the chunk label -solution e.g. exercise1-solution.

Creating questions

You can include multiple choice questions within your tutorial. Questions can either have single or multiple correct answers. Questions take the following form:

question("What is 1+1?",
  answer("1"),
  answer("2",correct=TRUE),
  answer("3"),
  answer("4")
  )

The general syntax to create a question is to use the question() function, and first specify your question as a string. Following this, we specify the multiple answers we want to specify using the answer() function within the question() function. To highlight the correct answer, specify correct=TRUE within the correct answer option. You can add multiple answers by using multiple correct=TRUE arguments.

You can also add in specific messages for correct and incorrect answers using the message option. This will produce a message once the user has provided an answer.

question("What is 1+1?",
  answer("1"),
  answer("2",correct=TRUE,message="Yes, 1+1 = 2"),
  answer("3"),
  answer("4")
  )

Example learnr document

We have created a sample learnr tutorial you can download and run, this will allow you to explore the features that can be used, and you can edit this file as you wish. The file can be downloaded here.

Sharing learnr tutorials

Once you have created your learnr tutorial, you can deploy this online using shinyapps. Shinyapps is an online web hosting platform for hosting Shiny applications (more information on Shiny here). In order to deploy your app, you will have to create an account at shinyapps.io and then link your account to your local RStudio. There are detailed instructions on how to do this here.

Once you have compiled your document using the Run Document button, a pop-up will appear with the document content. In the top right corner, you will see a “Publish” button like the one below

Publish your tutorial

Once you have clicked on this button, a dialog screen will open like the one shown below:

Deploy your tutorial

Select the relevant account you would like to publish with on the right hand pane, and make sure all files are selected and then press “Publish”. Your tutorial will then be deployed to your shinyapps account where you can obtain the URL to be shared with students to access the materials.

A free shinyapps account will allow you to have 5 applications running and deployed at one time. If you wish to have multiple applications, you will need to consider a paid subscription.

Creating questions with webexercises

The process for setting up a learnr lab for sharing with students is more involved and can be limited by the potential costs of using shinyapps. An alternative to learnr for interactive tutorials is the webexercises library, which has been developed by the psyteachR team at the University of Glasgow School of Psychology and Neuroscience.

The webexercises library enables us to create interactive HTML based documents that students can use for self-guided learning. The library allows us to incorporate interactive quiz based elements within a tutorial document and provide sample code.

Using webexercises is easier for sharing and implementation than learnr as only HTML files are produced, and there is no need to use a Shiny server for hosting. This approach will require that learners must work directly in RStudio, as we cannot implement in-built coding windows for use within the learning material.

Setting up a webexercises document

We can create a tutorial with webexercises features by using an RMarkdown document like our previous example. Make sure you have webexercises installed on your device.

To open a new learnr RMarkdown document, go to:

File > New file > R Markdown…

A dialog box will then open which will look like the following

webexercises tutorial window

Select the Web Exercises option. You can name the tutorial and set the location you would like to save it in. It is best to save your tutorials in their own folder.

Once opened, you will have a template tutorial to work from which contains some sample webexercises examples. At the top of the document, you will see a heading like the one shown below:

YAML data to generate a webexercises tutorial

This is called YAML metadata, and tells RMarkdown what document to make. The only component here you will need to change is the title, which you can change to what you wish. If you open a blank RMarkdown document, you will need to add the details in the output tab.

There are alternative setup approaches for creating webexercises, such as Quarto and Bookdown. Bookdown in particular is useful if you wish to create materials split over multiple units (like a book). You can find instructions on how to setup for these alternative formats here. More information on Bookdown can be found here.

Creating interactive question types

There are several question types we can construct using webexercises. These questions are of the following form:

Function	Element	Description
fitb()	text box	fill in the blank question
mcq()	pull-down menu	multiple choice question
torf()	pull-down menu	True or False question
longmcq()	radio buttons	MCQ’s with long answers
hide() & unhide()	button	Solution revealed when clicked

The webexercises tutorial document here contains several examples on how you can implement these question types. Try to work through these examples now and make some edits to the sample questions to get a feel for how webexercises works.

Sharing webexercises tutorials

As a webexercises document is self contained within an HTML file, you can simply share the final HTML file to learners.

If you are producing units of notes using bookdown, it is possible to host this document using Github pages. If you are interested in how to share such files in this way, please let us know and we can provide further information.