read_exercise {exams}

Reading LaTeX/Markdown Exercise Files

Description

Reading an exercise in either LaTeX format (i.e., after Sweave was run) or Markdown format (i.e., after knit was run).

Usage

  read_exercise(file, markup = NULL, exshuffle = NULL)
  read_metainfo(file, markup = NULL, exshuffle = NULL)

Arguments

file

character. Name of the LaTeX (.tex) or Markdown (.md) file that should be read into R.

markup

character specifying whether file is a "latex" or "markdown" exercise. By default (NULL) it is inferred from the file extension.

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

Details

read_exercise extracts the LaTeX/Markdown code from the question and solution environments/sections of the exercise file, extracting the corresponding answerlists separately (if any). Paths to supplementary files (such as graphics or data files) are stored and the metainformation is extracted (by calling read_metainfo which also includes sanity checks).

The supported metainformation commands are described in detail in vignette("exams2", package = "exams"), see Table 2. Essentially the extype command in is mapped to the type element of the returned list etc. (see the Value section below), using the right storage mode for each command (numeric, character, logical). Additionally, there is an exextra command which allows to set up arbitrary additional metainformation elements.

Value

read_exercise returns a list with elements

question

a character vector with LaTeX/Markdown code from the question environment (excluding the answerlist environment, if any).

questionlist

a character vector with LaTeX/Markdown code from the answerlist environment within the question environment (if any).

solution

a character vector with LaTeX/Markdown code from the solution environment (excluding the answerlist environment, if any).

solutionlist

a character vector with LaTeX/Markdown code from the answerlist environment within the solution environment (if any).

metainfo

a list of metainformation options, see below.

supplements

a character vector with paths to supplementary files such as graphics or data files (if any).

read_metainfo returns a list with the following elements. Most elements may also be NULL (or empty) if the underlying information is not specified in the file. If file specifies extra information, there may also be additional list elements.

file

character with file name (without extension) of the exercise template.

markup

character indicating whether "latex" or "markdown" markup is used in the exercise.

type

character indicating exercise type: num, mchoice, schoice, string, or cloze.

name

character with short name/description (to be used for printing within R).

title

character with a pretty longer title.

section

character with sections for groups of exercises (using slashes for subsections like a URL).

version

character with version of exercise.

solution

correct solution. The type/value depends on the type of the exercise: num leads to a numeric vector (of length 1 or 2), mchoice/schoice lead to logical vector, string to a character vector (of length 1), and cloze leads to a list of solutions (depending on clozetype).

tolerance

numeric tolerance limits (of length 1 or 2) for numeric solutions.

clozetype

character indicating the types of the elements of a cloze exercise.

points

numeric with (default) points for correct solution.

time

numeric with (default) time (in seconds) for solution.

shuffle

logical indicating whether mchoice/schoice answers should be shuffled (in Moodle or other e-learning systems).

single

logical indicating whether radio buttons should be used in Moodle.

length

numeric with length of solution.

string

character with a collapsed string of the solution (and tolerance) for backward compatibility with exams.

maxchars

character with the maximum number of characters allowed in QTI text answers (exercise type: string).

abstention

character with the label to be used for an abstention button in schoice/mchoice answers (currently only supported by Moodle).

See Also

xexams

Examples

## xexams() uses read_exercise() by default to read in
## each individual exercise, e.g., here for only a single
## exam with only a single exercise the result is:
set.seed(1090)
xexams("tstat.Rnw")[[1]][[1]]

## the corresponding Markdown version has:
set.seed(1090)
xexams("tstat.Rmd")[[1]][[1]]