Automatic generation of exams in Moodle XML format.
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)
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.
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.
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.
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.
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.
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.
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/.
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").
logical. Should an unique test id be added to the exam name.
logical. Should the resulting XML file be zipped?
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.
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.
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.
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).
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.
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.
logical. Should the question solution, if available, be added in the question XML?
For mchoice and schoice exercises, if set to TRUE will
force Moodle to additionally shuffle the provided answer list.
numeric. Specifies the penalty tag for a question.
character. Specifies how choice questions should be numbered,
allowed values are: "abc" (default), "ABCD", "123" or "none".
logical. Should string questions be case sensitive or not.
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.
character of length 2. For single choice answers in cloze questions,
the user may specify the possible options shown.
logical. In cloze questions, if set to TRUE, the answerlist and
solutionlist will be enumerated.
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.
named list, specifies the settings for the evaluation policy, see function
exams_eval.
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.
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.
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).
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.
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. tools:::Rd_expr_doi("10.18637/jss.v058.i01").
Zeileis A (2019). Mathematical Notation in Online R/exams. https://www.R-exams.org/tutorials/math/
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 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)
Run the code above in your browser using DataLab