exams2blackboard {exams}

Generation of Exams in Blackboard Format

Description

Automatic generation of exams in Blackboard format (which is partially based on QTI 1.2).

Usage

  exams2blackboard(file, n = 1L, nsamp = NULL, dir = ".",
    name = NULL, quiet = TRUE, edir = NULL,
    tdir = NULL, sdir = NULL, verbose = FALSE, rds = FALSE,
    resolution = 100, width = 4, height = 4, encoding = "UTF-8",
    envir = NULL, engine = NULL,
    num = NULL, mchoice = NULL,
    schoice = mchoice, string = NULL, cloze = NULL,
    template = "blackboard",
    pdescription = "This is an item from an item pool.",
    tdescription = "This is today's test.",
    pinstruction = "Please answer the following question.",
    tinstruction = "Give an answer to each question.",
    maxattempts = 1, zip = TRUE, points = NULL,
    eval = list(partial = TRUE, rule = "false2", negative = FALSE),
    base64 = FALSE, converter = NULL, seed = NULL, mathjax = NULL,
    fix_pre = TRUE, ...)

  make_itembody_blackboard(rtiming = FALSE, shuffle = FALSE,
    rshuffle = shuffle, minnumber = NULL, maxnumber = NULL,
    defaultval = NULL, minvalue = NULL, maxvalue = NULL,
    cutvalue = NULL, enumerate = TRUE, digits = NULL,
    tolerance = is.null(digits), maxchars = 12,
    eval = list(partial = TRUE, rule = "false2", negative = FALSE),
    qti12 = FALSE, mathjax = FALSE)

Arguments

file

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

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 default is the current working directory.

name

character. A name prefix for resulting exercises and ZIP file.

quiet

logical. Should output be suppressed when calling xweave?

edir

character specifying the path of the directory (along with its sub-directories) in which the files in file are stored (see also xexams).

tdir

character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up (i.e., existing files are deleted) and only certain temporary files are preserved.

sdir

character specifying a directory for storing supplements, by default this is chosen via tempfile.

verbose

logical. Should information on progress of exam generation be reported?

rds

logical indicating whether the return list should also be saved as an RDS data file.

resolution, width, height

numeric. Options for rendering PNG graphics passed to xweave.

encoding

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

envir

argument passed to xweave (which passes it to knit).

engine

argument passed to xweave indicating whether "Sweave" (default) or "knitr" should be used for rendering Rnw exercises.

num

function or named list applied to numerical (i.e., type num) questions. If num is a function, num will be used for generating the item body of the question, see function make_itembody_blackboard(). If num is a named list, these arguments will be passed to function make_itembody_blackboard().

mchoice, schoice, string, cloze

function or named list applied to multiple choice, single choice, string, and cloze questions (i.e., type mchoice, schoice, string, and cloze), respectively. See argument num for more details.

template

character. The IMS QTI 1.2 or 2.1 template that should be used. Currently, the package provides "blackboard.xml".

pdescription

character. Description (of length 1) of the item pool (i.e., the set of copies).

tdescription

character. Description (of length 1) of the overall assessment (i.e., exam).

pinstruction

character. Instruction (of length 1) for the item pool (i.e., set of copies).

tinstruction

character. Instruction (of length 1) for the overall assessment (i.e., exam).

maxattempts

integer. The maximum attempts for one question, may also be set to Inf.

zip

logical. Should the resulting XML file (plus supplements) be zipped?

points

integer. How many points should be assigned to each exercise? Note that this argument overules any exercise points that are provided within an expoints tag in the Rnw/Rmd exercise file. The vector of points supplied is expanded to the number of exercises in the exam.

eval

named list, specifies the settings for the evaluation policy, see function exams_eval.

base64

logical. Should supplementary files be embedded using Base 64 coding? Argument base64 may also be a character vector of file suffixes that should be encoded, e.g. base64 = c("png", "rda") will only encode PNG images and binary .rda files. If set to NULL only image files will be encoded.

converter, ...

arguments passed on to make_exercise_transform_html. The default for converter is set to "ttm" unless there are Rmd exercises in file where "pandoc" is used.

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.

mathjax

logical. Should the JavaScript from https://www.MathJax.org/ be included for rendering mathematical formulas? By default mathjax = FALSE unless converter = "pandoc-mathjax" is used. However, also for the default converters (producing MathML output) mathjax = TRUE can be used, enabling rendering of mathematical equations in browsers without native MathML support (like Chrome/Chromium). Note that this only works in Classic Blackboard but not in Blackboard Ultra.

fix_pre

logical. Should the HTML <pre> environment for rendering verbatim output be replaced by <code> tags? This is necessary in classical Blackboard which does not render <pre> correctly.

rtiming, shuffle, rshuffle, minnumber, maxnumber, defaultval, minvalue, maxvalue

arguments used for IMS QTI 1.2 item construction, for details see the XML specification (see IMS Global Learning Consortium, Inc. 2012), especially Section 4.

cutvalue

numeric. The cutvalue at which the exam is passed.

enumerate

logical. Insert potential solutions in enumerated list?

digits

integer. How many digits should be used for num exercises?

tolerance

logical. Should tolerance intervals be used for checking if the supplied num answer/number is correct? The default is to use tolerance intervals if digits = NULL.

maxchars

numeric. Lower bound for the number of characters in fill-in-blank fields. The actual number of characters is selected as the maximum number of characters of this value and the actual solution.

qti12

logical. For reverse compability to plain QTI 1.2 XML format.

Details

Blackboard employs an XML format that essentially uses the Question & Test Interoperability (QTI) standard, version 1.2, see IMS Global Learning Consortium, Inc. (2012). However, as this deviates from the plain QTI 1.2 standard in several places, the exams2qti12 cannot be used directly. Instead, exams2blackboard is a new interface that is likely to be improved in future versions.

exams2blackboard produces a .zip file that may be uploaded into Blackboard. This includes the final XML file of the exam/assessment as well as possible supplement folders that include images, data sets etc. used for the exam. After uploading the test into Blackboard, the material will appear under ‘Course Tools’: the test will be available in ‘Tests’, and each pool within the test will also appear in ‘Pools’.

exams2blackboard proceeds by (1) calling xweave on each exercise, (2) reading the resulting LaTeX code, (3) transforming the LaTeX code to HTML, and (4) embedding the HTML code in a XML file using Blackboard's QTI standards for assessments and question items. For steps (1) and (2) the standard drivers in xexams are used. In step (3), a suitable transformation function is set up on the fly using make_exercise_transform_html, see also the details section in exams2html. For step (4), the function will cycle through all questions and exams to generate the final XML file in the Blackboard QTI standard. Therefore, each question will be included in the XML as one section. The replicates of each question will be written as question items of the section.

The function uses the XML template for Blackboard's QTI standards for assessments and items to generate the exam (per default, this is the XML file blackboard.xml provided in the xml folder of this package). The assessment template must provide one section including one item. exams2blackboard will then use the single item template to generate all items, as well as the assessment and section specifications set within the template.

The default template will generate exams/assessments that sample one replicate of a question/item for each section. The usual procedure in exam/assessment generation would be to simply copy & paste the XML template of the package and adapt it to the needs of the user. Note that all specifiers that have a leading ## in the XML template will be replaced by suitable code in exams2blackboard and should always be provided in the template. I.e., the user may add additional tags to the XML template or modify certain specifications, like the number of replicates/items that should be sampled for each section etc.

Per default, the individual question/item bodies are generated by function make_itembody_blackboard, i.e., make_itembody_blackboard checks the type of the question and will produce suitable XML code. Note that for each question type, either the arguments of make_itembody_blackboard may be set within num, mchoice, schoice and string in exams2blackboard, by providing a named list of specifications that should be used, or for each questiontype, a function that produces the item body XML code may be provided to num, mchoice, schoice and string. E.g., mchoice = list(shuffle = TRUE) will force only multiple choice questions to have a shuffled answerlist.

Note that in Blackboard cloze items are not officially supported, and hence this type of item is not supported in the current version of exams2blackboard either. It is currently investigated if a workaround may be implemented to allow for cloze items.

Value

exams2blackboard returns a list of exams as generated by xexams.

make_itembody_blackboard returns a function that generates the XML code for the itembody tag in Blackboard's version of the IMS QTI 1.2 format.

References

Blackboard, Inc. (2016). Blackboard Help: Question types. https://help.blackboard.com/Learn/Instructor/Ultra/Tests_Pools_Surveys/Question_Types

IMS Global Learning Consortium, Inc. (2012). IMS Question & Test Interoperability: ASI XML Binding Specification Final Specification Version 1.2. https://www.imsglobal.org/question/qtiv1p2/imsqti_asi_bindv1p2.html

Zeileis A, Umlauf N, Leisch F (2014). Flexible Generation of E-Learning Exams in R: Moodle Quizzes, OLAT Assessments, and Beyond. Journal of Statistical Software, 58(1), 1–36. doi:10.18637/jss.v058.i01.

See Also

exams2qti12

Examples

## load package and enforce par(ask = FALSE)
library("exams")
options(device.ask.default = FALSE)

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

## output directory
dir.create(mydir <- tempfile())

## generate .zip with Blackboard exam in temporary directory
exams2blackboard(myexam, n = 3, dir = mydir)
dir(mydir)