exams2nops {exams}R Documentation

Generation of Written Exams for Automatic Evaluation

Description

Generation of exams in PDF format that can be printed, scanned, and evaluated automatically.

Usage

  exams2nops(file, n = 1L, nsamp = NULL, dir = ".", name = NULL,
    language = "en", title = "Exam", course = "",
    institution = "R University", logo = "Rlogo.png", date = Sys.Date(), 
    replacement = FALSE, intro = NULL, blank = NULL, duplex = TRUE, pages = NULL,
    usepackage = NULL, header = NULL, encoding = "UTF-8", startid = 1L,
    points = NULL, showpoints = FALSE, samepage = FALSE,
    twocolumn = FALSE, reglength = 7L, seed = NULL, ...)

  make_nops_template(n, replacement = FALSE, intro = NULL, blank = NULL,
    duplex = TRUE, pages = NULL, file = NULL, nchoice = 5, encoding = "UTF-8",
    samepage = FALSE, twocolumn = FALSE, reglength = 7L)

Arguments

file

character. A specification of a (list of) exercise files.

n

integer. The number of copies to be compiled from file (in exams2nops) and the number of exercises per exam (in make_nops_template), respectively.

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 default is either display on the screen (if n = 1L) or the current working directory.

name

character. A name prefix for resulting exams and RDS file.

language

character. Path to a DCF file with a language specification. See below for the list of supported languages.

title

character. Title of the exam, e.g., "Introduction to Statistics".

course

character. Optional course number, e.g., "101".

institution

character. Name of the institution at which the exam is conducted.

character. Path to a logo image. If the logo is not found, it is simply omitted.

date

character or "Date" object specifying the date of the exam.

replacement

logical. Should a replacement exam sheet be included?

intro

character. Either a single string with the path to a .tex file or a vector with with LaTeX code for optional introduction text on the first page of the exam.

blank

integer. Number of blank pages to be added at the end. (Default is chosen to be half of the number of exercises.) If pages is specified, blank can also be a vector of length two with blank pages before and after the extra pages, respectively.

duplex

logical. Should blank pages be added after the title page (for duplex printing)?

pages

character. Path(s) to additional PDF pages to be included at the end of the exam (e.g., formulary or distribution tables).

usepackage

character. Names of additional LaTeX packages to be included.

header

character vector or list. Either a character vector with LaTeX code to include in the header or a named list with further options to be passed to the LaTeX files.

encoding

character, ignored. The encoding is always assumed to be UTF-8.

startid

integer. Starting ID for the exam numbers (defaults to 1).

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.

showpoints

logical. Should the PDF show the number of points associated with each exercise (if specified in the Rnw/Rmd exercise or in points)?

samepage

logical. Should the itemized question lists be forced to be on the same page?

twocolumn

logical. Should a two-column layout be used?

reglength

integer. Number of digits in the registration ID. The default is 7 and it can be increased up to 10. In case of reglength < 7, internally reglength = 7 is enforced (and thus necessary in the registration CSV file) but the initial ID digits are fixed to 0 in the exam sheet and corresponding boxes ticked already.

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.

...

arguments passed on to exams2pdf.

nchoice

character. The number of choice alternatives per exercise.

Details

exams2nops is a convenience interface for exams2pdf with a dynamically generated title page which can be printed, scanned with nops_scan and evaluated automatically by nops_eval. It is originally intended for single- and multiple choice (schoice/mchoice) questions only but has also some limited support for open-ended (string) questions.

The exam sheet consists of various sections where information is either printed our filled in by the students. The section with personal data is just for human readers, it is not read automatically. The registration number has to be filled in in digits and also marked with corresponding crosses where only the latter is read automatically. The exam ID/type/scrambling are printed directly into the PDF and read automatically after scanning. Note that the font in the PDF must not be modified for the reading step to work reliably. (A sans-serif font is used and hence the sfmath LaTeX package is also used - if it is installed.) The questions can have up to five alternatives which have to answered by the students. The crosses are read automatically where both empty and completely filled boxes are regarded as not crossed.

Tutorial for NOPS workflow: https://www.R-exams.org/tutorials/exams2nops/.

Limitations: (a) Only up to five answer alternatives per question are supported. (b) Currently, only up to 45 questions are supported. If you have more questions, consider splitting the entire exam up into two NOPS exams. (c) Only up to 3 open-ended questions can be included. (d) Each question must have the same number of answer alternatives and the same number of points across random replications. For example, the n replications drawn for the first exercise all need, say, five alternatives and two points. Then, the second exercise may have, say, four alternatives and five points and so on. But this may not be mixed within the same exercise number.

The examples below show how PDF exams can be generated along with an RDS file with (serialized) R data containing all meta-information about the exam. The PDFs can be printed out for conducting the exam and the exam sheet from the first page then needs to be scanned into PDF or PNG images. Then the information from these scanned images can be read by nops_scan, extracting information about the exam, the participants, and the corresponding answers (as described above). The ZIP file produced by nops_scan along with the RDS of the exam meta-information and a CSV file with participant information can then be used by nops_eval to automatically evaluate the whole exam and producing HTML reports for each participant. See nops_eval for a worked example.

Currently, up to three open-ended string questions can also be included. These do not generate boxes on the first exam sheet but instead a second exam sheet is produced for these open-ended questions. It is assumed that a human reader reads these open-ended questions and then assigns points by marking boxes on this separate sheet. Subsequently, this sheet can also be read by nops_scan.

The language elements can be specified through a relatively simple text file and the package already ships with: English ("en"), Croatian ("hr"), Danish ("da"), Dutch ("nl"), Finnish ("fi"), French ("fr"), Galician ("gl"), German ("de"), Hungarian ("hu"), Italian ("it"), Japanese ("ja"), Korean ("ko"), Norwegian (Bokmål, "no"), Portuguese ("pt-PT" or "pt-BR"; also "pt" is synonymous with "pt-PT"), Romanian ("ro"), Russian ("ru"), Serbian ("sr"), Slovak ("sk"), Slovenian ("sl"), Spanish ("es"), Swiss German ("gsw"), Turkish ("tr"), Vietnamese ("vi"). Note that the language names correspond to the ISO 639 codes (https://www.loc.gov/standards/iso639-2/php/code_list.php) or IETF language tags (https://en.wikipedia.org/wiki/IETF_language_tag) if no ISO 639 codes exists (as for Brazilian Portuguese). For more details about the underlying text file in DCF format, see https://www.R-exams.org/tutorials/nops_language/

Value

A list of exams as generated by xexams is returned invisibly.

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")

## define an exam (= list of exercises)
myexam <- list(
  "tstat2.Rmd",
  "ttest.Rmd",
  "relfreq.Rmd",
  "anova.Rmd",
  c("boxplots.Rmd", "scatterplot.Rmd"),
  "cholesky.Rmd"
)

if(interactive()) {
## compile a single random exam (displayed on screen)
exams2nops(myexam, duplex = FALSE, language = "de")
}

## create multiple exams on the disk (in a
## temporary directory)
dir.create(mydir <- tempfile())

## generate NOPS exam in temporary directory
set.seed(403)
ex1 <- exams2nops(myexam, n = 2, dir = mydir)
dir(mydir)


## use a few customization options: different
## university/logo and language/title
## with a replacement sheet but for non-duplex printing
set.seed(403)
ex2 <- exams2nops(myexam, n = 2, dir = mydir,
  institution = "Universit\\\"at Innsbruck",
  name = "uibk", logo = "uibk-logo-bw.png",
  title = "Klausur", language = "de",
  replacement = TRUE, duplex = FALSE)
dir(mydir)


options(exams_tex = oopt$exams_tex)

[Package exams version 2.4-0 Index]