exams2moodle: Generation of Exams in Moodle XML Format

View source: R/exams2moodle.R

exams2moodleR Documentation

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,
    table = NULL, 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 = TRUE, 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

passed to xweave.

table

character. An optional class assigned to <table> elements (without a class) in the question (only supported for pandoc-based converter).

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 question (e.g., for formatting <table> elements).

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 .Rnw 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., 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.

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.

rule

character specifying which rule to use for negative partial credits. see function exams_eval. Note that the default using cloze exercises is rule = "none".

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 LaTeX code, (3) transforming the LaTeX code to HTML, and (4) embedding the HTML code in a XML file using the Moodle standards 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 XML file in Moodle standard. 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 .Rnw 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 is then generated using function make_question_moodle. Note that for each question type, either the arguments of make_question_moodle may be set within num, mchoice, schoice, string and cloze in exams2moodle, by providing a named list of specifications that should be used, or for each questiontype, a function that produces the question XML code may be provided to num, mchoice, schoice, string and cloze. E.g., to suppress the solution for numeric questions one may set num = list(solution = FALSE).

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.Rnw" and "fourfold2.Rnw" 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 .Rnw exercise. 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 free text questions in moodle one may specify extra parameters via \exextra. Currently the following options are supported:

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

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. (2019). Moodle, Version 3.6. https://moodle.org/.

MoodleDocs (2019). 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)

exams documentation built on Nov. 14, 2022, 3:02 p.m.