Package 'exams'

Generation of Simple Exams

Description

Old (version 1) interface for Sweave-based automatic generation of exams including multiple choice questions and arithmetic problems. Now it is recommended to use the (version 2) interface exams2pdf.

Usage

exams(file, n = 1, nsamp = NULL, dir = NULL, template = "plain",
    inputs = NULL, header = list(Date = Sys.Date()), name = NULL,
    quiet = TRUE, edir = NULL, tdir = NULL, control = NULL)

Arguments

file	character. A specification of a (list of) exercise files, for details see below.
n	integer. The number of copies to be compiled from file.
nsamp	integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir	character. The output directory, this has to be set if n is greater than 1 (or template is longer than 1).
template	character. A specification of a LaTeX template. The package currently provides "exam", "solution", "plain". For details see below.
inputs	character. Names of files that are needed as inputs during LaTeX compilation (e.g., style files, headers). Either the full path must be given or the file needs to be in edir.
header	list. A list of further options to be passed to the LaTeX files.
name	character. A name prefix for resulting exercises, by default chosen based on template.
quiet	logical. Should output be suppressed when calling Sweave and texi2dvi.
edir	character specifying the path of the directory in which the files in file are stored (see also below).
tdir	character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up and potentially temporary files are deleted.
control	A list of control arguments for the appearance of multiple choice results (see ‘Details’).

Details

exams is the old (version 1) interface for Sweave-based generation of PDF exams. It is only provided for backward compatibility and is superseded by the far more flexible function exams2pdf.

exams generates exams from lists of Sweave source files by: (1) running Sweave on each exercise, (2) including the resulting LaTeX files in a template, (3) running texi2dvi on the template, and (4) storing the resulting PDF file in an output dir (or displaying it interactively).

Each exercise in an exam is essentially a standalone Sweave source file that exams knows (almost) nothing about, it just calls Sweave (n times). The only exception is some meta-information which is passed by means of four commands back to exams. The commands are ‘⁠\extype⁠’ (which may be ‘⁠mchoice⁠’ or ‘⁠num⁠’), ‘⁠\exsolution⁠’ (e.g., 3.124 for a numeric solution and 10010 for a multiple choice solution), ‘⁠\exstring⁠’ (containing a human-readable string with the solution), and ‘⁠\extol⁠’ (a tolerance for numeric solutions).

The specification in file should be either of form "foo" or equivalently "foo.Rnw", where the file "foo.Rnw" should either be in the local directory, the edir directory or in the exercises directory of the package. file can either be a simple vector or a list of vectors. In the latter case, exercises are chosen randomly within each list element. For example, the specification file = list(c("a", "b"), "xyz") will result in an exam with two exercises: the first exercise is chosen randomly between "a" and "b" while "xyz" is always included as the second exercise.

The template is a (vector of) specification(s) of LaTeX templates. It can be "foo" or equivalently "foo.tex" where "foo.tex" should either be in the local directory (or provided with the full path) or in the tex directory of the package. It should specify where in the template the exercises are included, using the markup ‘⁠\exinput{exercises}⁠’. Additionally, it may contain ‘⁠\exinput{questionnaire}⁠’ and ‘⁠\exinput{header}⁠’. template can also be a vector, then for each of the n runs several output files (one for each template) are created.

The name prefix for each file is by default the base name of the corresponding template but can also be changed via name.

exams creates the PDF files and stores them in an output directory together with the solution meta information as ‘⁠metainfo.rda⁠’ (see also below). If only a single PDF is created (currently the default), dir may be NULL and it is only displayed on the screen.

The argument control is specified by a named list with elements mchoice.print and mchoice.symbol. The element mchoice.print is used for specifying the characters used for printing. It is again a named list where element True gives the (five) characters used for printing when the answer is correct and False if the answer is wrong. The symbol used for the questionnaire output in the final PDF file is defined by mchoice.symbol which is vector with elements True and False.

Value

An object of class "exams_metainfo" is returned invisibly. It is a list of length n, containing a list of meta informations for each exercise:

mchoice	logical. Is the exercise a multiple choice exercise?
length	integer. Length of solution.
solution	either a logical vector (for multiple choice) or numeric vector (for arithmetic problems).
string	character. A human-readable version of the solution.

References

Gruen B, Zeileis A (2009). Automatic Generation of Exams in R. Journal of Statistical Software, 29(10), 1–14. doi:10.18637/jss.v029.i10.

See Also

exams2pdf, Sweave, texi2dvi, mchoice2string

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## define an exams (= list of exercises)
myexam <- list(
  "boxplots.Rnw",
  c("tstat.Rnw", "ttest.Rnw", "confint.Rnw"),
  c("regression.Rnw", "anova.Rnw"),
  "scatterplot.Rnw",
  "relfreq.Rnw"
)


if(interactive()) {
## compile a single random exam (displayed on screen)
sol <- exams(myexam)
sol
}

## generate multiple exams (stored in output directory)
odir <- tempfile()
sol <- exams(myexam, n = 2, dir = odir, template = c("exam", "solution"))
sol

## inspect solution for a particular exam
print(sol, 3)

if(interactive()) {
## modify control argument for printing
mymchoice.control <- list(mchoice.print = list(True = LETTERS[1:5], False = "_"))
sol <- exams("boxplots.Rnw", template = "solution",
  control = mymchoice.control)
sol
}

---

Auxiliary Tools for Evaluating Exams

Description

Generation of various helper functions for evaluating exams.

Usage

exams_eval(partial = TRUE, negative = FALSE,
  rule = c("false2", "false", "true", "all", "none"))

Arguments

partial	logical. Should multiple-choice (mchoice) answers be evaluated as a whole pattern (partial = FALSE) or should partial credits be assigned to each of the choices (partial = TRUE)?
negative	logical or numeric. Handling of negative points for an exercise, for details see below.
rule	character specifying which rule to use for negative partial credits (i.e., only relevant for multiple-choice answers when partial = TRUE).

Details

The function exams_eval is a convenience wrapper for specifying various types of evaluation policies. It returns a set of auxiliary functions that may be useful in the evaluation of exams.

Exercises of types num, string, or schoice can essentially be just correct or wrong. In the former case they will give 100 percent of all points, in the latter either 0 percent or some negative percentage can be assigned. Setting negative = TRUE is equivalent to setting either negative = 1 or equivalently negative = -1, which all signal that 100 percent of the points for the exercise should be subtracted. Other percentages are also possible, e.g., negative = 0.25, which would be a natural choice for "schoice" questions with five answer alternatives. Not that when using an evaluation strategy with negative points for wrong answers, the system that collects the participants' answers should distinguish between ‘solved incorrectly’ and ‘not attempted’ (which should always yield 0 percent).

Moreover, for mchoice (multiple-choice) answers the evaluation policy can either pertain to the answer pattern as a whole (which can be correct or wrong, see above) or it can employ a partial credit strategy. In the latter case, each selected correct choice will yield the fraction 1/ncorrect of points. When an incorrect choice is selected, it should lead to negative points. Five strategies are currently implemented: "false" uses 1/nwrong while "false2" uses 1/max(nwrong, 2); "true" uses 1/ncorrect (so that each wrong selection cancels one correct selection); "all" uses 1 (so that a single wrong selection cancels all correct selections); and "none" uses 0 (so that wrong selections have no effect at all). When aggregating the partial percentages, the overall points can become negative. By setting negative a lower bound can be set: negative = TRUE sets no bound while negative = FALSE sets the bound to zero. Any other numeric value could be set as well, e.g., negative = 0.25.

The functions returned by exams_eval try to automatically infer the type of exercise based on the correct answer. However, this cannot always infer the type reliably (e.g., the number 10 vs. the string 10 vs. a multiple-choice question with two elements, true and false). Specifically, multiple-choice vs. single-choice cannot be distinguished automatically. Hence, it is better to explicitly indicate the exercise type with the type argument.

Evaluations for cloze exercises have to be built by appropriately reusing the building blocks for num/string/schoice/mchoice. For example, the components of cloze exercises have to be evaluated individually and then aggregated as desired. Different evaluations for different item types may be set as in: exams2qti12(..., eval = eval1, schoice = list(eval = eval2)). Then eval = eval1 is used as the default for all exercise types except schoice where eval = eval2 is used.

Thus, exams_eval might not give the complete finished evaluation policy for an entire exam but supplies the most important building blocks for setting this up ‘by hand’. Internally, exams_eval is also used by exams2moodle, exams2qti12 and exams2blackboard for writing the evaluation specifications in the respective XML specifications.

Value

exams_eval returns a list with the input parameters partial, negative, and rule along with the following functions:

checkanswer	function with arguments (correct, answer, tolerance = 0, and type = NULL. It checks whether answer (sufficiently) matches correct or not. It returns 1 for correct, -1 for wrong and 0 for not attempted. In case of partial = TRUE, the functions returns a vector for multiple-choice questions.
pointvec	function with arguments correct = NULL and type = NULL. It computes the vector of points for correct and wrong answers, respectively.
pointsum	function with arguments (correct, answer, tolerance = 0, and type = NULL. It computes the overall number of points.

All of the functions require at least the correct answer and optionally the exercise type (num, mchoice/schoice, or string). By default, the type is inferred from correct which works automatically except in a few edge cases (e.g., to correctly autodetect a string exercise the correct answer must contain at least one character that is not 0 or 1).

See Also

exams2moodle, exams2qti12, exams2blackboard

Examples

## binary evaluation policy with solutions being either correct
## or wrong: partial = FALSE, negative = FALSE
ee <- exams_eval(partial = FALSE, negative = FALSE)

## points that can be achieved are 0/1
ee$pointvec()

## checkanswer() returns 1 for correct, -1 for incorrect and 0 for missing answer
ee$checkanswer(1.23, 1.23)
ee$checkanswer(1.23, "1.23")
ee$checkanswer(1.23, "1,23")
ee$checkanswer(1.23, 1.24)
ee$checkanswer(1.23, 1.24, tolerance = 0.01)
ee$checkanswer(1.23, NA)
ee$checkanswer(1.23, NULL)
ee$checkanswer(1.23, "")

## similarly for logical (mchoice/schoice) answers
## (which allows either string or logical specification)
ee$checkanswer("10000", "10000")
ee$checkanswer(c(TRUE, FALSE, FALSE, FALSE, FALSE), c(TRUE, FALSE, FALSE, FALSE, FALSE))
ee$checkanswer(c(TRUE, FALSE, FALSE, FALSE, FALSE), "10000")
ee$checkanswer("10000", "01000")
ee$checkanswer("10000", "11000")

## and analogously for strings
ee$checkanswer("foo", "foo")
ee$checkanswer("foo", "bar")
ee$checkanswer("foo", "")

## obtain points achieved
ee$pointsum("10000", "10000")
ee$pointsum("10000", "01000")
ee$pointsum("10000", "00000")
ee$pointsum("10000", NA)

## ---------------------------------------------------------
## evaluation policy with -25% penalty for wrong answers
ee <- exams_eval(partial = FALSE, negative = -0.25)

## points that can be achieved are 1/-0.25 (or zero)
ee$pointvec()

## obtain points achieved
ee$pointsum("10000", "10000")
ee$pointsum("10000", "01000")
ee$pointsum("10000", "00000")
ee$pointsum("10000", NA)
ee$pointsum(1.23, 1.23)
ee$pointsum(1.23, 2.34)
ee$pointsum(1.23, NA)
ee$pointsum(1.23, 1.24)
ee$pointsum(1.23, 1.24, tolerance = 0.1)

## ---------------------------------------------------------
## default evaluation policy with partial points
## (but without negative points overall)
ee <- exams_eval()

## points that can be achieved are 1/3 (1/#true)
## or -1/2 (1/#false)
ee$pointvec("10101")

## obtain points achieved
ee$pointsum("10101", "10101")
ee$pointsum("10101", "10100")
ee$pointsum("10101", "11100")
ee$pointsum("10101", "01010")
ee$pointsum("10101", "00000")

## show individual answer check
ee$checkanswer("10101", "10101")
ee$checkanswer("10101", "10100")
ee$checkanswer("10101", "11100")
ee$checkanswer("10101", "01010")
ee$checkanswer("10101", "00000")

## numeric/string answers are not affected by partial=TRUE
ee$checkanswer(1.23, 1.23)
ee$pointsum(1.23, 1.23)
ee$checkanswer(1.23, 2.34)
ee$pointsum(1.23, 2.34)

## ---------------------------------------------------------
## evaluation policy with partial points
## (and with up to -25% negative points overall)
ee <- exams_eval(partial = TRUE, negative = -0.25)

## points that can be achieved are 1/3 (1/#true)
## or -1/2 (1/#false)
ee$pointvec("10101")

## obtain points achieved
ee$pointsum("10101", "10101")
ee$pointsum("10101", "01010")
ee$pointsum("10101", "00000")

## show individual answer check
ee$checkanswer("10101", "10101")
ee$checkanswer("10101", "10100")
ee$checkanswer("10101", "11100")
ee$checkanswer("10101", "01010")
ee$checkanswer("10101", "00000")

## numeric/string answers are not affected by partial=TRUE
ee$pointsum(1.23, 1.23)
ee$pointsum(1.23, 2.34)

---

Generate Skeleton for Exams Directory/Script

Description

Generate a directory structure which contains ‘demo-*.R’ scripts along with directories containing all available demonstation exercise ‘.Rnw’ or ‘.Rmd’ files and necessary template files (LaTeX, HTML, or XML).

Usage

exams_skeleton(dir = ".",
  type = c("num", "schoice", "mchoice", "string", "cloze"),
  writer = c("exams2html", "exams2pdf", "exams2moodle",
    "exams2qti12", "exams2qti21", "exams2arsnova", "exams2nops"),
  markup = "markdown", absolute = FALSE, encoding = "UTF-8")

Arguments

dir	character with path to directory. The default is the current working directory.
type	character vector indicating types of exercises that should be included in the ‘demo.R’ script. By default an example for each type of exercise is included.
writer	character vector indicating the exams2xyz writer functions that should be included in the ‘demo.R’ script. By default an example for each type of writer is included.
markup	character vector indicating whether the example exercises use "latex" markup (.Rnw files) or "markdown" markup (.Rmd files).
absolute	logical. Should the paths in the ‘demo.R’ script be absolute? The default is to use relative paths.
encoding	character, ignored. The encoding is always assumed to be UTF-8.

Details

exams_skeleton (or equivalently exams.skeleton) creates a directory with several ‘demo-*.R’ scripts illustrating the use of the various exams2xyz interfaces. Subdirectories with copies of all demonstration exercise .Rnw or .Rmd files and templates for different output formats (LaTeX, HTML, or XML) are also created.

This should provide a starting point for users wishing to start their own collection of exercises with exams.

Value

exams_skeleton returns a list of character vectors with the demo scripts invisibly.

See Also

exams2html, exams2pdf, exams2moodle, exams2qti12, exams2qti21, exams2arsnova, exams2nops

Examples

## output directory (replace this with mydir <- "/path/to/your/directory")
dir.create(mydir <- tempfile())

## create exams skeleton with absolute paths in demo.R
exams_skeleton(dir = mydir, absolute = TRUE)

## look at created files
dir(mydir)
dir(mydir, recursive = TRUE)

## now open demo-all.R or any of the other demo-*.R scripts in your
## favorite R code editor and run the examples...

---

Generation of Exam/Quiz Sessions in ARSnova Format

Description

Interface for generating interactive sessions in the JSON format of the audience response system ARSnova. As ARSnova has been superseded by Particify, it is recommended to use exams2particify instead. exams2arsnova will be removed in future versions of the package.

Usage

exams2arsnova(file, n = 1L, dir = ".",
  name = "R/exams", sname = NULL, qname = NULL,
  quiet = TRUE, resolution = 100, width = 4, height = 4, svg = FALSE,
  encoding = "UTF-8", envir = NULL, engine = NULL,
  url = "https://arsnova.eu/api", sessionkey = NULL, jsessionid = NULL,
  active = TRUE, votingdisabled = FALSE, showstatistic = FALSE, showanswer = FALSE,
  abstention = TRUE, variant = "lecture", ssl.verifypeer = TRUE,
  fix_choice = TRUE, ...)

make_exams_write_arsnova(url = "https://arsnova.eu/api", sessionkey = NULL,
  jsessionid = NULL, name = "R/exams", sname = NULL, qname = NULL,
  active = TRUE, votingdisabled = FALSE, showstatistic = FALSE, showanswer = FALSE,
  abstention = TRUE, variant = "lecture", ssl.verifypeer = TRUE, fix_choice = TRUE)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
dir	character. The default is either display on the screen or the current working directory.
name	character. A name prefix for resulting exercises and RDS file.
sname	character. A vector of length 2 with the session name (maximum of 50 characters) and its abbreviation (maximum of 8 characters). Ignored if the sessionkey of an existing session is supplied and otherwise copied by default from name.
qname	character. A vector of names for each question/exercise in file. By default, the name is used.
quiet	logical. Should output be suppressed when calling xweave and texi2dvi.
resolution, width, height	numeric, passed to xweave.
svg	logical. Should graphics be rendered in SVG or PNG (default)?
encoding	character, ignored. The encoding is always assumed to be UTF-8.
envir	argument passed to xweave (which passes it to knit).
engine	argument passed to xweave indicating whether "Sweave" (default) or "knitr" should be used for rendering Rnw exercises.
url, sessionkey, jsessionid	character specifying (1) the base URL of the ARSnova API, (2) the 8-digit ARSnova session key, (3) the JSESSIONID cookie of an active ARSnova session. If all are provided all questions are imported directly into the existing ARSnova session. Otherwise, a JSON import file is generated.
active	logical. Should the question be active (i.e., released for students) or locked?
votingdisabled	logical. Should voting be disabled?
showstatistic	logical. Should statistics be shown?
showanswer	logical. Should answers be shown?
abstention	logical. Are abstentions allowed?
variant	character. Should the question be a "lecture" or a "preparation" questions?
ssl.verifypeer	logical. Should SSL certificates be validated when connecting via https?
fix_choice	logical. Should math markup be removed in single and multiple choice lists? (This may be needed for older ARSnova versions where math markup is rendered in the question itself but not the choice list.)
...	arguments passed on to xexams.

Details

exams2arsnova generates exams in the JSON format for ARSnova using xexams. It proceeds by (1) calling xweave on each exercise, (2) reading the resulting Markdown or LaTeX text, (3) transforming the text to Markdown, and (4) embedding the Markdown text into the JSON format for ARSnova (and optionally imports it into a running ARSnova session).

Since 2020 the development of ARSnova has been shifted to a new tool called Particify and hence the arsnova.eu server is not hosted anymore. For an export function to Particify see exams2particify.

For steps (1) and (2) the standard drivers in xexams are used. For step (3) a suitable transformation function is set up on the fly using make_exercise_transform_pandoc. For step (4) a simple writer function is set up on the fly that embeds the transformed Markdown code into a hard-coded JSON template using toJSON and either writes a single JSON file for each exam or imports these directly into an ARSnova session.

When url, sessionkey, and jsessionid are all supplied, curlPerform is used to import tall questions directly into the existing ARSnova session. Otherwise, a file is written to the disk and then needs to be imported manually into an ARSnova server. This file is either a JSON file for a whole new session (if sessionkey is NULL, the default) or a CSV file with the questions only.

Value

A list of exams as generated by xexams is returned invisibly.

See Also

exams2particify

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## Not run: 
## exams2arsnova can either create text files with JSON data
exams2arsnova("tstat2")

## or directly post this to an active ARSnova session (for which the
## server URL, the 8-digit session key, and the JSESSIONID cookie are needed)
exams2arsnova("tstat2", url = "https://arsnova.eu/api",
  sessionkey = "49061284", jsessionid = "A5BEFDA4141816BB425F2204A602E4B3")

## End(Not run)

---

Generation of Exams in Blackboard Format

Description

Automatic generation of exams in Blackboard format (which is partially based on QTI 1.2).

Usage

exams2blackboard(file, n = 1L, nsamp = NULL, dir = ".",
    name = NULL, quiet = TRUE, edir = NULL,
    tdir = NULL, sdir = NULL, verbose = FALSE, rds = FALSE,
    resolution = 100, width = 4, height = 4, encoding = "UTF-8",
    envir = NULL, engine = NULL,
    num = NULL, mchoice = NULL,
    schoice = mchoice, string = NULL, cloze = NULL,
    template = "blackboard",
    pdescription = "This is an item from an item pool.",
    tdescription = "This is today's test.",
    pinstruction = "Please answer the following question.",
    tinstruction = "Give an answer to each question.",
    maxattempts = 1, zip = TRUE, points = NULL,
    eval = list(partial = TRUE, rule = "false2", negative = FALSE),
    base64 = FALSE, converter = NULL, seed = NULL, mathjax = NULL,
    fix_pre = TRUE, ...)

  make_itembody_blackboard(rtiming = FALSE, shuffle = FALSE,
    rshuffle = shuffle, minnumber = NULL, maxnumber = NULL,
    defaultval = NULL, minvalue = NULL, maxvalue = NULL,
    cutvalue = NULL, enumerate = TRUE, digits = NULL,
    tolerance = is.null(digits), maxchars = 12,
    eval = list(partial = TRUE, rule = "false2", negative = FALSE),
    qti12 = FALSE, mathjax = FALSE)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
nsamp	integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir	character. The default is the current working directory.
name	character. A name prefix for resulting exercises and ZIP file.
quiet	logical. Should output be suppressed when calling xweave?
edir	character specifying the path of the directory (along with its sub-directories) in which the files in file are stored (see also xexams).
tdir	character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up (i.e., existing files are deleted) and only certain temporary files are preserved.
sdir	character specifying a directory for storing supplements, by default this is chosen via tempfile.
verbose	logical. Should information on progress of exam generation be reported?
rds	logical indicating whether the return list should also be saved as an RDS data file.
resolution, width, height	numeric. Options for rendering PNG graphics passed to xweave.
encoding	character, ignored. The encoding is always assumed to be UTF-8.
envir	argument passed to xweave (which passes it to knit).
engine	argument passed to xweave indicating whether "Sweave" (default) or "knitr" should be used for rendering Rnw exercises.
num	function or named list applied to numerical (i.e., type num) questions. If num is a function, num will be used for generating the item body of the question, see function make_itembody_blackboard(). If num is a named list, these arguments will be passed to function make_itembody_blackboard().
mchoice, schoice, string, cloze	function or named list applied to multiple choice, single choice, string, and cloze questions (i.e., type mchoice, schoice, string, and cloze), respectively. See argument num for more details.
template	character. The IMS QTI 1.2 or 2.1 template that should be used. Currently, the package provides "blackboard.xml".
pdescription	character. Description (of length 1) of the item pool (i.e., the set of copies).
tdescription	character. Description (of length 1) of the overall assessment (i.e., exam).
pinstruction	character. Instruction (of length 1) for the item pool (i.e., set of copies).
tinstruction	character. Instruction (of length 1) for the overall assessment (i.e., exam).
maxattempts	integer. The maximum attempts for one question, may also be set to Inf.
zip	logical. Should the resulting XML file (plus supplements) be zipped?
points	integer. How many points should be assigned to each exercise? Note that this argument overules any exercise points that are provided within an expoints tag in the Rnw/Rmd exercise file. The vector of points supplied is expanded to the number of exercises in the exam.
eval	named list, specifies the settings for the evaluation policy, see function exams_eval.
base64	logical. Should supplementary files be embedded using Base 64 coding? Argument base64 may also be a character vector of file suffixes that should be encoded, e.g. base64 = c("png", "rda") will only encode PNG images and binary .rda files. If set to NULL only image files will be encoded.
converter, ...	arguments passed on to make_exercise_transform_html. The default for converter is set to "ttm" unless there are Rmd exercises in file where "pandoc" is used.
seed	integer matrix or logical. Either NULL (default), logical, or a matrix of random seeds for each possible exercise to be set prior to calling driver@sweave. If NULL no random seeds are set. If a matrix, the number of rows must be n and the number of columns must correspond to unlist(file). If TRUE a suitable matrix of seeds is sampled.
mathjax	logical. Should the JavaScript from https://www.MathJax.org/ be included for rendering mathematical formulas? By default mathjax = FALSE unless converter = "pandoc-mathjax" is used. However, also for the default converters (producing MathML output) mathjax = TRUE can be used, enabling rendering of mathematical equations in browsers without native MathML support (like Chrome/Chromium). Note that this only works in Classic Blackboard but not in Blackboard Ultra.
fix_pre	logical. Should the HTML <pre> environment for rendering verbatim output be replaced by <code> tags? This is necessary in classical Blackboard which does not render <pre> correctly.
rtiming, shuffle, rshuffle, minnumber, maxnumber, defaultval, minvalue, maxvalue	arguments used for IMS QTI 1.2 item construction, for details see the XML specification (see IMS Global Learning Consortium, Inc. 2012), especially Section 4.
cutvalue	numeric. The cutvalue at which the exam is passed.
enumerate	logical. Insert potential solutions in enumerated list?
digits	integer. How many digits should be used for num exercises?
tolerance	logical. Should tolerance intervals be used for checking if the supplied num answer/number is correct? The default is to use tolerance intervals if digits = NULL.
maxchars	numeric. Lower bound for the number of characters in fill-in-blank fields. The actual number of characters is selected as the maximum number of characters of this value and the actual solution.
qti12	logical. For reverse compability to plain QTI 1.2 XML format.

Details

Blackboard employs an XML format that essentially uses the Question & Test Interoperability (QTI) standard, version 1.2, see IMS Global Learning Consortium, Inc. (2012). However, as this deviates from the plain QTI 1.2 standard in several places, the exams2qti12 cannot be used directly. Instead, exams2blackboard is a new interface that is likely to be improved in future versions.

exams2blackboard produces a .zip file that may be uploaded into Blackboard. This includes the final XML file of the exam/assessment as well as possible supplement folders that include images, data sets etc. used for the exam. After uploading the test into Blackboard, the material will appear under ‘Course Tools’: the test will be available in ‘Tests’, and each pool within the test will also appear in ‘Pools’.

exams2blackboard proceeds by (1) calling xweave on each exercise, (2) reading the resulting LaTeX code, (3) transforming the LaTeX code to HTML, and (4) embedding the HTML code in a XML file using Blackboard's QTI standards for assessments and question items. For steps (1) and (2) the standard drivers in xexams are used. In step (3), a suitable transformation function is set up on the fly using make_exercise_transform_html, see also the details section in exams2html. For step (4), the function will cycle through all questions and exams to generate the final XML file in the Blackboard QTI standard. Therefore, each question will be included in the XML as one section. The replicates of each question will be written as question items of the section.

The function uses the XML template for Blackboard's QTI standards for assessments and items to generate the exam (per default, this is the XML file blackboard.xml provided in the xml folder of this package). The assessment template must provide one section including one item. exams2blackboard will then use the single item template to generate all items, as well as the assessment and section specifications set within the template.

The default template will generate exams/assessments that sample one replicate of a question/item for each section. The usual procedure in exam/assessment generation would be to simply copy & paste the XML template of the package and adapt it to the needs of the user. Note that all specifiers that have a leading ## in the XML template will be replaced by suitable code in exams2blackboard and should always be provided in the template. I.e., the user may add additional tags to the XML template or modify certain specifications, like the number of replicates/items that should be sampled for each section etc.

Per default, the individual question/item bodies are generated by function make_itembody_blackboard, i.e., make_itembody_blackboard checks the type of the question and will produce suitable XML code. Note that for each question type, either the arguments of make_itembody_blackboard may be set within num, mchoice, schoice and string in exams2blackboard, by providing a named list of specifications that should be used, or for each questiontype, a function that produces the item body XML code may be provided to num, mchoice, schoice and string. E.g., mchoice = list(shuffle = TRUE) will force only multiple choice questions to have a shuffled answerlist.

Note that in Blackboard cloze items are not officially supported, and hence this type of item is not supported in the current version of exams2blackboard either. It is currently investigated if a workaround may be implemented to allow for cloze items.

Value

exams2blackboard returns a list of exams as generated by xexams.

make_itembody_blackboard returns a function that generates the XML code for the itembody tag in Blackboard's version of the IMS QTI 1.2 format.

References

Blackboard, Inc. (2016). Blackboard Help: Question types. https://help.blackboard.com/Learn/Instructor/Ultra/Tests_Pools_Surveys/Question_Types

IMS Global Learning Consortium, Inc. (2012). IMS Question & Test Interoperability: ASI XML Binding Specification Final Specification Version 1.2. https://www.imsglobal.org/question/qtiv1p2/imsqti_asi_bindv1p2.html

Zeileis A, Umlauf N, Leisch F (2014). Flexible Generation of E-Learning Exams in R: Moodle Quizzes, OLAT Assessments, and Beyond. Journal of Statistical Software, 58(1), 1–36. doi:10.18637/jss.v058.i01.

See Also

exams2qti12

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## define an exams (= list of exercises)
myexam <- list(
  "boxplots.Rmd",
  "ttest.Rmd",
  "anova.Rmd",
  "scatterplot.Rmd",
  "relfreq.Rmd"
)

## output directory
dir.create(mydir <- tempfile())

## generate .zip with Blackboard exam in temporary directory
exams2blackboard(myexam, n = 3, dir = mydir)
dir(mydir)

---

Generation of Exams for Canvas

Description

Automatic generation of exams in QTI 1.2 with some tweaks (still under development) for the learning management system Canvas.

Usage

exams2canvas(file, n = 1L, dir = ".", name = "canvasquiz",
    maxattempts = 1, duration = NULL, points = NULL,
    converter = "pandoc-mathjax", template = "canvas_qti12.xml",
    quiztype = "assignment", ...)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
dir	character. The default is the current working directory.
name	character. A name prefix for resulting exercises and ZIP file.
maxattempts	integer. The maximum attempts for one question (must be smaller than 100000).
duration	integer. Set the duration of the exam in minutes.
points	integer. How many points should be assigned to each exercise? Note that this argument overules any exercise points that are provided within an "\expoints{}" tag in the .Rnw file. The vector of points supplied is expanded to the number of exercises in the exam.
converter	character passed on to make_exercise_transform_html, indicating the type of converter from LaTeX/Markdown to HTML.
template	character. The IMS QTI 1.2 template that should be used.
quiztype	character. The type of quiz that should be created in Canvas. Defaults to "assignment" with alternative values being "practice_quiz", "graded_survey", or "survey".
...	arguments passed on to exams2qti12. The arguments base64 and eval cannot be modified but are hard-coded internally (for details see below).

Details

exams2canvas is a convenience interface to exams2qti12 for generating QTI 1.2 with some small tweaks for Canvas (https://www.instructure.com/canvas). The supported exercise types at the moment are num, schoice, mchoice, and string. There is limited support for cloze exercises with multiple dropdown menus, i.e., schoice elements placed in the text with ANSWERi tags.

The Canvas-specific tweaks include:

• Canvas needs a converter that produces HTML with mathematical notation that can be rendered by MathJax. Hence "pandoc-mathjax" is the default but "pandoc-mathml" (or "ttm" for exams with only R/LaTeX .Rnw exercises) works as well, albeit possibly with problems when imported from a quiz to the item bank.

• Supplementary files (images, data, ...) must be embedded without Base 64 encoding. Thus, base64 = FALSE is hard-coded internally in exams2canvas.

• Multiple-choice exercises (referred to as multiple answer questions in Canvas) are always evaluated (aka scored) with partial credits in Canvas. Therefore, eval = list(partial = TRUE, negative = FALSE) is hard-coded internally in exams2canvas. Negative points are not supported in Canvas.

• The QTI XML file requires a few special tags which are enforced through flavor = "canvas" in exams2qti12.

Technical note: For multiple-choice questions the QTI XML file produced by exams2canvas appears to encode an “all-or-nothing” scheme without partial credits (i.e., partial = FALSE). However, this is necessary for Canvas to recognize the answer alternatives correctly. Despite this, Canvas always applies partial-credit evaluation (as explained above).

Value

exams2canvas returns a list of exams as generated by xexams.

See Also

exams2qti12

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## define an exams (= list of exercises)
myexam <- c(
  "boxplots.Rmd",
  "tstat.Rmd",
  "ttest.Rmd",
  "regression.Rmd",
  "relfreq.Rmd"
)

## output directory
dir.create(mydir <- tempfile())

## generate .zip with Canvas test in temporary directory
exams2canvas(myexam, n = 3, dir = mydir)
dir(mydir)

---

Generation of Exercises in Grasple Format

Description

Automatic generation of exercises in JSON format for the e-learning platform Grasple.

Usage

exams2grasple(file, n = 1L, dir = ".", name = NULL, quiet = TRUE,
  resolution = 100, width = 4, height = 4, svg = FALSE, encoding = "UTF-8",
  envir = NULL, engine = NULL,
  converter = "pandoc-mathjax", zip = TRUE, use_solutionlist = TRUE,
  license_name = NULL, license_description = NULL, license_value = NULL,
  license_link = NULL, ...)

make_exams_write_grasple(name = NULL, license_name = NULL,
  license_description = NULL, license_value = NULL, license_link = NULL,
  zip = TRUE, use_solutionlist = TRUE)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
dir	character. The default is the current working directory.
name	character. A name prefix for resulting ZIP file.
quiet	logical. Should output be suppressed when calling xweave and texi2dvi.
resolution, width, height	numeric, passed to xweave.
svg	logical. Should graphics be rendered in SVG or PNG (default)?
encoding	character, ignored. The encoding is always assumed to be UTF-8.
envir	argument passed to xweave (which passes it to knit).
engine	argument passed to xweave indicating whether "Sweave" (default) or "knitr" should be used for rendering Rnw exercises.
converter	character passed on to make_exercise_transform_html, indicating the type of converter from LaTeX/Markdown to the specific requirements in Grasple. To accomplish this the converter must be set to "pandoc-mathjax".
zip	logical. Should the resulting JSON file(s) be zipped?
use_solutionlist	logical. By default it is assumed that for schoice items the solutionlist contains separate feedback for each option. If set to FALSE the general feedback is placed in the solutionlist for each option separately.
license_name, license_description, license_value, license_link	character, arguments for specifying the copyright license for the exercise(s). Defaults to "Non-explicit license".
...	arguments passed on to xexams.

Details

exams2grasple generates exercises in the JSON format for Grasple using xexams. It proceeds by (1) calling xweave on each exercise, (2) reading the resulting Markdown or LaTeX text, (3) transforming the text to Markdown, and (4) embedding the Markdown text into the JSON format for Grasple.

For steps (1) and (2) the standard drivers in xexams are used. For step (3) a suitable transformation function is set up on the fly using make_exercise_transform_html. For step (4) a simple writer function is set up on the fly that embeds the transformed Markdown code into a hard-coded JSON template using toJSON and writes a JSON file for each exercise and by default bundles the collection in a ZIP file.

Note that Grasple only officially supports schoice and num items, and hence other item types are not supported in the current version of exams2grasple either. If the function is used for other types the execution of the function is stopped and a warning is issued.

For num exercises the content as specified under the solution environment in the Rmd/Rnw files is presented as feedback in Grasple. By contrast, for schoice items Grasple requires separate feedback for each option. This can be accomplished in two ways. First (the default), by putting unique feedback for each option in the items of the solutionlist in the Rmd/Rnw file. Second by putting a general feedback in the solution environment and setting use_solutionlist to FALSE, which creates a solutionlist with this general feedback for each option.

If the meta-information of an exercise contains an exsection element, its content will be transferred to the name element of the JSON-file. This name element is searchable in Grasple. In the ShareStats project the exsection element is used for classifying items in terms of its taxonomy of topics in statistics education.

Within the HTML of Grasple exercises, LaTeX elements must be embedded within \\(\\) blocks. After conversion using "pandoc-mathjax" the function employs further tweaks to meet Grasple's requirements. Also, in case of displaying multiline equations Grasple only allows for using the align environment. Environments eqnarray and eqnarray* are automatically converted into align. It is uncertain how pandoc deals with other multiline environments.

Value

A list of exercises as generated by xexams is returned invisibly.

References

Grasple - Open Education (2022). Format for Open Interactive Math Exercises. https://github.com/grasple/open-format

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## define a list of exercises
myexam <- list(
  "fruit.Rmd",
  "tstat.Rmd",
  "regression.Rmd",
  "swisscapital.Rmd",
  "tstat2.Rmd",
  "dist3.Rmd"
)

## output directory
dir.create(mydir <- tempfile())

## Not run: 
## generate .zip with Grasple exercises and use general feedback
exams2grasple(myexam, dir = mydir, use_solutionlist = FALSE)
dir(mydir)

## End(Not run)

---

Generation of Exams in HTML Format

Description

Automatic generation of exams in HTML format.

Usage

exams2html(file, n = 1L, nsamp = NULL, dir = ".", template = "plain.html",
    name = NULL, quiet = TRUE, edir = NULL, tdir = NULL, sdir = NULL, verbose = FALSE,
    rds = FALSE, question = "<h4>Question</h4>", solution = "<h4>Solution</h4>",
    mathjax = NULL, resolution = 100, width = 4, height = 4, svg = FALSE,
    encoding = "UTF-8", envir = NULL, engine = NULL, converter = NULL, seed = NULL,
    exshuffle = NULL, ...)

  make_exercise_transform_html(converter = c("ttm", "tth", "pandoc", "tex2image"),
    base64 = TRUE, options = NULL, ...)

  make_exams_write_html(template = "plain", name = NULL,
    question = "<h4>Question</h4>", solution = "<h4>Solution</h4>",
    mathjax = FALSE)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
nsamp	integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir	character specifying the output directory (default: current working directory). If only a single HTML file is produced and no dir is explicitly specified, the file is displayed in the browser rather than saved in dir.
template	character. A specification of a HTML template.
name	character. A name prefix for resulting exercises.
quiet	logical. Should output be suppressed when calling xweave?
edir	character specifying the path of the directory (along with its sub-directories) in which the files in file are stored (see also xexams).
tdir	character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up (i.e., existing files are deleted) and only certain temporary files are preserved.
sdir	character specifying a directory for storing supplements, by default this is chosen via tempfile.
verbose	logical. Should information on progress of exam generation be reported?
rds	logical indicating whether the return list should also be saved as an RDS data file.
question	character or logical. Should the question be included in the HTML output? If question is a character it will be used as a header for resulting questions. Argument question may also be a vector that controls the output for the templates.
solution	character or logical, see argument question.
mathjax	logical. Should the JavaScript from https://www.MathJax.org/ be included for rendering mathematical formulas? By default mathjax = FALSE unless converter = "pandoc-mathjax".
resolution, width, height	numeric. Options for rendering PNG (or SVG) graphics passed to xweave.
svg	logical. Should graphics be rendered in SVG or PNG (default)?
encoding	character, ignored. The encoding is always assumed to be UTF-8.
envir	argument passed to xweave (which passes it to knit).
engine	argument passed to xweave indicating whether "Sweave" (default) or "knitr" should be used for rendering Rnw exercises.
base64	logical. Should supplementary files be embedded using Base 64 coding? Argument base64 may also be a character vector of file suffixes that should be encoded, e.g. base64 = c("png", "rda") will only encode PNG images and binary .rda files. If set to NULL only image files will be encoded.
converter, ...	arguments passed on to make_exercise_transform_html. The default for converter is set to "ttm" unless there are Rmd exercises in file where "pandoc" is used.
seed	integer matrix or logical. Either NULL (default), logical, or a matrix of random seeds for each possible exercise to be set prior to calling driver@sweave. If NULL no random seeds are set. If a matrix, the number of rows must be n and the number of columns must correspond to unlist(file). If TRUE a suitable matrix of seeds is sampled.
exshuffle	logical or integer. If the exshuffle argument is non-NULL it is used to overrule the exshuffle tag from the file (e.g., exshuffle = FALSE can be used to keep all available answers without permutation).
options	list of options to be passed on to pandoc_convert.

Details

exams2html generates exams in a very simple HTML format using xexams. It proceeds by (1) calling xweave on each exercise, (2) reading the resulting LaTeX code, (3) transforming the LaTeX code to HTML, and (4) embedding the HTML code in a template (a simple and plain template is used by default).

For steps (1) and (2) the standard drivers in xexams are used.

For step (3) a suitable transformation function is set up on the fly using make_exercise_transform_html. This transforms the LaTeX code in question/questionlist and solution/solutionlist by leveraging one of four functions: ttm produces HTML with MathML for mathematical formulas, tth produces plain HTML that aims to emulate mathematical formulas, pandoc_convert employs pandoc offering different options for handling formulas, and tex2image runs LaTeX and turns the result into a single image. In all cases, images can either be stored in supplementary files or embedded directly in Base 64 coding.

For step (4) a simple writer function is set up on the fly that embeds the transformed HTML code into a template and writes a single HTML file for each exam.

Value

exams2html returns a list of exams as generated by xexams.

make_exercise_transform_html returns a function that is suitable for being supplied as driver$transform to xexams.

make_exams_write_html returns a function that is suitable for being supplied as driver$write to xexams.

References

Zeileis A, Umlauf N, Leisch F (2014). Flexible Generation of E-Learning Exams in R: Moodle Quizzes, OLAT Assessments, and Beyond. Journal of Statistical Software, 58(1), 1–36. doi:10.18637/jss.v058.i01.

See Also

xexams, ttm, tth, pandoc_convert, tex2image, browseURL

Examples

## load package and enforce par(ask = FALSE)
options(device.ask.default = FALSE)

if(interactive() && requireNamespace("png")) {
## compile a single random exam (displayed in the browser)
exams2html(list(
  "boxplots.Rmd",
  c("tstat.Rmd", "ttest.Rmd", "confint.Rmd"),
  c("regression.Rmd", "anova.Rmd"),
  "scatterplot.Rmd",
  "relfreq.Rmd"
))

## various versions of displaying mathematical formulae

## via MathML (displayed correctly in MathML-aware browsers, e.g. Firefox)
exams2html("tstat")

## via MathML + MathJax (should work in all major browsers,
## note the display options you get when right-clicking on the formulas
## in the browser)
exams2html("tstat", mathjax = TRUE)

## via plain HTML (works in all browsers but with inferior formatting)
exams2html("tstat", converter = "tth")

## via HTML with embedded picture (works in all browsers but
## is slow and requires LaTeX and ImageMagick)
## Not run: 
exams2html("tstat", converter = "tex2image")

## End(Not run)
}

---

Generation of Exams in ILIAS Format

Description

Automatic generation of exams in QTI 1.2 with some tweaks (still under development) for the learning management system ILIAS.

Usage

exams2ilias(file, n = 1L, nsamp = NULL, dir = ".",
    name = NULL, quiet = TRUE, edir = NULL, tdir = NULL, sdir = NULL,
    verbose = FALSE, resolution = 100, width = 4, height = 4, svg = FALSE,
    encoding  = "UTF-8", num = list(fix_num = FALSE, minvalue = NA),
    mchoice = list(maxchars = c(3, NA, 3), minvalue = NA),
    schoice = mchoice, string = NULL, cloze = NULL,
    template = "ilias",
    duration = NULL, stitle = "Exercise", ititle = "Question",
    adescription = "Please solve the following exercises.",
    sdescription = "Please answer the following question.", 
    maxattempts = 1, cutvalue = 0, solutionswitch = TRUE, zip = TRUE,
    points = NULL, eval = list(partial = TRUE, negative = FALSE),
    converter = "pandoc-mathjax", xmlcollapse = TRUE,
    metasolution = FALSE, ...)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
nsamp	integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir	character. The default is the current working directory.
name	character. A name prefix for resulting exercises and ZIP file.
quiet	logical. Should output be suppressed when calling xweave?
edir	character specifying the path of the directory (along with its sub-directories) in which the files in file are stored (see also xexams).
tdir	character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up (i.e., existing files are deleted) and only certain temporary files are preserved.
sdir	character specifying a directory for storing supplements, by default this is chosen via tempfile.
verbose	logical. Should information on progress of exam generation be reported?
resolution, width, height	numeric. Options for rendering PNG (or SVG) graphics passed to xweave.
svg	logical. Should graphics be rendered in SVG or PNG (default)?
encoding	character, ignored. The encoding is always assumed to be UTF-8.
num	function or named list applied to numerical (i.e., type num) questions. If num is a function, num will be used for generating the item body of the question, see function make_itembody_qti12() (or make_itembody_qti21()). If num is a named list, these arguments will be passed to function make_itembody_qti12() (or make_itembody_qti21() using exams2qti21()).
mchoice, schoice, string, cloze	function or named list applied to multiple choice, single choice, string, and cloze questions (i.e., type mchoice, schoice, string, and cloze), respectively. See argument num for more details.
template	character. The IMS QTI 1.2 or 2.1 template that should be used. Currently, the package provides "qti12.xml" and "qti21.xml".
duration	integer. Set the duration of the exam in minutes.
stitle	character. A title that should be used for the sections. May be a vector of length 1 to use the same title for each section, or a vector containing different section titles.
ititle	character. A title that should be used for the assessment items. May be a vector of length 1 to use the same title for each item, or a vector containing different item titles. Note that the maximum of different item titles is the number of sections/questions that are used for the exam.
adescription	character. Description (of length 1) for the overall assessment (i.e., exam).
sdescription	character. Vector of descriptions for each section, omitted if empty (or NULL or FALSE).
maxattempts	integer. The maximum attempts for one question. This may also be a vector so that the maximum number of attempts varies across questions. A value of Inf or 0 signals that the attempts per question are not limited.
cutvalue	numeric. The cutvalue at which the exam is passed.
solutionswitch	logical. Should the question/item solutionswitch be enabled? In OLAT this means that the correct solution is shown after an incorrect solution was entered by an examinee (i.e., this is typically only useful if maxattempts = 1).
zip	logical. Should the resulting XML file (plus supplements) be zipped?
points	integer. How many points should be assigned to each exercise? Note that this argument overules any exercise points that are provided within an "\expoints{}" tag in the .Rnw file. The vector of points supplied is expanded to the number of exercises in the exam.
eval	named list, specifies the settings for the evaluation policy, see function exams_eval.
converter	character. Argument passed on to make_exercise_transform_html. The default for converter is set to "ttm" unless there are Rmd exercises in file where "pandoc" is used.
xmlcollapse	logical or character. Should line breaks be collapsed in the XML code. If TRUE everything is collapsed with spaces (" ") but other collapse characters could be supplied.
metasolution	logical. Should the solution be added to the XML output as qtimetadata tag? This currently only works for ILIAS essay questions.
...	further arguments passed on to make_exercise_transform_html.

Details

exams2ilias is a convenience interface to exams2qti12 for generating QTI 1.2 with some tweaks for ILIAS (https://www.ilias.de/). The support for ILIAS so far is somewhat rudimentary. Not all question types are currently supported. What has been tested most extensively, are string questions with open answers and solutions; these are rendered into ILIAS essay questions within a question pool. Also mchoice and schoice questions render in ILIAS, but have received less amount of testing. Numeric and cloze questions do not work yet.

Value

exams2ilias returns a list of exams as generated by xexams.

If zip is TRUE (default), an ILIAS Questionpool object is generated.

See Also

exams2qti12,

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## define an exams (= list of exercises)
myexam <- list(
  ## multiple-choice with graphics
  c("boxplots.Rmd", "scatterplot.Rmd"),

  ## multiple-choice with output or tables
  c("ttest.Rmd", "anova.Rmd", "relfreq.Rmd"),

  ## single-choice
  c("deriv2.Rmd", "swisscapital.Rmd"),

  ## string (closed)
  "function.Rmd",
  
  ## string (open-ended)
  "essayreg.Rmd"
)

## output directory
dir.create(mydir <- tempfile())

## generate .zip with ILIAS Questionpool in temporary directory
## using a few customization options
exams2ilias(myexam, n = 3, dir = mydir,
  maxattempts = 3,
  num = list(digits = 1),
  mchoice = list(shuffle = TRUE, enumerate = FALSE),
  solutionswitch = FALSE
)
dir(mydir)

---

Generation of Exams for Inspera

Description

Automatic generation of exams in QTI 2.1 with some tweaks optimized for Inspera.

Usage

exams2inspera(file, n = 1L, dir = ".", name = "inspera", template = "inspera",
    converter = "pandoc-mathml", base64 = FALSE, ...)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
dir	character. The default is the current working directory.
name	character. A name prefix for resulting exercises and ZIP file.
template	character. The QTI 2.1 template that should be used, defaulting to "inspera.xml" provided within the package.
converter	character passed on to make_exercise_transform_html, indicating the type of converter from LaTeX/Markdown to HTML. Defaults to HTML with MathML.
base64	logical. Should supplementary files be embedded using Base 64 coding? Currently only FALSE is supported by Inspera.
...	arguments passed on to exams2qti21, providing many further arguments for customization.

Details

exams2inspera is a convenience interface to exams2qti21 for generating QTI 2.1 output with some small tweaks for Inspera. Most importantly, no full "assessment" is exported but only a collection of individual exercises. Consequently, all options from exams2qti21 that pertain to the configuration of the assessment (e.g., maxattempts, cutvalue, navigation, etc.) have no effect here. Moreover, MathJax is used for type-setting mathematical content by default.

Value

exams2inspera returns a list of exams as generated by xexams.

See Also

exams2qti21

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## define an exams (= list of exercises)
myexam <- list(
  "boxplots.Rmd",
  c("tstat.Rmd", "ttest.Rmd", "confint2.Rmd"),
  c("regression.Rmd", "anova.Rmd"),
  c("scatterplot.Rmd", "boxhist.Rmd"),
  "relfreq.Rmd"
)

## output directory
dir.create(mydir <- tempfile())

## generate .zip with exercises for Inspera in temporary directory
exams2inspera(myexam, n = 3, dir = mydir)
dir(mydir)

---

Generation of Excel Sheets with Quiz Questions for Kahoot!

Description

Interface for generating Excel sheets with plain-text quiz questions for the Kahoot! game-based learning platform.

Usage

exams2kahoot(file, n = 1L, dir = ".", name = "kahootquiz",
  quiet = TRUE, time = NULL, ...)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
dir	character. The default is the current working directory.
name	character. A name prefix for resulting Excel sheets.
quiet	logical. Should output be suppressed when calling xweave?
time	numeric. Time limit (in seconds) allowed for answering the question in Kahoot!, must be one of 5, 10, 20, 30, 60, 90, 120, 240. If other numeric inputs are made, they are forced to the nearest admissable specification. Default: 60 seconds.
...	arguments passed on to xexams.

Details

exams2kahoot generates Excel sheets, requiring write.xlsx from the openxlsx package, that can be imported to the Kahoot! game-based learning platform. Only single-choice (schoice) and multiple-choice (mchoice) questions are allowed with plain questions and answers (using conversion via pandoc_convert). Questions and answers must not exceed 120 and 75 characters, respectively.

Value

A list of exams as generated by xexams is returned invisibly.

Examples

## Not run: 
## create an .xlsx file for Kahoot! (requiring openxslx) based
## on three simple text-based single-choice and multiple-choice questions
exams2kahoot(c("capitals", "swisscapital", "switzerland"))

## End(Not run)

---

Generation of Exams in LOPS Exam Server Format (WU Wien)

Description

Automatic generation of exams in LOPS exam server format (WU Wien).

Usage

exams2lops(file, n = 1L, nsamp = NULL, dir = ".", name = NULL, 
    quiet = TRUE, edir = NULL, tdir = NULL, sdir = NULL, verbose = FALSE,
    solution = TRUE, doctype = NULL, head = NULL, resolution = 100, width = 4, 
    height = 4, svg = FALSE,  encoding = "UTF-8", envir = NULL, engine = NULL,
    converter = "tex2image", base64 = FALSE,
    auto_scramble = TRUE, ...)

  make_exams_write_lops(name = NULL, auto_scramble = TRUE, ...)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
nsamp	integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir	character. The default is the current working directory.
name	character. A name prefix for resulting exercises.
quiet	logical. Should output be suppressed when calling xweave?
edir	character specifying the path of the directory (along with its sub-directories) in which the files in file are stored (see also xexams).
tdir	character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up (i.e., existing files are deleted) and only certain temporary files are preserved.
sdir	character specifying a directory for storing supplements, by default this is chosen via tempfile.
verbose	logical. Should information on progress of exam generation be reported?
solution	logical. Should the solution be included in the HTML output?
doctype	character vector with a DOCTYPE tag for the HTML page. By default HTML4 is employed.
head	character vector for the head tag. By default a simple header is employed, setting the font to Arial.
resolution, width, height	numeric. Options for rendering PNG (or SVG) graphics passed to xweave.
svg	logical. Should graphics be rendered in SVG or PNG (default)?
encoding	character, ignored. The encoding is always assumed to be UTF-8.
envir	argument passed to xweave (which passes it to knit).
engine	argument passed to xweave indicating whether "Sweave" (default) or "knitr" should be used for rendering Rnw exercises.
converter	character. Workhorse function for transforming LaTeX code to HTML.
base64	logical. Should supplementary files be embedded using Base 64 coding? Argument base64 may also be a character vector of file suffixes that should be encoded, e.g. base64 = c("png", "rda") will only encode PNG images and binary .rda files. If set to NULL only image files will be encoded.
auto_scramble	logical. Should answers be scrambled automaticall?
...	arguments passed on to make_exercise_transform_html.

Details

exams2lops will produce a .zip file that may be uploaded. It proceeds by (1) calling xweave on each exercise, (2) reading the resulting LaTeX code, (3) transforming the LaTeX code to HTML, and (4) embedding the HTML code in a XML file using the LOPS exam server XML format (WU Wien).

For steps (1) and (2) the standard drivers in xexams are used. In step (3), a suitable transformation function is set up on the fly using make_exercise_transform_html, see also the details section in exams2html.

For step (4) a simple writer function is set up on the fly that embeds the transformed HTML code into the final XML files for each question and the exam.

Note that in make_exams_write_lops only multiple and single choice questions are supported at the moment, since the LOPS exam server XML format (WU Wien) is used to generate printed versions for large scale multiple choice exams. In addition, only images of the question/questionlist/solution/solutionlist should be generated, since the server has only minimum support for e.g. MathML markup used to produce mathematical formulas.

Value

exams2lops returns a list of exams as generated by xexams.

make_exams_write_lops eturns a function that generates the XML code for the question in LOPS exam server format (WU Wien).

References

Zeileis A, Umlauf N, Leisch F (2014). Flexible Generation of E-Learning Exams in R: Moodle Quizzes, OLAT Assessments, and Beyond. Journal of Statistical Software, 58(1), 1–36. doi:10.18637/jss.v058.i01.

See Also

xexams, ttm, tth, tex2image, make_exercise_transform_html,

Examples

## Not run: 
## output directory
dir.create(mydir <- tempfile())

## generate the exam
exams2lops(c("scatterplot.Rmd", "boxplots.Rmd"), dir = mydir)
dir(mydir)

## End(Not run)

---

Generation of Exams in Moodle XML Format

Description

Automatic generation of exams in Moodle XML format.

Usage

exams2moodle(file, n = 1L, nsamp = NULL, dir = ".",
    name = NULL, quiet = TRUE, edir = NULL,
    tdir = NULL, sdir = NULL, verbose = FALSE, rds = FALSE,
    resolution = 100, width = 4, height = 4, svg = FALSE, encoding = "UTF-8",
    iname = TRUE, stitle = NULL,
    testid = FALSE, zip = FALSE, num = NULL, mchoice = NULL,
    schoice = mchoice, string = NULL, cloze = NULL,
    points = NULL, rule = NULL, pluginfile = TRUE, forcedownload = FALSE,
    converter = "pandoc-mathjax", envir = NULL, engine = NULL,
    table = "table_shade", css = NULL, ...)

  make_question_moodle(name = NULL, solution = TRUE,
    shuffle = FALSE, penalty = 0, answernumbering = "abc",
    usecase = FALSE, cloze_mchoice_display = NULL, cloze_schoice_display = NULL,
    truefalse = c("True", "False"), enumerate = FALSE, abstention = NULL,
    eval = list(partial = TRUE, negative = FALSE, rule = "false2"),
    essay = NULL, numwidth = NULL, stringwidth = NULL,
    css = NULL)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
nsamp	integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir	character. The default is the current working directory.
name	character. A name prefix for resulting exercises and ZIP file.
quiet	logical. Should output be suppressed when calling xweave?
edir	character specifying the path of the directory (along with its sub-directories) in which the files in file are stored (see also xexams).
tdir	character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up (i.e., existing files are deleted) and only certain temporary files are preserved.
sdir	character specifying a directory for storing supplements, by default this is chosen via tempfile.
verbose	logical. Should information on progress of exam generation be reported?
rds	logical indicating whether the return list should also be saved as an RDS data file.
resolution, width, height	numeric. Options for rendering PNG (or SVG) graphics passed to xweave.
svg	logical. Should graphics be rendered in SVG or PNG (default)?
encoding	character, ignored. The encoding is always assumed to be UTF-8.
envir	argument passed to xweave (which passes it to knit).
engine	argument passed to xweave indicating whether "Sweave" (default) or "knitr" should be used for rendering Rnw exercises.
table	character or logical. Control the style for tables in an exercise via a custom class: "table_shade" (equivalent to table = TRUE), "table_rule", and "table_grid" being provided. See also the details below.
css	character. A character string (or vector) containing the path(s) to CSS style file(s). Alternatively, a string (or vector) with a <style> tag to be included in every exercise. This is used internally for the table styles above, see also the details below.
iname	logical. Should the exam name be included in the path in the <category> tag in the final XML file? This option may be useful when questions should be added to certain already existing question banks, i.e. iname = TRUE will include the exam name by $course$/ExamName/.
stitle	character. For the questions specified in argument file, additional section titles may be set. The section titles will then be added to the <category> tag in the final XML file (see also argument iname), i.e. the section name for each question will be written to $course$/ExamName/SectionName. Note that section names may also be provided in the \exsection{} tag in the exercise file of the question. However, section names that are specified in stitle will overwrite \exsection{} tags. stitle may also include NA, e.g. stitle = c("Exercise 1", NA, "Exercise 3").
testid	logical. Should an unique test id be added to the exam name.
zip	logical. Should the resulting XML file be zipped?
num	function or named list applied to numerical (i.e., num) questions. If num is a function, this will be used to set up the question XML code. If num is a list, such a function is generated on the fly via make_question_moodle using the arguments in the list. For example, num = list(solution = FALSE) can be used to suppress embedding the solution text in the XML.
mchoice, schoice, string, cloze	function or named list applied to multiple choice, single choice, string, and cloze questions (i.e., type mchoice, schoice, string, and cloze), respectively. For more guidance see argument num and the details below.
points	integer. How many points should be assigned to each exercise? Note that this argument overules any exercise points that are provided within an "\expoints{}" tag in the exercise file. The vector of points supplied is expanded to the number of exercises in the exam.
rule	character specifying which rule to use for negative partial credits. See function exams_eval. Note that Moodle is somewhat restrictive about the number of multiple-choice alternatives when using partial credits (see below for details).
pluginfile	logical. Should supplements be included in the Moodle XML file via Moodle's Pluginfile mechanism? This is the default but may not work with older versions of Moodle (<2.5). If set to FALSE supplements like graphics and data are included as data URIs.
forcedownload	logical. Should all supplementary links be forced to download when clicked (as opposed to opening in the browser)? Only supported if pluginfile = TRUE. If forcedownload = FALSE the behavior typically depends on the browser, user settings, and file type.
solution	logical. Should the question solution, if available, be added in the question XML?
shuffle	For mchoice and schoice exercises, if set to TRUE will force Moodle to additionally shuffle the provided answer list.
penalty	numeric. Specifies the penalty tag for a question.
answernumbering	character. Specifies how choice questions should be numbered, allowed values are: "abc" (default), "ABCD", "123" or "none".
usecase	logical. Should string questions be case sensitive or not.
cloze_mchoice_display, cloze_schoice_display	character. In cloze questions, the user may set the visual appearance of choice questions. If NULL (default), "MULTIRESPONSE" (column of checkboxes) is used for mchoice questions and "MULTICHOICE" (drop-down menu) for schoice questions unless math markup is present in the question list. The latter is not rendered in drop-down menus and hence "MULTICHOICE_V" (radio buttons, vertical column) are used. Other options include a horizontal row of either checkboxes ("MULTIRESPONSE_H") or radio buttons ("MULTICHOICE_H"), respectively. Shuffled versions of all display types are also available (since Moodle 3.0) by appending an "S", e.g., "MULTICHOICE_S" or "MULTICHOICE_VS" etc.
truefalse	character of length 2. For single choice answers in cloze questions, the user may specify the possible options shown.
enumerate	logical. In cloze questions, if set to TRUE, the answerlist and solutionlist will be enumerated.
abstention	character or logical. Should an explicit abstention option be added in single/multiple choice exercises? The character text specified is used for an extra button in Moodle which (when selected) always leads to zero points.
eval	named list, specifies the settings for the evaluation policy, see function exams_eval.
essay	logical. Should string questions be rendered into Moodle shortanswer or essay questions? The default is to use shortanswer unless either essay=TRUE or the exercise's metainformation is set to essay.
numwidth, stringwidth	logical, numeric, or character. Should the width of all num or string sub-items, respectively, in a cloze be fixed to the same width? This can be accomplished by adding a wrong solution with a suitable length to all sub-items in Moodle XML. The default (NULL or equivalently FALSE) is not to do so but let Moodle decide the width of each cell based on the respective correct solution. Alternatively, the arguments can be set to TRUE (then the maximum width from the correct solutions is used), an integer (indicating the maximum width) or a character (like "1111111", to be used as the wrong solution). Both arguments can also be set through exextra tags in each of the exercises' meta-information.
converter, ...	arguments passed on to make_exercise_transform_html. The default for converter is "pandoc-mathjax" which assumes that the quiz is imported in a Moodle site with MathJax plugin activated (which is the default setting in Moodle). For using MathML instead of MathJax the converter can be set to NULL or "pandoc-mathml" etc. For details see Zeileis (2019).

Details

exams2moodle produces an XML file that may be uploaded into Moodle. It proceeds by (1) calling xweave on each exercise, (2) reading the resulting Markdown or LaTeX text, (3) transforming the text to HTML, and (4) embedding the HTML code in a Moodle XML file for exams/quizzes.

For steps (1) and (2) the standard drivers in xexams are used. In step (3), a suitable transformation function is set up on the fly using make_exercise_transform_html, see also the details section in exams2html.

For step (4), the function will cycle through all questions and exams to generate the final Moodle XML file. The structure of the resulting XML file is such that one category will be set for the exam/quiz using the exam/quiz name (or this category may be suppressed (i.e., not included in the XML) by setting iname = FALSE), followed by one category/section for each question, while the replicates of each question will be included in the corresponding category/section. Note that category/section names may also be provided in the exsection tag in the exercise files, or within argument stitle in exams2moodle. This may be useful when questions should automatically be added to already existing Moodle question banks. (See also the argument descriptions above.)

The XML code for each question type (numeric, multiple-choice, etc.) is set up by separate functions that can be specified through the separate arguments num, mchoice, schoice, string, and cloze in exams2moodle. While it is possible to pass a suitable function to these arguments, it is more common to set suitable functions up on the fly using make_question_moodle. In this case, the arguments num, mchoice, schoice, string and cloze can be lists of arguments to pass on to make_question_moodle. For example, to suppress numbering the multiple-choice answer items with a/b/c/... one has to specify mchoice = list(answernumbering = "none") (which, by default, also gets passed on to schoice).

When using partial credits for multiple-choice exercises, only certain numbers of alternatives are supported in Moodle. This is because the Moodle XML format just supports certain percentages which can be added or subtracted from the score of an item. Therefore, it may not be possible to use partial credits for certain combinations of true and false answer alternatives when the overall number of alternatives is greater than 10.

When specifying cloze exercises, two approaches are possible: Either a answerlist with all questions is provided within the question or, alternatively, the answer fields can be placed anywhere in the question text. For the latter, the strings ##ANSWER1##, ##ANSWER2##, etc., have to be used, see the exercises "boxhist2" and "fourfold2" for illustration and Appendix C in Zeileis et al. (2014) for further details.

To fix the width of numeric answer fields withing cloze exercises (in order not to convey any clues about the length of the correct solution), the exextra[numwidth] metainformation command can be used in the exercise file. For example, it can be set to \exextra[numwidth,logical]{TRUE}, \exextra[numwidth,numeric]{5}, or \exextra[numwidth,character]{100.0}.

In order to generate open-ended text questions in Moodle one can use string questions and then additionally set exstringtype to essay and/or file. See the "essayreg" question for a worked example. On top of the basic exstringtype one can make further Moodle-specific customizations via some exextra options, namely:

• essay: logical. Enables the essay function.

• format: character. Type of text field (one of: plain, editor, editorfilepicker monospaced noinline)

• required: logical. Whether an answer is required.

• attachments: numeric. How many attachments can be uploaded.

• attachmentsrequired: numeric. The number of required attachments.

To control the style used for rendering the HTML in Moodle exercises, it is possible to include some custom CSS (cascading style sheets) code via the argument css. In particular, the exams2moodle function leverages this for table formatting. It includes its own CSS for this purpose if one of the classes "table_shade" (rows highlighted with different shades of gray), "table_rule" (with horizontal lines), or "table_grid" (with both horizontal and vertical lines) is used.

Value

exams2moodle returns a list of exams as generated by xexams.

make_question_moodle returns a function that generates the XML code for the question in Moodle's XML standard.

References

Dougiamas M, et al. (2022). Moodle, Version 4.0. https://moodle.org/.

MoodleDocs (2022). Moodle XML Format. https://docs.moodle.org/en/Moodle_XML

Zeileis A, Umlauf N, Leisch F (2014). Flexible Generation of E-Learning Exams in R: Moodle Quizzes, OLAT Assessments, and Beyond. Journal of Statistical Software, 58(1), 1–36. doi:10.18637/jss.v058.i01.

Zeileis A (2019). Mathematical Notation in Online R/exams. https://www.R-exams.org/tutorials/math/

See Also

xexams, ttm, tth, tex2image, make_exercise_transform_html,

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## define an exams (= list of exercises)
myexam <- list(
  "boxplots.Rmd",
  c("tstat.Rmd", "ttest.Rmd", "confint.Rmd"),
  c("regression.Rmd", "anova.Rmd"),
  c("scatterplot.Rmd", "boxhist.Rmd"),
  "relfreq.Rmd"
)

## output directory
dir.create(mydir <- tempfile())

## generate moodle quiz in temporary directory
## using a few customization options
exams2moodle(myexam, n = 3, dir = mydir,
  num = list(solution = FALSE),
  mchoice = list(shuffle = TRUE)
)
dir(mydir)

---

Generation of Written Exams for Automatic Evaluation

Description

Generation of exams in PDF format that can be printed, scanned, and evaluated automatically.

Usage

exams2nops(file, n = 1L, nsamp = NULL, dir = ".", name = NULL,
    language = "en", title = "Exam", course = "",
    institution = "R University", logo = "Rlogo.png", date = Sys.Date(), 
    replacement = FALSE, intro = NULL, blank = NULL, duplex = TRUE, pages = NULL,
    usepackage = NULL, header = NULL, encoding = "UTF-8", startid = 1L,
    points = NULL, showpoints = FALSE, samepage = FALSE, newpage = FALSE,
    twocolumn = FALSE, reglength = 7L, seed = NULL, ...)

  make_nops_template(n, replacement = FALSE, intro = NULL, blank = NULL,
    duplex = TRUE, pages = NULL, file = NULL, nchoice = 5, encoding = "UTF-8",
    samepage = FALSE, newpage = FALSE, twocolumn = FALSE, reglength = 7L)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file (in exams2nops) and the number of exercises per exam (in make_nops_template), respectively.
nsamp	integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir	character. The default is either display on the screen (if n = 1L) or the current working directory.
name	character. A name prefix for resulting exams and RDS file.
language	character. Path to a DCF file with a language specification. See below for the list of supported languages.
title	character. Title of the exam, e.g., "Introduction to Statistics".
course	character. Optional course number, e.g., "101".
institution	character. Name of the institution at which the exam is conducted.
logo	character. Path to a logo image (in a file format supported by pdfLaTeX). If set to NULL, the logo is omitted.
date	character or "Date" object specifying the date of the exam.
replacement	logical. Should a replacement exam sheet be included?
intro	character. Either a single string with the path to a .tex file or a vector with with LaTeX code for optional introduction text on the first page of the exam.
blank	integer. Number of blank pages to be added at the end. (Default is chosen to be half of the number of exercises.) If pages is specified, blank can also be a vector of length two with blank pages before and after the extra pages, respectively.
duplex	logical. Should blank pages be added after the title page (for duplex printing)?
pages	character. Path(s) to additional PDF pages to be included at the end of the exam (e.g., formulary or distribution tables).
usepackage	character. Names of additional LaTeX packages to be included.
header	character vector or list. Either a character vector with LaTeX code to include in the header or a named list with further options to be passed to the LaTeX files.
encoding	character, ignored. The encoding is always assumed to be UTF-8.
startid	integer. Starting ID for the exam numbers (defaults to 1).
points	integer. How many points should be assigned to each exercise? Note that this argument overules any exercise points that are provided within the expoints tags of the exercise files (if any). The vector of points supplied should either have length 1 or the number of exercises in the exam.
showpoints	logical. Should the PDF show the number of points associated with each exercise (if specified in the Rnw/Rmd exercise or in points)?
samepage	logical. Should the itemized question lists be forced to be on the same page?
newpage	logical. Should each exercise start on a new page? (Technically, a page break is added after each exercise.)
twocolumn	logical. Should a two-column layout be used?
reglength	integer. Number of digits in the registration ID. The default is 7 and it can be increased up to 10. In case of reglength < 7, internally reglength = 7 is enforced (and thus necessary in the registration CSV file) but the initial ID digits are fixed to 0 in the exam sheet and corresponding boxes ticked already.
seed	integer matrix or logical. Either NULL (default), logical, or a matrix of random seeds for each possible exercise to be set prior to calling driver@sweave. If NULL no random seeds are set. If a matrix, the number of rows must be n and the number of columns must correspond to unlist(file). If TRUE a suitable matrix of seeds is sampled.
...	arguments passed on to exams2pdf.
nchoice	character. The number of choice alternatives per exercise.

Details

exams2nops is a convenience interface for exams2pdf with a dynamically generated title page which can be printed, scanned with nops_scan and evaluated automatically by nops_eval. It is originally intended for single- and multiple choice (schoice/mchoice) questions only but has also some limited support for open-ended (string) questions.

The exam sheet consists of various sections where information is either printed our filled in by the students. The section with personal data is just for human readers, it is not read automatically. The registration number has to be filled in in digits and also marked with corresponding crosses where only the latter is read automatically. The exam ID/type/scrambling are printed directly into the PDF and read automatically after scanning. Note that the font in the PDF must not be modified for the reading step to work reliably. (A sans-serif font is used and hence the sfmath LaTeX package is also used - if it is installed.) The questions can have up to five alternatives which have to answered by the students. The crosses are read automatically where both empty and completely filled boxes are regarded as not crossed.

Tutorial for NOPS workflow: https://www.R-exams.org/tutorials/exams2nops/.

Limitations: (a) Only up to five answer alternatives per question are supported. (b) Currently, only up to 45 questions are supported. If you have more questions, consider splitting the entire exam up into two NOPS exams. (c) Only up to 3 open-ended questions can be included. (d) Each question must have the same number of answer alternatives and the same number of points across random replications. For example, the n replications drawn for the first exercise all need, say, five alternatives and two points. Then, the second exercise may have, say, four alternatives and five points and so on. But this may not be mixed within the same exercise number.

The examples below show how PDF exams can be generated along with an RDS file with (serialized) R data containing all meta-information about the exam. The PDFs can be printed out for conducting the exam and the exam sheet from the first page then needs to be scanned into PDF or PNG images. Then the information from these scanned images can be read by nops_scan, extracting information about the exam, the participants, and the corresponding answers (as described above). The ZIP file produced by nops_scan along with the RDS of the exam meta-information and a CSV file with participant information can then be used by nops_eval to automatically evaluate the whole exam and producing HTML reports for each participant. See nops_eval for a worked example.

Currently, up to three open-ended string questions can also be included. These do not generate boxes on the first exam sheet but instead a second exam sheet is produced for these open-ended questions. It is assumed that a human reader reads these open-ended questions and then assigns points by marking boxes on this separate sheet. Subsequently, this sheet can also be read by nops_scan.

The language elements can be specified through a relatively simple text file and the package already ships with: English ("en"), Bulgarian ("bg"), Catalan ("ca"), Croatian ("hr"), Czech ("cz"), Danish ("da"), Dutch ("nl"), Finnish ("fi"), French ("fr"), Galician ("gl"), German ("de"), Hungarian ("hu"), Italian ("it"), Japanese ("ja"), Korean ("ko"), Norwegian (Bokmål, "no"), Polish ("pl"), Portuguese ("pt-PT" or "pt-BR"; also "pt" is synonymous with "pt-PT"), Romanian ("ro"), Russian ("ru"), Serbian ("sr"), Slovak ("sk"), Slovenian ("sl"), Spanish ("es"), Swiss German ("gsw"), Turkish ("tr"), Vietnamese ("vi"). Note that the language names correspond to the ISO 639 codes (https://www.loc.gov/standards/iso639-2/php/code_list.php) or IETF language tags (https://en.wikipedia.org/wiki/IETF_language_tag) if no ISO 639 codes exists (as for Brazilian Portuguese). For more details about the underlying text file in DCF format, see https://www.R-exams.org/tutorials/nops_language/

Value

A list of exams as generated by xexams is returned invisibly.

Examples

## load package and enforce par(ask = FALSE)
## additionally, for simplicity, enforce using the basic
## tools::texi2dvi() LaTeX interface instead of the more
## flexible/robust tinytex::latexmk()
library("exams")
oopt <- options(device.ask.default = FALSE, exams_tex = "tools")

## define an exam (= list of exercises)
myexam <- list(
  "tstat2.Rmd",
  "ttest.Rmd",
  "relfreq.Rmd",
  "anova.Rmd",
  c("boxplots.Rmd", "scatterplot.Rmd"),
  "cholesky.Rmd"
)

if(interactive()) {
## compile a single random exam (displayed on screen)
exams2nops(myexam, duplex = FALSE, language = "de")
}

## create multiple exams on the disk (in a
## temporary directory)
dir.create(mydir <- tempfile())

## generate NOPS exam in temporary directory
set.seed(403)
ex1 <- exams2nops(myexam, n = 2, dir = mydir)
dir(mydir)


## use a few customization options: different
## university/logo and language/title
## with a replacement sheet but for non-duplex printing
set.seed(403)
ex2 <- exams2nops(myexam, n = 2, dir = mydir,
  institution = "Universit\\\"at Innsbruck",
  name = "uibk", logo = "uibk-logo-bw.png",
  title = "Klausur", language = "de",
  replacement = TRUE, duplex = FALSE)
dir(mydir)


options(exams_tex = oopt$exams_tex)

---

Generation of Exams for OpenOlat

Description

Automatic generation of exams in QTI 2.1 (or 1.2) with some tweaks optimized for OpenOlat.

Usage

exams2openolat(file, n = 1L, dir = ".", name = "olattest",
    qti = "2.1", config = TRUE, converter = "pandoc-mathjax", table = TRUE,
    maxattempts = 1, cutvalue = NULL, ...)

  openolat_config(cancel = FALSE, suspend = FALSE, scoreprogress = FALSE,
    questionprogress = FALSE, maxscoreitem = TRUE, menu = TRUE,
    titles = TRUE, notes = FALSE, hidelms = TRUE, hidefeedbacks = FALSE,
    blockaftersuccess = FALSE, attempts = 1, anonym = FALSE,
    manualcorrect = FALSE)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
dir	character. The default is the current working directory.
name	character. A name prefix for resulting exercises and ZIP file.
qti	character indicating whether QTI "1.2" or "2.1" (default) should be generated.
config	logical or named list with arguments to be passed to function openolat_config, for adding an OpenOlat-specifc configuration file QTI21PackageConfig.xml to the exam. If set to config = FALSE, no configuration file is added (which was the default behavior up to R/exams 2.3.6). Setting config = TRUE is equivalent to config = list() or config = openolat_config() (which is the current default, starting from R/exams 2.4.0). Custom configurations can be specified using the syntax config = list(...), see the details on the possible arguments below.
converter	character passed on to make_exercise_transform_html, indicating the type of converter from LaTeX/Markdown to HTML. Defaults to HTML with MathJax (and OpenOlat-specific fixups).
table	logical or character. Should a dedicated table class be used in the HTML for OpenOlat? For details see below.
maxattempts	integer. The maximum attempts for one question within an exam. Set to Inf or 0 for unlimited attempts. For a finite number of attempts this must be smaller than 100000. See also attempts below for allowing more than one attempt for the exam as a whole.
cutvalue	numeric. The number of points at which the exam is passed. If set to NULL (default) or equivalently NA, no cutvalue is set and the result of the exam is just the number of points.
...	arguments passed on to exams2qti21 (or exams2qti12, respectively). See the corresponding manual pages for further important arguments such as solutionswitch, casesensitive, cloze_schoice_display navigation, shufflesections, eval, selection, among many others.
cancel	logical. Are participants allowed to cancel an exam after starting it? (Default: FALSE.)
suspend	logical. Are participants allowed to suspend an exam after starting it (in order to continue it later)? (Default: FALSE.)
scoreprogress	logical. Should the progress of the score/points achieved so far be displayed during the exam? (Default: FALSE.)
questionprogress	logical. Should the number of questions solved so far be displayed during the exam? (Default: FALSE.)
maxscoreitem	logical. Should the maximum score of a question/item be displayed? (Default: TRUE.)
menu	logical. Should the menu be displayed during the exam? (Default: TRUE.)
titles	logical. Should question titles be displayed during the exam? (Default: TRUE.)
notes	logical. Should participants be enabled to take notes in OpenOlat during the exam? (Default: FALSE.)
hidelms	logical. Should access to the OpenOlat learning management system be hidden during the exam? (Default: TRUE.)
hidefeedbacks	logical. Should feedbacks be hidden? (Default: FALSE.)
blockaftersuccess	logical. Should the exam be blocked after successful completion? (Default: FALSE.)
attempts	integer. How many attempts are allowed for the exam as a whole? Note that this should not be confused with the maxattempts for a question within the exam (see above).
anonym	logical. Should anonymous users be allowed to take the exam? (Default: FALSE.)
manualcorrect	logical. Should the points and pass/fail status from the exam be evaluated manually? (Default: FALSE.)

Details

exams2openolat is a convenience interface to exams2qti12 and exams2qti21 for generating either QTI 1.2 or 2.1 (default) output with some small tweaks for OpenOlat. Specifically, the MathJax and table output from pandoc is post-processed as expected by OpenOlat. See the corresponding manual page for many more arguments that are supported by exams2openolat.

Dedicated table classes currently include: Full-width tables with borders ("b_grid", "b_border") or without ("b_full", "b_borderless"). Or regular tables without background color ("b_middle") or with white grid and color background ("b_gray", "b_red", "b_green", "b_blue", "b_yellow"). Setting table = TRUE corresponds to table = "b_gray".

In addition to controlling the behavior of the exam and its questions via the standard QTI 2.1 options (see exams2qti21), it is possible to specify certain OpenOlat-specific configurations via an additional XML file to be added to the ZIP output. This is why these options are not part of exams2qti21 but are provided in the separate wrapper function openolat_config. As the resulting XML configuration file is not part of the official OpenOlat interface, it may be subject to more changes in the future.

Value

exams2openolat returns a list of exams as generated by xexams.

See Also

exams2qti12, exams2qti21

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## define an exams (= list of exercises)
myexam <- list(
  "boxplots.Rmd",
  c("tstat.Rmd", "ttest.Rmd", "confint.Rmd"),
  c("regression.Rmd", "anova.Rmd"),
  c("scatterplot.Rmd", "boxhist.Rmd"),
  "relfreq.Rmd"
)

## output directory
dir.create(mydir <- tempfile())

## generate .zip with OpenOlat test in temporary directory
exams2openolat(myexam, n = 3, dir = mydir)
dir(mydir)

---

Generation of Exams via Pandoc

Description

Automatic generation of exams via pandoc, by default in docx format.

Usage

exams2pandoc(file, n = 1L, nsamp = NULL, dir = ".",
    name = "pandoc", type = "docx", template = "plain.tex",
    question = "Question", solution = "Solution",
    header = list(Date = Sys.Date()), inputs = NULL, options = NULL,
    quiet = TRUE, resolution = 100, width = 4, height = 4, svg = FALSE,
    encoding = "UTF-8", envir = NULL, engine = NULL,
    edir = NULL, tdir = NULL, sdir = NULL, verbose = FALSE,
    points = NULL, exshuffle = NULL, ...)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
nsamp	integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir	character specifying the output directory (default: current working directory). If only a single HTML file is produced and no dir is explicitly specified, the file is displayed in the browser rather than saved in dir.
name	character. A name prefix for resulting exercises.
type	character. The file type to convert to using pandoc. The default is "docx" (but other choices are also supported, e.g., "odt", "html", "markdown" etc.).
template	character. A specification of a template in either LaTeX, HTML, or Markdown format. The default is to use the "plain.tex" file provided but an alternative "plain.html" is also available.
question	character or logical. Should the question be included in the output? If question is a character it will be used as a header for resulting questions.
solution	character or logical, see argument question.
header	list. A list of named character strings (or functions generating such) to be substituted in the template.
inputs	character. Names of files that are needed as inputs for the template (e.g., images, headers). Either the full path must be given or the file needs to be in edir.
options	character. A string of options to be passed on to pandoc_convert.
quiet	logical. Should output be suppressed when calling xweave?
resolution, width, height	numeric. Options for rendering PNG (or SVG) graphics passed to xweave.
svg	logical. Should graphics be rendered in SVG or PNG (default)?
encoding	character, ignored. The encoding is always assumed to be UTF-8.
envir	argument passed to xweave (which passes it to knit).
engine	argument passed to xweave indicating whether "Sweave" (default) or "knitr" should be used for rendering Rnw exercises.
edir	character specifying the path of the directory (along with its sub-directories) in which the files in file are stored (see also xexams).
tdir	character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up (i.e., existing files are deleted) and only certain temporary files are preserved.
sdir	character specifying a directory for storing supplements, by default this is chosen via tempfile.
verbose	logical. Should information on progress of exam generation be reported?
points	integer. How many points should be assigned to each exercise? Note that this argument overules any exercise points that are provided within the expoints tags of the exercise files (if any). The vector of points supplied should either have length 1 or the number of exercises in the exam.
exshuffle	logical or integer. If the exshuffle argument is non-NULL it is used to overrule the exshuffle tag from the file (e.g., exshuffle = FALSE can be used to keep all available answers without permutation).
...	currently not used.

Details

exams2pandoc can generate exams in various output formats (by default docx) using xexams and pandoc_convert. It proceeds by (1) calling xweave on each exercise, (2) reading the resulting LaTeX or Markdown code, (3) transforming the code to the markup of some exam template (either LaTeX, HTML, or Markdown), (4) embedding the code in a template and converting it to the desired output format using pandoc.

For steps (1) and (2) the standard drivers in xexams are used.

For step (3) a suitable transformation function is set up on the fly using make_exercise_transform_pandoc. Depending on which format the template uses (LaTeX or HTML or Markdown) the transformation may or may not be trivial.

For step (4) all exercises are inserted into the template (and also replacing certain additional tags from header) and then pandoc_convert is used to convert to the desired output format (one file for each exam). In principle, all output types of pandoc are supported, but most of them have not been tested. (The main motivation for exams2pandoc was the generation of "docx" or "odt" files.)

Value

exams2pandoc returns a list of exams as generated by xexams.

See Also

xexams, pandoc_convert

Examples

## load package and enforce par(ask = FALSE)
options(device.ask.default = FALSE)

## define an exams (= list of exercises)
myexam <- list(
  "boxplots.Rmd",
  c("tstat.Rmd", "ttest.Rmd", "confint.Rmd"),
  c("regression.Rmd", "anova.Rmd"),
  c("scatterplot.Rmd", "boxhist.Rmd"),
  "relfreq.Rmd"
)

## output directory
dir.create(mydir <- tempfile())

## compile two docx and odt versions each
set.seed(1090)
exams2pandoc(myexam, n = 2, dir = mydir, type = "docx")
set.seed(1090)
exams2pandoc(myexam, n = 2, dir = mydir, type = "odt")

---

Generation of Exam/Quiz Sessions in Particify Format

Description

Interface for generating comma-separated files for import in the audience response system Particify.

Usage

exams2particify(file, n = 1L, dir = ".", name = "particify",
  quiet = TRUE, resolution = 100, width = 4, height = 4, svg = FALSE,
  abstention = FALSE, fix_choice = FALSE, exshuffle = NULL, ...)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
dir	character. The default is either display on the screen or the current working directory.
name	character. A name prefix for resulting exercises and RDS file.
quiet	logical. Should output be suppressed when calling xweave and texi2dvi.
resolution, width, height	numeric, passed to xweave.
svg	logical. Should graphics be rendered in SVG or PNG (default)?
abstention	logical. Are abstentions allowed for choice questions?
fix_choice	logical. Should math markup be removed in single and multiple choice lists? (This may be needed for older Particify versions where math markup is rendered in the question itself but not the choice list.)
exshuffle	logical or integer. If the exshuffle argument is non-NULL it is used to overrule the exshuffle tag from the file (e.g., exshuffle = FALSE can be used to keep all available answers without permutation).
...	arguments passed on to xexams.

Details

exams2particify generates exams in comma-separated values (CSV) format that can be imported into the audience response system Particify (https://particify.de/) using xexams. In particular, single-choice and multiple-choice exercises are fully supported while num and string question are converted to open-ended text questions.

To import the generated CSV file, click on "Create question series" in Particify and then select Settings > Import/Export > Import series.

Internally, the exams2particify function proceeds by (1) calling xweave on each exercise, (2) reading the resulting Markdown/LaTeX text, (3) transforming the text to Markdown, and (4) embedding the Markdown text into the CSV format for Particify. For steps (1) and (2) the standard drivers in xexams are used. For step (3) a suitable transformation function is set up on the fly using make_exercise_transform_pandoc. For step (4) a custom writer function is set up on the fly.

Value

A list of exams as generated by xexams is returned invisibly.

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## output directory
dir.create(mydir <- tempfile())

## create a CSV file particify-1.csv for import in Particify
exams2particify(c("swisscapital.Rmd", "capitals.Rmd", "deriv2.Rmd",
  "boxplots.Rmd", "ttest.Rmd", "function.Rmd"), dir = mydir)

---

Generation of Exams in PDF Format

Description

Automatic generation of exams in PDF format.

Usage

exams2pdf(file, n = 1L, nsamp = NULL, dir = ".", template = "plain", 
    inputs = NULL, header = list(Date = Sys.Date()), name = NULL, 
    control = NULL, encoding = "UTF-8", quiet = TRUE, transform = NULL,
    edir = NULL, tdir = NULL, sdir = NULL, texdir = NULL, texengine = "pdflatex",
    verbose = FALSE, rds = FALSE, points = NULL, seed = NULL, 
    attachfile = FALSE, exshuffle = NULL, ...)
  
  make_exams_write_pdf(template = "plain", inputs = NULL,
    header = list(Date = Sys.Date()), name = NULL, encoding = "UTF-8",
    quiet = TRUE, control = NULL, texdir = NULL, texengine = "pdflatex")

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
nsamp	integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir	character specifying the output directory (default: current working directory). If only a single PDF file is produced and no dir is explicitly specified, the file is displayed on the screen rather than saved in dir.
template	character. A specification of a LaTeX template. The package currently provides "exam", "solution", "plain", among others. The default is to use the "plain.tex" file unless there are Rmd exercises in file for which "plain8.tex" is used. For further details see below.
inputs	character. Names of files that are needed as inputs during LaTeX compilation (e.g., style files, headers). Either the full path must be given or the file needs to be in edir.
header	list. A list of further options to be passed to the LaTeX files.
name	character. A name prefix for resulting exercises, of the same length as template. By default (if name is NULL) the base name of template is used.
control	A list of control arguments for the appearance of multiple choice results (see details).
encoding	character, ignored. The encoding is always assumed to be UTF-8.
quiet	logical. Should output be suppressed when calling xweave and texi2dvi.
transform	function. An optional transform driver passed to xexams (by default no transformation is used).
edir	character specifying the path of the directory (along with its sub-directories) in which the files in file are stored (see also xexams).
tdir	character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up (i.e., existing files are deleted) and only certain temporary files are preserved.
sdir	character specifying a directory for storing supplements, by default this is chosen via tempfile.
texdir	character specifying a directory for running texi2dvi in. By default this is chosen via tempfile (and deleted again) but, if specified by the user, the temporary LaTeX files from the last iteration are preserved and not deleted. This is intended especially for debugging purposes.
texengine	character. Passed to latexmk if tinytex is available.
verbose	logical. Should information on progress of exam generation be reported?
rds	logical indicating whether the return list should also be saved as an RDS data file.
points	integer. How many points should be assigned to each exercise? Note that this argument overules any exercise points that are provided within the expoints tags of the exercise files (if any). The vector of points supplied should either have length 1 or the number of exercises in the exam.
seed	integer matrix or logical. Either NULL (default), logical, or a matrix of random seeds for each possible exercise to be set prior to calling driver@sweave. If NULL no random seeds are set. If a matrix, the number of rows must be n and the number of columns must correspond to unlist(file). If TRUE a suitable matrix of seeds is sampled.
attachfile	logical. Should the LaTeX commands url and href be replaced by attachfile commends when used for supplementary files? This enables embedding these supplementary files directly into the PDF when template loads the attachfile LaTeX package.
exshuffle	logical or integer. If the exshuffle argument is non-NULL it is used to overrule the exshuffle tag from the file (e.g., exshuffle = FALSE can be used to keep all available answers without permutation).
...	further arguments passed on to xweave.

Details

exams2pdf is a more flexible re-implementation of the old (version 1) exams function (Gruen and Zeileis 2009), using the new extensible xexams framework (Zeileis et al. 2014). A detailed introduction is provided in vignette("exams", package = "exams"), also pointing out relative advantages of the new interface.

exams2pdf proceeds by using make_exams_write_pdf to set up a custom driver$write function on the fly before calling xexams. This custom driver combines each exams with the desired template (and inputs etc.) and then calls texi2dvi on the resulting LaTeX file to produce PDF output. For a single exam (n = 1) the resulting PDF is displayed on screen (unless dir is explicitly specified) while for n > 1 the PDF files are stored in the output directory dir.

The argument control is specified by a named list, currently with elements mchoice.symbol and cloze.collapse. mchoice.symbol has to be a character vector with elements True and False, specifying the symbol used for the questionnaire output in the final PDF file. cloze.collapse specifies the character used for collapsing mchoice/schoice alternatives within a cloze exercise. By default, these are separated by " / " but with cloze.collapse = "\\\\" each alternative would be in a new line. Finally, cloze.collapse = "enumerate" can also be used which employs a nested enumerate environment. In the latter case, the questionnaire uses exclozechoice rather than exmchoice (see exam.tex or solution.tex for an illustration.

Value

exams2pdf returns a list of exams as generated by xexams.

make_exams_write_pdf returns a function that is suitable for being supplied as driver$write to xexams.

References

Gruen B, Zeileis A (2009). Automatic Generation of Exams in R. Journal of Statistical Software, 29(10), 1–14. doi:10.18637/jss.v029.i10.

Zeileis A, Umlauf N, Leisch F (2014). Flexible Generation of E-Learning Exams in R: Moodle Quizzes, OLAT Assessments, and Beyond. Journal of Statistical Software, 58(1), 1–36. doi:10.18637/jss.v058.i01.

See Also

xexams, exams, texi2dvi

Examples

## load package and enforce par(ask = FALSE)
##
## additionally, for simplicity, enforce using the basic
## tools::texi2dvi() LaTeX interface instead of the more
## flexible/robust tinytex::latexmk()
library("exams")
oopt <- options(device.ask.default = FALSE, exams_tex = "tools")

if(interactive()) {
## compile a single random exam (displayed on screen)
exams2pdf(list(
  "boxplots.Rmd",
  c("tstat.Rmd", "ttest.Rmd", "confint.Rmd"),
  c("regression.Rmd", "anova.Rmd"),
  "scatterplot.Rmd",
  "relfreq.Rmd"
))
}

options(exams_tex = oopt$exams_tex)

---

Generation of Exams in QTI 1.2 Format

Description

Automatic generation of exams in QTI 1.2 format.

Usage

exams2qti12(file, n = 1L, nsamp = NULL, dir = ".",
    name = NULL, quiet = TRUE, edir = NULL,
    tdir = NULL, sdir = NULL, verbose = FALSE, rds = FALSE,
    resolution = 100, width = 4, height = 4, svg = FALSE, encoding = "UTF-8",
    num = NULL, mchoice = NULL,
    schoice = mchoice, string = NULL, cloze = NULL,
    template = "qti12", duration = NULL,
    stitle = "Exercise", ititle = "Question",
    adescription = "Please solve the following exercises.",
    sdescription = "Please answer the following question.",
    maxattempts = 1, cutvalue = 0, solutionswitch = TRUE,
    zip = TRUE, points = NULL,
    eval = list(partial = TRUE, rule = "false2", negative = FALSE),
    converter = NULL, envir = NULL, engine = NULL, xmlcollapse = FALSE,
    flavor = c("plain", "openolat", "canvas", "ilias"), ...)

  make_itembody_qti12(rtiming = FALSE, shuffle = FALSE,
    rshuffle = shuffle, minnumber = NULL, maxnumber = NULL,
    defaultval = NULL, minvalue = NULL, maxvalue = NULL,
    cutvalue = NULL, enumerate = FALSE, digits = NULL,
    tolerance = is.null(digits), maxchars = 12,
    eval = list(partial = TRUE, rule = "false2", negative = FALSE),
    fix_num = TRUE, flavor = "plain")

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
nsamp	integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir	character. The default is the current working directory.
name	character. A name prefix for resulting exercises and ZIP file.
quiet	logical. Should output be suppressed when calling xweave?
edir	character specifying the path of the directory (along with its sub-directories) in which the files in file are stored (see also xexams).
tdir	character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up (i.e., existing files are deleted) and only certain temporary files are preserved.
sdir	character specifying a directory for storing supplements, by default this is chosen via tempfile.
verbose	logical. Should information on progress of exam generation be reported?
rds	logical indicating whether the return list should also be saved as an RDS data file.
resolution, width, height	numeric. Options for rendering PNG (or SVG) graphics passed to xweave.
svg	logical. Should graphics be rendered in SVG or PNG (default)?
encoding	character, ignored. The encoding is always assumed to be UTF-8.
num	function or named list applied to numerical (i.e., type num) questions. If num is a function, num will be used for generating the item body of the question, see function make_itembody_qti12(). If num is a named list, these arguments will be passed to function make_itembody_qti12().
mchoice, schoice, string, cloze	function or named list applied to multiple choice, single choice, string, and cloze questions (i.e., type mchoice, schoice, string, and cloze), respectively. See argument num for more details.
template	character. The QTI 1.2 template that should be used. Currently, the package provides "qti12.xml".
duration	integer. Set the duration of the exam in minutes.
stitle	character. A title that should be used for the sections. May be a vector of length 1 to use the same title for each section, or a vector containing different section titles.
ititle	character or NULL. A title that should be used for the assessment items. May be a vector of length 1 to use the same title for each item, or a vector containing different item titles. Note that the maximum of different item titles is the number of sections/questions that are used for the exam. Note, if ititle = NULL, simple numbering for the exercises will be used, however, if the exercise contains meta info extitle, this title will be used.
adescription	character. Description (of length 1) for the overall assessment (i.e., exam).
sdescription	character. Vector of descriptions for each section, omitted if empty (or NULL or FALSE).
maxattempts	integer. The maximum attempts for one question. This may also be a vector so that the maximum number of attempts varies across questions. A value of Inf or 0 signals that the attempts per question are not limited.
cutvalue	numeric. The cutvalue at which the exam is passed.
solutionswitch	logical. Should the question/item solutionswitch be enabled? In OLAT this means that the correct solution is shown after an incorrect solution was entered by an examinee (i.e., this is typically only useful if maxattempts = 1).
zip	logical. Should the resulting XML file (plus supplements) be zipped?
points	integer. How many points should be assigned to each exercise? Note that this argument overules any exercise points that are provided within an "\expoints{}" tag in the .Rnw file. The vector of points supplied is expanded to the number of exercises in the exam.
eval	named list, specifies the settings for the evaluation policy, see function exams_eval.
converter	character. Argument passed on to make_exercise_transform_html. The default for converter is set to "ttm" unless there are Rmd exercises in file where "pandoc" is used.
envir	argument passed to xweave (which passes it to knit).
engine	argument passed to xweave indicating whether "Sweave" (default) or "knitr" should be used for rendering Rnw exercises.
xmlcollapse	logical or character. Should line breaks be collapsed in the XML code. If TRUE everything is collapsed with spaces (" ") but other collapse characters could be supplied.
flavor	character. Which QTI 1.2 “flavor” should be used? Some learning management systems require that the QTI XML tags are used in a rather specific and idiosyncratic way. Typically, users should not set this argument directly but use the convenience interfaces exams2openolat, exams2canvas, or exams2ilias instead (which use the flavor argument internally along with further customizations).
rtiming, shuffle, rshuffle, minnumber, maxnumber, defaultval, minvalue, maxvalue	arguments used for QTI 1.2 item construction, for details see the XML specification (see IMS Global Learning Consortium, Inc. 2002), especially Section 4.
enumerate	logical. Insert potential solutions in enumerated list?
digits	integer. How many digits should be used for num exercises?
tolerance	logical. Should tolerance intervals be used for checking if the supplied num answer/number is correct? The default is to use tolerance intervals if digits = NULL.
maxchars	numeric. Lower bound for the number of characters in fill-in-blank fields. The actual number of characters is selected as the maximum number of characters of this value and the actual solution.
fix_num	logical. This is a special flag to enable/force the display of the correct solutions for numeric exercises/answers as well as to obtain results when archiving tests. Note that this is a workaround, which works e.g. within OLAT.
...	further arguments passed on to make_exercise_transform_html.

Details

The Question & Test Interoperability (QTI) is an international XML standard for specifying e-learning tests established by the IMS Global Learning Consortium, Inc. (2002, 2012). The standard evolved over various versions with the first release culminating in the QTI 1.2 standard and the most commonly used stable version of the second release being QTI 2.1. While both versions share many similarities, they also differ in many details. Hence, separate functions exams2qti12 and exams2qti21 are provided. Moreover, due to the flexibility of the QTI standard, different learning management systems employ the standard in slightly different ways. Therefore, dedicated interfaces exams2canvas and exams2ilias (both based on QTI 1.2), and exams2openolat (based on either QTI 2.1 or 1.2) are provided for the learning management systems Canvas, ILIAS, and OLAT/OpenOlat, respectively. In addition, the interfaces exams2blackboard, exams2testvision, and the separate package exams2sakai started as forks of the exams2qti12 and exams2qti21 functions, respectively.

exams2qti12 produces a .zip file that may be uploaded into different learning management systems (see above). This includes the final XML file of the exam/assessment as well as possible supplement folders that include images, data sets etc. used for the exam. It proceeds by (1) calling xweave on each exercise, (2) reading the resulting Markdown and/or LaTeX code, (3) transforming the Markdown/LaTeX code to HTML, and (4) embedding the HTML code in a XML file using the QTI 1.2 standards for assessments and question items.

For steps (1) and (2) the standard drivers in xexams are used. In step (3), a suitable transformation function is set up on the fly using make_exercise_transform_html, see also the details section in exams2html. For step (4), the function will cycle through all questions and exams to generate the final XML file in QTI 1.2 format. Therefore, each question will be included in the XML as one "section". The replicates of each question will be written as question items of the section. The default XML template generates exams/assessments that sample one replicate of a question/item for each section. Typically, the learning management systems sample the items from the different sections independently so that one participant might receive the first random replication from the first exercise but the third random replication from the second exercise, and so on.

Templates other than the default qti12.xml provided in the xml folder of this package could in principle also be specified. However, adapting these is a bit technical. The assessment template must provide one section including one item. exams2qti12 will then use the single item template to generate all items, as well as the assessment and section specifications set within the template. Note that all specifiers that have a leading ## in the XML template will be replaced by suitable code in exams2qti12 and should always be provided in the template. I.e., the user may add additional tags to the XML template or modify certain specifications, like the number of replicates/items that should be sampled for each section etc.

By default, the individual question/item bodies are generated by function make_itembody_qti12, which checks the type of the question and will produce suitable XML code. Note that for each question type, either the arguments of make_itembody_qti12 may be set within num, mchoice, schoice, string and cloze in exams2qti12, by providing a named list of specifications that should be used, or for each questiontype, a function that produces the item body XML code may be provided to num, mchoice, schoice, string and cloze. E.g., mchoice = list(shuffle = TRUE) will force only multiple choice questions to have a shuffled answerlist.

Note that in very old OLAT/OpenOlat versions with QTI 1.2, num exercises are not officially supported but in fact work correctly. The only drawback is that in certain settings the correct solution is not shown at the end of the assessment (although it is used for all internal computations). Therefore, two workarounds are implemented. Either fix_num can be set to TRUE (default), then a fix is added by double-checking the result, or digits can be set to a fixed value (e.g., digits = 2). In the latter case, the num exercise is represented by a string. Then the answer must be provided exactly to the decimal places specified (e.g., if the exact solution is 16.4562, then the correct answer in the test will be "16.46", i.e., a character string of 5 characters).

Value

exams2qti12 returns a list of exams as generated by xexams.

make_itembody_qti12 returns a function that generates the XML code for the itembody tag in QTI 1.2 format.

References

IMS Global Learning Consortium, Inc. (2002). IMS Question & Test Interoperability: ASI XML Binding Specification Final Specification Version 1.2. https://www.imsglobal.org/question/qtiv1p2/imsqti_asi_bindv1p2.html

IMS Global Learning Consortium, Inc. (2012). IMS Question & Test Interoperability (QTI) XSD Binding Version 2.1 Final. https://www.imsglobal.org/question/qtiv2p1/imsqti_bindv2p1.html

Zeileis A, Umlauf N, Leisch F (2014). Flexible Generation of E-Learning Exams in R: Moodle Quizzes, OLAT Assessments, and Beyond. Journal of Statistical Software, 58(1), 1–36. doi:10.18637/jss.v058.i01.

See Also

xexams, ttm, tth, tex2image, make_exercise_transform_html,

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## define an exams (= list of exercises)
myexam <- list(
  "boxplots.Rmd",
  c("tstat.Rmd", "ttest.Rmd", "confint.Rmd"),
  c("regression.Rmd", "anova.Rmd"),
  c("scatterplot.Rmd", "boxhist.Rmd"),
  "relfreq.Rmd"
)

## output directory
dir.create(mydir <- tempfile())

## generate .zip with QTI 1.2 exam in temporary directory
## using a few customization options
exams2qti12(myexam, n = 3, dir = mydir,
  maxattempts = 3,
  num = list(digits = 1),
  mchoice = list(shuffle = TRUE, enumerate = FALSE)
)
dir(mydir)

---

Generation of Exams in QTI 2.1 Format

Description

Automatic generation of exams in QTI 2.1 format.

Usage

exams2qti21(file, n = 1L, nsamp = NULL, dir = ".",
    name = NULL, quiet = TRUE, edir = NULL,
    tdir = NULL, sdir = NULL, verbose = FALSE, rds = FALSE,
    resolution = 100, width = 4, height = 4, svg = FALSE, encoding  = "UTF-8",
    num = NULL, mchoice = NULL,
    schoice = mchoice, string = NULL, cloze = NULL,
    template = "qti21", duration = NULL,
    stitle = NULL, ititle = NULL,
    adescription = "Please solve the following exercises.", sdescription = "",
    maxattempts = 1, cutvalue = NULL, solutionswitch = TRUE,
    casesensitive = TRUE, cloze_schoice_display = "auto",
    navigation = "nonlinear", allowskipping = TRUE, allowreview = FALSE,
    allowcomment = FALSE, shufflesections = FALSE, zip = TRUE, points = NULL,
    eval = list(partial = TRUE, rule = "false2", negative = FALSE),
    converter = NULL, envir = NULL, engine = NULL, base64 = TRUE, mode = "hex",
    include = NULL, selection = c("pool", "exam"), flavor = "plain", ...)

  make_itembody_qti21(shuffle = FALSE, defaultval = NULL,
    minvalue = NULL, maxvalue = NULL, enumerate = FALSE,
    digits = NULL, tolerance = is.null(digits), maxchars = 12,
    eval = list(partial = TRUE, rule = "false2", negative = FALSE),
    solutionswitch = TRUE, casesensitive = TRUE,
    cloze_schoice_display = c("auto", "buttons", "dropdown"),
    copypaste = TRUE)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
nsamp	integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir	character. The default is the current working directory.
name	character. A name prefix for resulting exercises and ZIP file (must not contain spaces or periods, otherwise replaced by underscores).
quiet	logical. Should output be suppressed when calling xweave?
edir	character specifying the path of the directory (along with its sub-directories) in which the files in file are stored (see also xexams).
tdir	character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up (i.e., existing files are deleted) and only certain temporary files are preserved.
sdir	character specifying a directory for storing supplements, by default this is chosen via tempfile.
verbose	logical. Should information on progress of exam generation be reported?
rds	logical indicating whether the return list should also be saved as an RDS data file.
resolution, width, height	numeric. Options for rendering PNG (or SVG) graphics passed to xweave.
svg	logical. Should graphics be rendered in SVG or PNG (default)?
encoding	character, ignored. The encoding is always assumed to be UTF-8.
num	function or named list applied to numerical (i.e., type num) questions. If num is a function, num will be used for generating the item body of the question, see function make_itembody_qti21(). If num is a named list, these arguments will be passed to function make_itembody_qti21().
mchoice, schoice, string, cloze	function or named list applied to multiple choice, single choice, string, and cloze questions (i.e., type mchoice, schoice, string, and cloze), respectively. See argument num for more details.
template	character. The QTI 2.1 template that should be used. Currently, the package provides "qti21.xml".
duration	integer. Set the duration of the exam in minutes.
stitle	character. A title that should be used for the sections. May be a vector of length 1 to use the same title for each section, or a vector containing different section titles.
ititle	character or NULL. A title that should be used for the assessment items. May be a vector of length 1 to use the same title for each item, or a vector containing different item titles. Note that the maximum of different item titles is the number of sections/questions that are used for the exam. Note, if ititle = NULL, simple numbering for the exercises will be used, however, if the exercise contains meta info extitle, this title will be used.
adescription	character. Description (of length 1) for the overall assessment (i.e., exam).
sdescription	character. Vector of descriptions for each section, omitted if empty (or NULL or FALSE).
maxattempts	integer. The maximum attempts for one question. This may also be a vector so that the maximum number of attempts varies across questions. A value of Inf or 0 signals that the attempts per question are not limited.
cutvalue	numeric. The number of points at which the exam is passed. If set to NULL (default) or equivalently NA, no cutvalue is set and the result of the exam is just the number of points.
solutionswitch	logical or character. Should the question/item solutionswitch be enabled? In OLAT this means that the correct solution is shown after an incorrect solution was entered by an examinee (i.e., this is typically only useful if maxattempts = 1). Furthermore, if e.g. solutionswitch = c("correct", "incorrect", "summary"), the correct solution can be either displayed when the answer is "correct" and/or "incorrect" and/or after the test is completed in the "summary" of the results.
casesensitive	logical. Should the evaluation of string exercises be case sensitive?
cloze_schoice_display	character. For schoice answers in cloze exercises, select the display of the possible answers. By default (cloze_schoice_display = "auto"), radio "buttons" are used if the answer list appears in its own paragraph and a "dropdown" menu is used if the answer list appears inline (and has no mathematical markup). Both options can also be enforced explicitly, independently from the answer list appearing in a separate paragraph or inline. Note that in dropdown menus the answer list will typically be rendered as plain text which means that mathematical notaion may become unintelligible.
copypaste	logical. For string/text responses, controls whether text may be copied into the text entry field, or must actually be entered.
navigation	character. Mode of navigation, can either be "nonlinear" (default) or "linear". The former means that test participants can switch back and forth between questions while the latter implies that the questions need to be answered sequentially.
allowskipping	logical. Can a question/section be skipped (default) or must it be answered?
allowreview	logical. Can questions be viewed again at the end of a test/exam or not (default)?
allowcomment	logical. Are comments allowed?
shufflesections	logical. Should the order of the exercises be shuffled? For selection = "pool" setting shufflesections = TRUE this corresponds to shuffling the sections that contain the pools of exercises. For selection = "exam" it corresponds to shuffling the exercises within each exam section.
zip	logical. Should the resulting XML file (plus supplements) be zipped?
points	integer. How many points should be assigned to each exercise? Note that this argument overules any exercise points that are provided within an "\expoints{}" tag in the .Rnw file. The vector of points supplied is expanded to the number of exercises in the exam.
eval	named list, specifies the settings for the evaluation policy, see function exams_eval.
converter	character. Argument passed on to make_exercise_transform_html. The default for converter is set to "ttm" unless there are Rmd exercises in file where "pandoc" is used.
envir	argument passed to xweave (which passes it to knit).
engine	argument passed to xweave indicating whether "Sweave" (default) or "knitr" should be used for rendering Rnw exercises.
base64	logical. Should supplementary files be embedded using Base 64 coding? Argument base64 may also be a character vector of file suffixes that should be encoded, e.g. base64 = c("png", "rda") will only encode PNG images and binary .rda files. If set to NULL only image files will be encoded.
mode	character. See function tth.
include	character, paths of extra files that should be included within the final .zip-file.
selection	character. If selection = "pool", the function creates one section for each exercise from which one replication will be selected in the exam. If selection = "exam" each section contains all questions and one section will be selected for the exam. The "exam" variant has the advantage that questions that build on each other can be used in the exam.
flavor	character. Which QTI 2.1 “flavor” should be used? Some learning management systems require that the QTI XML tags are used in a rather specific and idiosyncratic way. Typically, users should not set this argument directly but use the convenience interfaces such as exams2openolat instead (which use the flavor argument internally along with further customizations).
shuffle, defaultval, minvalue, maxvalue	arguments used for item construction, for details see the XML specification (see IMS Global Learning Consortium, Inc. 2012), especially Section 4.
enumerate	logical. Insert potential solutions in enumerated list?
digits	integer. How many digits should be used for num exercises?
tolerance	logical. Should tolerance intervals be used for checking if the supplied num answer/number is correct? The default is to use tolerance intervals if digits = NULL.
maxchars	numeric. Lower bound for the number of characters in fill-in-blank fields. The actual number of characters is selected as the maximum number of characters of this value and the actual solution.
...	further arguments passed on to make_exercise_transform_html.

Details

The Question & Test Interoperability (QTI) is an international XML standard for specifying e-learning tests established by the IMS Global Learning Consortium, Inc. (2002, 2012). The standard evolved over various versions with the first release culminating in the QTI 1.2 standard and the most commonly used stable version of the second release being QTI 2.1. While both versions share many similarities, they also differ in many details. Hence, separate functions exams2qti12 and exams2qti21 are provided. Moreover, due to the flexibility of the QTI standard, different learning management systems employ the standard in slightly different ways. Therefore, dedicated interfaces exams2canvas and exams2ilias (both based on QTI 1.2), and exams2openolat (based on either QTI 2.1 or 1.2) are provided for the learning management systems Canvas, ILIAS, and OLAT/OpenOlat, respectively. In addition, the interfaces exams2blackboard, exams2testvision, and the separate package exams2sakai started as forks of the exams2qti12 and exams2qti21 functions, respectively.

exams2qti21 produces a .zip file that may be uploaded into different learning management systems (see above). This includes the final XML file of the exam/assessment, its exercises as well as possible supplement folders that include images, data sets etc. It proceeds by (1) calling xweave for each exercise, (2) reading the resulting Markdown and/or LaTeX code using read_exercise, (3) transforming the Markdown/LaTeX code to HTML, and (4) embedding the HTML code in XML files using the QTI 2.1 standard for assessments and question items.

For steps (1) and (2) the standard drivers in xexams are used. In step (3), a suitable transformation function is set up on the fly using make_exercise_transform_html, see also the details section in exams2html. For step (4), the function will cycle through all questions and exams to generate the final XML files in QTI 2.1 format: separate XML files for each random replication of each exercise (labeled items in sections in QTI), one XML file tying the overall exam/assessment together based on the individual exercises and one overall ‘imsmanifest.xml’.

For arranging the individual exercise replications (called "items") in so-called "sections" two different types of selection are available: First, a "pool" of replications/items can be put into a section and then one item will be selected randomly for each participant from each section. As learning management systems typically sample the sections independently, this means that one participant might receive the first random replication from the first exercise but the third random replication from the second exercise, and so on. Alternatively, selection = "exam" specifies that each section contains a complete set of exercises and one section will be selected randomly for each participant. The "exam" variant is less commonly used but has the advantage that questions that build on each other can be used in the exam. Also, duplicated exercise types can be avoided when using nsamp to sample a certain number of exercises without replacement.

Templates other than the default qti21.xml provided in the xml folder of this package could in principle also be specified. However, adapting these is a bit technical. The assessment template must provide one section including one item. exams2qti21 will then use the single item template to generate all items, as well as the assessment and section specifications set within the template. Note that all specifiers that have a leading ## in the XML template will be replaced by suitable code in exams2qti21 and should always be provided in the template. Thus, the user may add additional tags to the XML template or modify certain specifications, like the number of replicates/items that should be sampled for each section etc.

By default, the individual question/item bodies are generated by function make_itembody_qti21 which checks the type of the question and will produce suitable XML code. Note that for each question type, either the arguments of make_itembody_qti21 may be set within num, mchoice, schoice, string and cloze in exams2qti21, by providing a named list of specifications that should be used, or for each question type, a function that produces the item body XML code may be provided to num, mchoice, schoice, string and cloze. E.g., mchoice = list(shuffle = TRUE) will force only multiple choice questions to have a shuffled answerlist.

Value

exams2qti21 returns a list of exams as generated by xexams.

make_itembody_qti21 returns a function that generates the XML code for the itembody tag in QTI 2.1 format.

References

IMS Global Learning Consortium, Inc. (2002). IMS Question & Test Interoperability: ASI XML Binding Specification Final Specification Version 1.2. https://www.imsglobal.org/question/qtiv1p2/imsqti_asi_bindv1p2.html

IMS Global Learning Consortium, Inc. (2012). IMS Question & Test Interoperability (QTI) XSD Binding Version 2.1 Final. https://www.imsglobal.org/question/qtiv2p1/imsqti_bindv2p1.html

Zeileis A, Umlauf N, Leisch F (2014). Flexible Generation of E-Learning Exams in R: Moodle Quizzes, OLAT Assessments, and Beyond. Journal of Statistical Software, 58(1), 1–36. doi:10.18637/jss.v058.i01.

See Also

xexams, ttm, tth, tex2image, make_exercise_transform_html,

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## define an exams (= list of exercises)
myexam <- list(
  "boxplots.Rmd",
  c("tstat.Rmd", "ttest.Rmd", "confint.Rmd"),
  c("regression.Rmd", "anova.Rmd"),
  c("scatterplot.Rmd", "boxhist.Rmd"),
  "relfreq.Rmd"
)

## output directory
dir.create(mydir <- tempfile())

## generate .zip with QTI 2.1 exam in temporary directory
## using a few customization options
exams2qti21(myexam, n = 3, dir = mydir,
  maxattempts = 3,
  num = list(digits = 1),
  mchoice = list(shuffle = TRUE, enumerate = TRUE)
)
dir(mydir)

---

Generation of Exams in TCExam Format

Description

Interface for generating exams in TCExam format.

Usage

exams2tcexam(file, n = 1L, nsamp = NULL, dir = ".",
    name = NULL, quiet = TRUE, edir = NULL, tdir = NULL, sdir = NULL, verbose = FALSE,
    resolution = 100, width = 4, height = 4, svg = FALSE, encoding = "UTF-8",
    points = NULL, modulename = name, subjectname = name, subjectdescription = NULL,
    timer = 0, fullscreen = FALSE, inlineanswers = FALSE, autonext = FALSE,
    shuffle = FALSE, lang = "en", date = Sys.time(), zip = FALSE, converter = NULL,
    ...)

Arguments

file	character. A specification of a (list of) exercise files.
n	integer. The number of copies to be compiled from file.
nsamp, quiet, edir, tdir, sdir, verbose	arguments passed to xexams.
dir	character specifying the output directory path. The default is the current working directory.
name	character. A name prefix for resulting XML file.
resolution, width, height, svg	arguments passed to xweave.
encoding	character, ignored. The encoding is always assumed to be UTF-8.
points	numeric. Number of points for the questions.
modulename	character. Module name.
subjectname	character. Subject name.
subjectdescription	character. Subject description.
timer	numeric. Number of seconds for each question.
fullscreen	logical. Should the question be shown in full-screen mode?
inlineanswers	logical. Should the question list be presented inline?
autonext	logical. Automatically advance to the next item?
shuffle	logical. Should the question list of schoice/mchoice answers be shuffled (or kept fixed)?
lang	character. Two-letter indicator of the language.
date	character or "Date" object specifying the date of the exam.
zip	logical. Should the resulting XML file be zipped?
converter, ...	arguments passed on to make_exercise_transform_html. The default for converter is set to "ttm" unless there are Rmd exercises in file where "pandoc" is used.

Details

exams2tcexam generates XML exams that can be imported into the TCExam software of Asuni (2012). Currently, the subset of HTML(-like) commands that is supported in TCExam is rather limited, e.g., tables and figures cannot be directly included.

Value

A list of exams as generated by xexams is returned invisibly.

References

Asuni (2012). TCExam: Computer-Based Assessment Software. https://tcexam.org/.

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## Not run: 
## exams2tcexam creates a single XML file
exams2tcexam("tstat2", n = 2)

## End(Not run)

---