exams (version 1.9-0)

exams: Generation of Simple Exams

Description

Sweave-based automatic generation of exams including multiple choice questions and arithmetic problems.

Usage

exams(file, n = 1, nsamp = NULL, dir = NULL, template = "plain",
    inputs = NULL, header = list(Date = Sys.Date()), name = NULL,
    quiet = TRUE, edir = NULL, tdir = NULL, control = NULL)

Arguments

file

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

n

integer. The number of copies to be compiled from file.

nsamp

integer. The number 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

dir

character. The output directory, this has to be set if n is greater than 1 (or template is longer than 1).

template

character. A specification of a LaTeX template. The package currently provides "exam", "solution", "plain". For 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, by default chosen based on template.

quiet

logical. Should output be suppressed when calling Sweave and texi2dvi.

edir

character specifying the path of the directory in which the files in file are stored (see also below).

tdir

character specifying a temporary directory, by default this is chosen via tempdir.

control

A list of control arguments for the appearance of multiple choice results (see Details).

Value

• An object of class "exams_metainfo" is returned invisibly. It is a list of length n, containing a list of meta informations for each exercise:
• mchoice
  logical. Is the exercise a multiple choice exercise?
• length
  integer. Length of solution.
• solution
  either a logical vector (for multiple choice) or numeric vector (for arithmetic problems).
• string
  character. A human-readable version of the solution.

Details

exams generates exams from lists of Sweave source files by: (1) running Sweave on each exercise, (2) including the resulting LaTeX files in a template, (3) running texi2dvi on the template, and (4) storing the resulting PDF file in an output dir (or displaying it interactively). Each exercise in an exam is essentially a standalone Sweave source file that exams knows (almost) nothing about, it just calls Sweave (n times). The only exception is some meta-information which is passed by means of four commands back to exams. The commands are \extype (which may be mchoice or num), \exsolution (e.g., 3.124 for a numeric solution and 10010 for a multiple choice solution), \exstring (containing a human-readable string with the solution), and \extol (a tolerance for numeric solutions). The specification in file should be either of form "foo" or equivalently "foo.Rnw", where the file "foo.Rnw" should either be in the local directory, the edir directory or in the exercises directory of the package. 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.

The template is a (vector of) specification(s) of LaTeX templates. It can be "foo" or equivalently "foo.tex" where "foo.tex" should either be in the local directory (or provided with the full path) or in the tex directory of the package. It should specify where in the template the exercises are included, using the markup \exinput{exercises}. Additionally, it may contain \exinput{questionnaire} and \exinput{header}. template can also be a vector, then for each of the n runs several output files (one for each template) are created. The name prefix for each file is by default the base name of the corresponding template but can also be changed via name. exams creates the PDF files and stores them in an output directory together with the solution meta information as metainfo.rda (see also below). If only a single PDF is created (currently the default), dir may be NULL and it is only displayed on the screen.

The argument control is specified by a named list with elements mchoice.print and mchoice.symbol. The element mchoice.print is used for specifying the characters used for printing. It is again a named list where element True gives the (five) characters used for printing when the answer is correct and False if the answer is wrong. The symbol used for the questionnaire output in the final PDF file is defined by mchoice.symbol which is vector with elements True and False.

References

Gruen B, Zeileis A (2009). Automatic Generation of Exams in R. Journal of Statistical Software, 29(10), 1--14. http://www.jstatsoft.org/v29/i10/.

See Also

Sweave, texi2dvi, mchoice2string

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

## define an exams (= list of exercises)
myexam <- list(
  "boxplots",
  c("tstat", "ttest", "confint"),
  c("regression", "anova"),
  "scatterplot",
  "relfreq"
)

if(interactive()) {
## compile a single random exam (displayed on screen)
sol <- exams(myexam)
sol
}

## generate multiple exams (stored in output directory)
odir <- tempfile()
sol <- exams(myexam, n = 5, dir = odir, template = c("exam", "solution"))
sol

## inspect solution for a particular exam
print(sol, 3)

if(interactive()) {
## modify control argument for printing
mymchoice.control <- list(mchoice.print = list(True = LETTERS[1:5], False = "_"))
sol <- exams("boxplots", template = "solution",
  control = mymchoice.control)
sol
}