3

I have created a "book" using bookdown. I would love to be able to add interactive quizzes, without needing shiny etc.

Is it possible using R/exams (http://www.R-exams.org/) with bookdown? I'm mainly interested in the HTML output; PDF output a bonus but hardly essential. The web page offers promise:

Based on (potentially) dynamic exercise templates large numbers of personalized exams/quizzes/tests can be created for various systems: [...] and the possibility to create custom output (in PDF, HTML, Docx, ...).

Exercise types include multiple-choice or single-choice questions, numeric or text answers, or combinations of these. Formatting can be done either in Markdown or LaTeX with the possibility to generate dynamic content using R, e.g., random numbers, graphics, data sets, or shuffled text blocks.

It sounds great. Does anyone know if it is possible to use exams with bookdown (even if just some features)?

If it is possible: how? Any pointers?

If it is not possible: does anyone know a way to do something similar?

1
  • It's relatively straightforward to write a custom function that prepares a given exercise to be embedded in a given Markdown or HTML document. I'll post something about this later today when I have more time. What I don't know, though: What can be done in bookdown to make the exercise interactive. I guess some basic stuff should be possible with Javascript but I have never looked at this and whether there arr solutions readily available. If anybody has pointers re this, I would be interested. Jun 11, 2020 at 8:04

2 Answers 2

7

General remarks

R/exams is indeed extensible leveraging its building blocks is relatively easy. The workhorse function underlying all the exams2xyz() interfaces is called xexams(). It proceeds in four steps:

  1. sweave: The exercise files are copied to a temporary directory and then run through R, by default using xweave() which provides a unified convenience interface to utils::Sweave() (for Rnw files) and knitr::knit() (for Rmd files).
  2. read: The resulting weaved files are read into R, by default using read_exercise(). For each exercise this yields a list of question, questionlist, solution, solutionlist, metainfo, and supplements. All elements are always there but may be empty, e.g., when there is no solution environment provided in the exercise or when there are no supplementary files.
  3. transform: By default this is empty but can be used to transform the exercise list elements above to a desired format, e.g., HTML.
  4. write: By default this is empty, but can be used to write out results for each of the n replications of the exam.

Embedding exercise texts in Markdown

When you write your exercises in R/Markdown (Rmd) files you can easily run them through xexams() to get some randomized version of them. As an example, let's consider the numeric (num) and single-choice (schoice) version of the derivative exercise, see: deriv, deriv2. Using 1 as the random seed, the numeric exercise has the following question along with the correct solution and tolerance:

set.seed(1)
d1 <- xexams("deriv.Rmd")[[1]][[1]]
d1$question
## [1] "What is the derivative of $f(x) = x^{2} e^{2.3 x}$, evaluated at $x = 0.56$?"
d1$metainfo$solution
## [1] 6.68
d1$metainfo$tolerance
## [1] 0.01

The reason for the [[1]][[1]] index is that this is from the first (and only) exam, the first (and only) exercise. If you generate, say, xexams(..., n = 3) then the first index could be in 1, 2, 3. Similarly, you could inlude more than one exercise if you want.

The single-choice version has

set.seed(1)
d2 <- xexams("deriv2.Rmd")[[1]][[1]]
d2$question
## [1] "What is the derivative of $f(x) = x^{2} e^{2.3 x}$, evaluated at $x = 0.66$?"
## [2] ""                                                                            
d2$questionlist
## [1] "$8.01$"  "$14.09$" "$10.59$" "$15.35$" "$6.02$" 
d2$metainfo$solution
## [1] FALSE FALSE  TRUE FALSE FALSE

Both of these would be very easy to integrate as static text into any R/Markdown document.

Embedding exercise texts in webex

To turn the static text into a dynamic element in HTML, e.g., a text field where readers could enter a number which is then compared with the reference value from the solution, it is possible to employ Javascript for example. One lightweight R-based framework for generating such output is the webex package by Dale Barr and Lisa DeBruine.

In webex you can create fill-in-the-blank interactions via fitb() for numeric solutions with an optional tolerance (num in R/exams) or for character solutions (string in R/exams). Also, you can create drop-down menu interactions via mcq() for single-choice questions (schoice in R/exams). (Note: The jargon regarding choice questions is not unified: What R/exams calls single-choice is also referred to as multiple-choice. In this case multiple-answer is often used for what R/exams calls multiple-choice.)

At the moment, webex does not support radio buttons as an alternative to drop-down menus. Also, check-boxes for multiple-choice (aka multiple-answer) questions is not available.

Below, I illustrate how to embed simple schoice, num, and string questions in webex. For more elaborate examples with supplementary files, see the comments below. Also, cloze would also be doable but take some more work.

---
title: "Web Exercises with R/exams & webex"
output: webex::webex_default
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(echo = TRUE)
library("webex")
library("exams")
```

`r style_widgets("#DF536B", "#61D04F")`

## `schoice`

```{r swisscapital, echo = FALSE, results = "asis"}
x <- xexams("swisscapital.Rmd")[[1]][[1]]
names(x$questionlist) <- ifelse(x$metainfo$solution, "answer", "")

x <- c(
  x$question,
  "",
  mcq(x$questionlist),
  "",
  hide("Correct solution"),
  "",
  x$solution,
  "",
  paste("*", x$solutionlist),
  "",
  unhide()
)
writeLines(x)
```

## `num`

```{r deriv, echo = FALSE, results = "asis"}
x <- xexams("deriv.Rmd")[[1]][[1]]

x <- c(
  x$question,
  "",
  fitb(x$metainfo$solution, tol = x$metainfo$tol,
    width = min(100, max(20, nchar(x$metainfo$solution)))),
  "",
  hide("Correct solution"),
  "",
  x$solution,
  "",
  unhide()
)
writeLines(x)
```

## `string`

```{r function, echo = FALSE, results = "asis"}
x <- xexams("function.Rmd")[[1]][[1]]

x <- c(
  x$question,
  "",
  fitb(x$metainfo$solution, width = min(100, max(20, nchar(x$metainfo$solution)))),
  "",
  hide("Correct solution"),
  "",
  x$solution,
  "",
  unhide()
)
writeLines(x)
```

Rendering this with rmarkdown::render() gives you a file like shown in the screenshot below. When embedding this in bookdown you need to make sure to embed the webex.css and webex.js from the package.

webex

Further variations

Some extra work is involved when processing exercises that contain images such as boxplots. The default in xexams() is set up for PDF output but the driver$sweave can be tweaked to produce PNG output. In either case, the supplements is then a vector of file paths to the supplementary files:

set.seed(1)
b1 <- xexams("boxplots.Rmd", driver = list(sweave = list(png = TRUE)))[[1]][[1]]
b1$question
## [1] "In the following figure the distributions of a variable"             
## [2] "given by two samples (A and B) are represented by parallel boxplots."
## [3] "Which of the following statements are correct?  _(Comment: The"      
## [4] "statements are either about correct or clearly wrong.)_"             
## [5] "\\"                                                                  
## [6] "![](boxplot-1.png)"                                                  
## [7] ""                                                                    
b1$supplements
##                                                      boxplot-1.png 
## "/tmp/RtmpA07Hau/file11d77d212e69bf/exam1/exercise1/boxplot-1.png" 
## attr(,"dir")
## [1] "/tmp/RtmpA07Hau/file11d77d212e69bf/exam1/exercise1"

Additionally, you can set up a transform driver that converts the R/Markdown already to HTML (rather than having bookdown doing this later on). Here I'm selecting pandoc as the converter, using MathJax for the rendering of mathematical content (like bookdown does as well). Using base64 = TRUE instead of the FALSE below would embed the supplementary PNG image directly in the HTML code using a Base 64 encoding.

set.seed(1)
htmltrafo <- make_exercise_transform_html(converter = "pandoc-mathjax", base64 = FALSE)
b2 <- xexams("boxplots.Rmd", driver = list(sweave = list(png = TRUE), transform = htmltrafo))[[1]][[1]]
b2$question
## [1] "<p>In the following figure the distributions of a variable given by two samples (A and B) are represented by parallel boxplots. Which of the following statements are correct? <em>(Comment: The statements are either about correct or clearly wrong.)</em><br />"
## [2] "<img src=\"boxplot-1.png\" /></p>"                                         
3
  • Thanks heaps Achim. One thing I would really appreciate is the "What I don't know" that you list: essentially, how to give feedback. I have coerced the R package webex ( CRAN.R-project.org/package=webex) to work in bookdown, but it has restricted question types. It does, however, allow students to enter answers to get feedback...
    – Pete
    Jun 15, 2020 at 2:44
  • Ah, nice! I've updated my answer to include a worked webex example. I'll also reach out to the webex authors to see whether we can get support for radio buttons and check boxes. And maybe they would be interested in a exams2webex() command. Jun 15, 2020 at 8:28
  • 1
    I have started a discussion at twitter.com/AchimZeileis/status/1272449487873757186 and will also report back here if there is progress on that. But I hope the current answer should be useful enough to close the issue here on SO? Jun 16, 2020 at 2:17
2

This is Great Achim. I was struggling to find a way to make bookdown talk to exam exercise files and found similar solution before reaching this post. The main difference is that I'm using bootstrap 4 (bookdown::bs4_book) in the html, which looks nicer.

This is how it looks in the Rmarkdown chapter file:

f_in <- fs::dir_ls('00-EOCE-Rmd/Cap08-Programação/', 
                   type = 'file')

build_exercises(f_in, type_doc = my_engine)

The result:

enter image description here

2

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.