| exams {exams} | R Documentation |
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)
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
|
nsamp |
integer. The number(s) of exercise files sampled from each
list element of |
dir |
character. The output directory, this has to be set if
|
template |
character. A specification of a LaTeX template. The package
currently provides |
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 |
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 |
quiet |
logical. Should output be suppressed when calling
|
edir |
character specifying the path of the directory in which
the files in |
tdir |
character specifying a temporary directory, by default
this is chosen via |
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.
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. |
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.
See Also
exams2pdf,
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.Rnw",
c("tstat.Rnw", "ttest.Rnw", "confint.Rnw"),
c("regression.Rnw", "anova.Rnw"),
"scatterplot.Rnw",
"relfreq.Rnw"
)
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.Rnw", template = "solution",
control = mymchoice.control)
sol
}