exams (version 2.3-6)

exams: Generation of Simple Exams

Description

Old (version 1) interface for Sweave-based automatic generation of exams including multiple choice questions and arithmetic problems. Now it is recommended to use the (version 2) interface exams2pdf.

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)

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.

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(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 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 tempfile. Note that this is cleaned up and potentially temporary files are deleted.

control

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

Details

exams is the old (version 1) interface for Sweave-based generation of PDF exams. It is only provided for backward compatibility and is superseded by the far more flexible function exams2pdf.

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

exams2pdf, Sweave, texi2dvi, mchoice2string

Examples

Run this code
## 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 = 2, 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
}

Run the code above in your browser using DataCamp Workspace