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:
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).
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.
transform
: By default this is empty but can be used to transform the exercise list elements above to a desired format, e.g., HTML.
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.

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] ""
## [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>"