xexams {exams}

Extensible Generation of Exams

Description

Extensible automatic generation of exams including multiple choice questions and arithmetic problems.

Usage

  xexams(file, n = 1L, nsamp = NULL,
    driver = list(sweave = NULL, read = NULL, transform = NULL, write = NULL),
    dir = ".", edir = NULL, tdir = NULL, sdir = NULL, verbose = FALSE,
    points = NULL, seed = NULL, rds = FALSE, ...)

  exams_metainfo(x, class = "exams_metainfo", tags = TRUE, factors = FALSE,
    ...)

Arguments

file

character. A specification of a (list of) exercise files, for details see below.

n

integer. The number of copies to be taken 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.)

driver

list with elements sweave (weaver function or list of arguments for the default xweave), read (function for reading exercise files, defaulting to read_exercise), transform (function to transform each exercise, by default no transformations are done), write (function to write exams to output files, by default nothing is written). For more details, see below.

dir

character. The output directory passed on to driver$write.

edir

character specifying the path of the directory (along with its sub-directories) 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 (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.

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.

rds

logical or character indicating whether the list returned by xexams should also be saved as an RDS data file. If rds = TRUE the file name "metainfo.rds" is used. Alternatively, rds can also be a character file name to be used.

x

a list as returned by xexams (or one of the exams2xyz interfaces).

class

character. Should the meta-information be returned as a list of lists with class "exams_metainfo" or as a "data.frame"?

tags

logical. Should the extags entries be processed into separate columns if class = "data.frame"?

factors

logical. Should the character columns for class = "data.frame" be turned into factors?

...

currently not used.

Details

xexams is meant to provide an extensible framework for generating exams based on exercises in R/LaTeX format (via Sweave) or R/Markdown format (via knit) and rendering them into various output formats such as PDF, HTML, or XML (e.g., for Moodle or IMS QTI). xexams is typically not called by the user directly but is used as a common infrastructure for functions such as exams2pdf, exams2html, exams2moodle, exams2qti12, or exams2lops.

xexams generates exams from lists (or vectors) of Rnw/Rmd source files by: (1) running driver$sweave on each exercise (by default xweave is used, calling Sweave or knit), (2) running driver$read on the resulting LaTeX/Markdown file which by default uses read_exercise to read question/solution texts plus metainformation and stores the result in a list, (3) running driver$transform on this list for possible transformations (e.g., from LaTeX to HTML), (4) running driver$write on the list of exercises within each exam.

Each exercise in an exam is essentially a standalone source file that xexams knows (almost) nothing about, it just calls driver$sweave in each iteration and assumes that driver$read can read the resulting LaTeX or Markdown file into a list.

The specification in file should be either of form "foo.Rnw" (or equivalently just "foo") or "foo.Rmd", where the file should either be in the local directory, the edir directory or in the exercises directory of the package. If edir is specified, the directory along with all its sub-directories is searched for the exercises in file. Also, 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.

Value

A list of exams (of length n), each of which is a list of exercises (whose length depends on the length of file and nsamp), each of which is a list (whose length/contents depends on driver$read).

When using the default reader, the resulting list can be simplified using exams_metainfo, returning the same (classed) structure as the older exams interface. It is recommended to use this to inspect whether the ‘extype’ and ‘exsolution’ (and corresponding tolerance, if any) are correctly specified.

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

xweave, exams2pdf, exams2html, exams2moodle, exams2canvas, exams2openolat, exams2nops

Examples

## define an exam with five exercises
myexam <- list(
  "boxplots.Rmd",
  c("tstat.Rmd", "ttest.Rmd", "confint.Rmd"),
  c("regression.Rmd", "anova.Rmd"),
  "scatterplot.Rmd",
  "relfreq.Rmd"
)

## run exams with default drivers (i.e., no transformations or writer)
x <- xexams(myexam, n = 2)
## x is a list of 2 exams,
## each of which contains 5 exercises,
## each of which contains LaTeX code for question(list) and solution(list),
## plus metainformation and potential supplements

## The first exercise in each exam is "boxplots.Rmd", a multiple choice question.
## Its general question text is
x[[1]][[1]]$question
## with a list of multiple choice questions given as
x[[1]][[1]]$questionlist
## the corresponding graphic is in supplementary file
x[[1]][[1]]$supplements

## The metainformation is a list read from the ex* items
x[[1]][[1]]$metainfo

## The metainformation can also be extracted/printed
exams_metainfo(x)
## customize printing: only exam 1 in blocks of up to 3 exercises
print(exams_metainfo(x), which = 1, block = 3)

## The metainformation can also be prepared as a data.frame
exams_metainfo(x, class = "data.frame")