exams2pdf {exams}

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)