Overview

The basic idea of R/exams is to have a one-for-all exams generator where each exercise is a standalone file, so that the same exercise can be rendered easily into a variety output formats such as e-learning systems or written exams. To reduce the risk of cheating, R/exams offers different mechanisms for drawing random variations of exercises:

• Randomly selecting one (or more) out of a set of exercises for each participant.
• Randomly shuffling answer alternatives in single-choice and multiple-choice questions.
• Randomly selecting numbers, text blocks, graphics, etc. using the R programming language.

Each exercise (or rather “exercise template”) is a standalone file with up to four elements:

1. Data-generating process in R.
2. Question text.
3. Solution text.
4. Meta-information: Type of question (single-choice, multiple-choice, numeric, string, or combinations thereof), correct solution, a name/label, etc.

Only the question (2) and the meta-information (4) are mandatory while data generation (1) and solution (3) are optional. Solutions can be used to either inform teachers about the correct solution for some randomly drawn exercise – or for giving students feedback about how to solve a given exercise. Programming a good data-generating process is often the hardest part of authoring a new dynamic exercise but is, of course, crucial for drawing a very large number of random variations.

For formatting the text within question/solution (e.g., italics, bold face, lists, etc.) two options are available: Markdown or LaTeX. The former is very easy to learn and recommended for authors who do not know LaTeX yet. If mathematic notation and formulas are needed, then LaTeX can be used – either within a LaTeX or also within a Markdown question. The file suffix for R/Markdown is .Rmd while .Rnw is conventionally used for R/LaTeX, known as Sweave.

In the following, a first session should help new R/exams users to explore the materials available and get a feeling for the workflow. Furthremore, two exercise templates are shown in more detail:

• swisscapital: A static single-choice knowledge quiz question where the only randomization is a subsampling of the presented alternatives.
• deriv: A dynamic airthmetic question about the product rule for derivatives where various numbers are drawn randomly in R.

A first session

To explore what is available in R/exams two things are necessary: a couple of exercise templates to draw inspiration from, and some demo R scripts that illustrate how the different exams2xyz() functions can produce output in a variety of formats. (Here, xyz is a placeholder for the output format like html, pdf, moodle, etc.) The function exams_skeleton() is a helper function that generates exactly these materials in a specified folder. For example, when exams has already been installed, the following can be carried out in R:

library("exams")
exams_skeleton(markup = "markdown", encoding = "UTF-8",
  writer = c("exams2html", "exams2pdf", "exams2moodle"))

This copies all R/Markdown files to the current working directory along with demo scripts, illustrating the usage of exams2html() and exams2pdf() for customizable HTML and PDF output, respectively, along with Moodle output via exams2moodle(). Specifically, the working directory then contains:

dir()
## [1] "demo-all.R"    "demo-html.R"   "demo-moodle.R" "demo-pdf.R"   
## [5] "exercises"     "templates"

Simply open the demo script demo-all.R for the first steps and then continue with more details in demo-html.R, demo-pdf.R, or demo-moodle.R, respectively. More information about all the exercises can be found in the exercise template gallery online.

Single-choice: Swiss capital

Knowledge quiz question (about the Swiss capital) with 1 correct and 6 false alternative. 4 out of the 6 false alternatives are sampled randomly and shuffled. Otherwise the exercise is static and contains no R code. Below the structure of the exercise is highlighted side-by-side in both .Rmd and .Rnw, illustrating that the additional exercise markup is similar in spirit to the respective typesetting system.

To see what the output looks like, run the following code within R or take a look at swisscapital in the exercise gallery.

Markdown

LaTeX

library("exams")
exams2html("swisscapital.Rmd")
exams2pdf("swisscapital.Rmd")
    

library("exams")
exams2html("swisscapital.Rnw")
exams2pdf("swisscapital.Rnw")
    

Question

The question is straightforward and lists 7 answer alternatives. The correct solution (Bern) is declared in the meta-information below.

Question
========
What is the seat of the federal
authorities in Switzerland
(i.e., the de facto capital)?

Answerlist
----------
* Basel
* Bern
* Geneva
* Lausanne
* Zurich
* St. Gallen
* Vaduz
    

\begin{question}
What is the seat of the federal
authorities in Switzerland
(i.e., the de facto capital)?

\begin{answerlist}
  \item Basel
  \item Bern
  \item Geneva
  \item Lausanne
  \item Zurich
  \item St.~Gallen
  \item Vaduz
\end{answerlist}
\end{question}
    

Solution

The optional solution can provide some general feedback (that explains why Bern is correct in this question) as well as more details for each answer alternative (only listing true/false here). It is also possible to have no solution, or just a general text, or just the answer list.

Solution
========
There is no de jure capital but
the de facto capital and seat of
the federal authorities is Bern.

Answerlist
----------
* False
* True
* False
* False
* False
* False
* False
    

\begin{solution}
There is no de jure capital but
the de facto capital and seat of
the federal authorities is Bern.

\begin{answerlist}
  \item False.
  \item True.
  \item False.
  \item False.
  \item False.
  \item False.
  \item False.
\end{answerlist}
\end{solution}
    

Meta-information

In the meta-information, each exercise must specify at least an extype, and an exsolution, and should typically also have a short descriptive exname. The type for single-choice questions is schoice and the exsolution is simply a binary coding of the 7 answer alternatives. For randomization, additionally exshuffle is set to 5 so that 1 correct and 4 random wrong alternatives are subsampled and shuffled.

Meta-information
================
exname: Swiss Capital
extype: schoice
exsolution: 0100000
exshuffle: 5
    

\exname{Swiss Capital}
\extype{schoice}
\exsolution{0100000}
\exshuffle{5}
    

Numeric: Product rule for derivatives

Arithmetic question for computing the first derivative of a product function with two factors, using the product rule. The parameters of the function are drawn randomly in R and subsequently inserted into the question and the solution (which is not shown below for brevity). LaTeX is used for typesetting the mathematical formulas – both in the Markdown and the LaTeX version.

To see what the output looks like, run the following code within R or take a look at deriv in the exercise gallery.

R/Markdown

R/LaTeX

library("exams")
exams2html("deriv.Rmd")
exams2pdf("deriv.Rmd")
    

library("exams")
exams2html("deriv.Rnw")
exams2pdf("deriv.Rnw")
    

Data generation

The R code simply draws the two parameters a and b as well as the argument c from a discrete uniform distribution. (See the question below for the actual function used.) Subsequently, the random numbers are inserted into the correct solution and storing it as res.

```{r, echo=FALSE, results="hide"}
## parameters
a <- sample(2:9, 1)
b <- sample(seq(2, 4, 0.1), 1)
c <- sample(seq(0.5, 0.8, 0.01), 1)
## solution
res <- exp(b * c) * (a * c^(a-1) +
       b * c^a)
```
    

<<echo=FALSE, results=hide>>=
## parameters
a <- sample(2:9, 1)
b <- sample(seq(2, 4, 0.1), 1)
c <- sample(seq(0.5, 0.8, 0.01), 1)
## solution
res <- exp(b * c) * (a * c^(a-1) +
       b * c^a)
@
    

Question

The question asks for the derivative of a particular function and simply inserts the parameters drawn above into the question template. (The solution is set up analogously in the exercise template but not shown here for brevity.)

Question
========
What is the derivative of
$f(x) = x^{6} e^{3.3 x}$,
evaluated at $x = 0.79$?
    

\begin{question}
What is the derivative of
$f(x) = x^{\Sexpr{a}} e^{\Sexpr{b}x}$,
evaluated at $x = \Sexpr{c}$?
\end{question}
    

Meta-information

Again, the meta-information lists extype (which is num for numeric exercises), exsolution (which is inserted dynamically from the variable res computed above), and a short exname. Additionally, the tolerance extol which is used for automatically evaluating answers, e.g., in an online test/exam.

Meta-information
================
extype: num
exsolution: `r fmt(res)`
exname: derivative exp
extol: 0.01
    

\extype{num}
\exsolution{\Sexpr{fmt(res)}}
\exname{derivative exp}
\extol{0.01}