num_to_schoice: Generate Single-Choice Question List from Numeric Solution

Description

A function for generating a single-choice question list for one correct numeric solution along with four wrong solutions.

Usage

num_to_schoice(correct, wrong = NULL, range = c(0.5, 1.5) * correct,
  delta = 1, digits = 2, method = c("runif", "delta"), sign = FALSE,
  format = TRUE, order = getOption("num_to_schoice_order", FALSE),
  maxit = getOption("num_to_schoice_maxit", Inf),
  verbose = getOption("num_to_schoice_verbose", TRUE))

Value

num_to_schoice/num2schoice returns either NULL (if no suitable question list can be found) or a list with the following components:

solutions: a logical vector of length 5 indicating the correct solution,
questions: a vector of length 5 with the question list, by default formatted as character but optionally also numeric (if format = FALSE or "numeric").

Arguments

correct: numeric vector of length 1 with correct solution.
wrong: numeric vector (optional) with wrong solutions.
range: numeric vector of length 2 with range of random wrong solutions.
delta: numeric. Minimal distance between solutions.
digits: integer. Digits that should be displayed.
method: character specifying method for generating random results.
sign: logical. Should the sign be changed randomly?
format: logical or character. Should the question list be formatted to a character vector with LaTeX math markup? If TRUE (default, or equivalently "latex") the question list is formatted with the same number of digits and LaTeX math markup is added. If FALSE (or equivalently "numeric") then the question list is returned as a numeric vector. If "character" then the question list is a formatted character vector but without LaTeX math markup.
order: logical. Should the question list be ordered numerically? If FALSE (default) the question list is shuffled randomly.
maxit: numeric. Maximum number of iterations to try to find a suitable set of wrong solutions for the question list. If the number of iterations exceed abs(maxit), NULL is returned (with a warning if verbose = TRUE) except if maxit < 0 (which stops with an error). See the examples below.
verbose: logical. Should warnings be issued if no suitable set of wrong solutions can be found?

Details

The function num_to_schoice (or equivalently num2schoice) can be used for generating a single-choice question list for a numeric correct solution. The question list always comprises five elements, one of which is the correct solution. The wrong solutions can be provided or are generated randomly. If wrong is provided only up to 2 elements of it are used in order to assure some random solutions.

Two methods can be used to generate the wrong solutions: Either simply runif or otherwise a full equi-distant grid for the range with step size delta is set up from which a discrete uniform sample is drawn. The former is preferred if the range is large enough while the latter performs better if the range is small (as compared to delta.

The function tries to avoid patterns in the question list that could be used for guessing the correct solution, e.g., situations where (almost) always the highest (or always the lowest) answer is the correct one. Therefore, internally num_to_schoice first randomly decides how many of the 4 wrong solutions should be to the left or to the right of the correct solution, respectively. And in a second step the sampling method is used to find these fixed numbers of wrong solutions to the left and right (if possible!).

By default (format = TRUE or format = "latex"), the question list in the output is formatted to a character vector enclosed in LaTeX math markup to assure consistent rendering. Optionally, using format = FALSE or format = "numeric" the numeric vector without any formatting can be returned as well. This is useful if the numeric question list should be processed further, e.g., adding annotation etc. Finally, format = "character" returns a formatted character vector with the same number of digits but without LaTeX math markup. This is useful if the output format of the exam does not provide LaTeX support.

Exercise templates using num_to_schoice should be thoroughly tested in order to avoid problems with too small ranges or almost identical correct and wrong answers! This can potentially cause problems, infinite loops, etc. See https://www.R-exams.org/tutorials/stresstest/ for some comments/hints regarding stress-testing of such exercise templates.

Examples

Run this code

set.seed(1)
## just a correct solution
num_to_schoice(123.45)

## or equivalently
set.seed(1)
num2schoice(123.45)

## just a correct integer solution
num_to_schoice(123, digits = 0)

## a correct solution with a wider range
num_to_schoice(123.45, range = c(0, 200))

## here, the defaults can't work
num_to_schoice(0.123, verbose = FALSE)
## warning: specified 'range' is too small for 'delta'
## (suppressed here via verbose = FALSE)

## alternatives could be
num_to_schoice(0.123, range = c(0, 1), delta = 0.03, method = "delta")
num_to_schoice(0.123, range = c(-5, 5), delta = 0.05)
num_to_schoice(0.123, wrong = c(0.275, 1.972), delta = 0.05)
num_to_schoice(0.123, wrong = c(0.275, 1.972), range = c(-5, 5), delta = 0.05)

## ## caveat: num_to_schoice() can result in virtually infinite loops, e.g.,
## set.seed(5)
## num_to_schoice(10, range = c(7, 13))
## 
## ## return NULL with warning after 10 iterations
## set.seed(5)
## num_to_schoice(10, range = c(7, 13), maxit = 10)
##
## ## stop with error after 10 iterations
## set.seed(5)
## num_to_schoice(10, range = c(7, 13), maxit = -10)