First Steps

September 9, 2017
By

(This article was first published on 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:

  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
Rmd

LaTeX
Rnw

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
Rmd

R/LaTeX
Rnw

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}
    

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



If you got this far, why not subscribe for updates from the site? Choose your flavor: e-mail, twitter, RSS, or facebook...

Comments are closed.

Search R-bloggers

Sponsors

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)