# First Steps

First overview of the structure of R/exams, its exercise templates, and a first hands-on session.

## 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. Furthermore, 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**

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

**R/Markdown**

Question ======== What is the derivative of $f(x) = x^{`r a`} e^{`r b` x}$, evaluated at $x = `r c`$?

**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}