**R/exams**, and kindly contributed to R-bloggers)

## 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:

- Data-generating process in R.
- Question text.
- Solution text.
- 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.

**Markdown**

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

**LaTeX**

\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*.

**Markdown**

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

**LaTeX**

\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.

**Markdown**

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

**LaTeX**

\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/Markdown**

```{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) ```

**R/LaTeX**

<>= ## 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.)

**R/Markdown**

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

**R/LaTeX**

\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.

**R/Markdown**

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

**R/LaTeX**

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

**leave a comment**for the author, please follow the link and comment on their blog:

**R/exams**.

R-bloggers.com offers

**daily e-mail updates**about R news and tutorials on topics such as: Data science, Big Data, R jobs, visualization (ggplot2, Boxplots, maps, animation), programming (RStudio, Sweave, LaTeX, SQL, Eclipse, git, hadoop, Web Scraping) statistics (regression, PCA, time series, trading) and more...