Automatic generation of exams in QTI 2.1 format.
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)
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.
character. A specification of a (list of) exercise files.
integer. The number of copies to be compiled from file
.
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.)
character. The default is the current working directory.
character. A name prefix for resulting exercises and ZIP file (must not contain spaces or periods, otherwise replaced by underscores).
logical. Should output be suppressed when calling
xweave
?
character specifying the path of the directory (along with its
sub-directories) in which the files in file
are stored
(see also xexams
).
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.
character specifying a directory for storing supplements, by
default this is chosen via tempfile
.
logical. Should information on progress of exam generation be reported?
logical indicating whether the return list should also be saved as an RDS data file.
numeric. Options for rendering PNG (or SVG)
graphics passed to xweave
.
logical. Should graphics be rendered in SVG or PNG (default)?
character, ignored. The encoding is always assumed to be UTF-8.
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()
.
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.
character. The QTI 2.1 template that should be used. Currently,
the package provides "qti21.xml"
.
integer. Set the duration of the exam in minutes.
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.
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.
character. Description (of length 1) for the overall assessment (i.e., exam).
character. Vector of descriptions for each section, omitted if empty
(or NULL
or FALSE
).
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.
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.
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.
logical. Should the evaluation of string exercises be case sensitive?
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.
logical. For string/text responses, controls whether text may be copied into the text entry field, or must actually be entered.
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.
logical. Can a question/section be skipped (default) or must it be answered?
logical. Can questions be viewed again at the end of a test/exam or not (default)?
logical. Are comments allowed?
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.
logical. Should the resulting XML file (plus supplements) be zipped?
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.
named list, specifies the settings for the evaluation policy, see function
exams_eval
.
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.
argument passed to xweave
(which passes
it to knit
).
argument passed to xweave
indicating whether
"Sweave"
(default) or "knitr"
should be used for rendering Rnw exercises.
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.
character. See function tth
.
character, paths of extra files that should be included within the final
.zip
-file.
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.
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).
arguments used for item construction, for details see the XML specification (see IMS Global Learning Consortium, Inc. 2012), especially Section 4.
logical. Insert potential solutions in enumerated list?
integer. How many digits should be used for num
exercises?
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
.
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
.
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.
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. tools:::Rd_expr_doi("10.18637/jss.v058.i01").
xexams
,
ttm
,
tth
,
tex2image
,
make_exercise_transform_html
,
## 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)
Run the code above in your browser using DataLab