moodlequiz

https://numbats.github.io/moodlequiz/
Admin
moodlequiz is an R package that enables creating Moodle quiz questions and XML files using literate...
Tokens:7,356
Snippets:49
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install moodlequiz from CRAN

Source: https://numbats.github.io/moodlequiz/index.html

Installs the released version of the moodlequiz package from CRAN. Run this in an R console to install the package.

```r
install.packages("moodlequiz")
```

--------------------------------

### Description question: Introduction with setup and data chunks

Source: https://numbats.github.io/moodlequiz/index.html

A description question in Moodle contains no assessment activities. It provides background context, an image, and a data preview that are bundled into the XML and imported as part of the quiz question.

```markdown
## Introduction

```{r setup, include = FALSE}
library(moodlequiz)
knitr::opts_chunk$set(echo = FALSE)
```

**Meet the penguins!**

![The Palmer Archipelago penguins. Artwork by @allison_horst.](lter_penguins.png)

> The `palmerpenguins` data contains size measurements for three penguin species observed on three islands in the Palmer Archipelago, Antarctica.

```{r data, echo = TRUE}
library(palmerpenguins)
penguins
```
```

--------------------------------

### Examples of cloze_shortanswer, cloze_multichoice, cloze_singlechoice, cloze_numerical, and cloze

Source: https://numbats.github.io/moodlequiz/reference/cloze_questions.html

Examples for each cloze function, showing the generated Moodle inline text. The output lines (prefixed with #>) are the actual returned strings from the R console.

```r
# Short-answer question: Where is the best coffee?
cloze_shortanswer(
  options = c("Melbourne" = 1),
  case_sensitive = FALSE
)
#> [1] "`{1:SHORTANSWER:%100%Melbourne#}`{=html}"

# Multiple-choice question: Select all lower-case answers
cloze_multichoice(
  options = c("a" = 1, "F" = 0, "g" = 1, "V" = 0, "K" = 0),
  type = "vertical"
)
#> [1] "`{1:MULTIRESPONSE:%100%a#~%0%F#~%100%g#~%0%V#~%0%K#}`{=html}"

# Where is Melbourne?
cloze_singlechoice(
  choices(
    c("New South Wales", "Victoria", "Queensland", "Western Australia",
      "South Australia", "Tasmania", "Australian Capital Territory",
      "Northern Territory"),
    "Victoria"
  ),
  type = "dropdown"
)
#> [1] "`{1:MULTICHOICE:%0%New South Wales#~%100%Victoria#~%0%Queensland#~%0%Western Australia#~%0%South Australia#~%0%Tasmania#~%0%Australian Capital Territory#~%0%Northern Territory#}`{=html}"

# Numerical question: Pick a number between 1 and 10
cloze_numerical(
  answer = 5.5,
  tolerance = 4.5
)
#> [1] "`{1:NUMERICAL:=5.500000:4.500000#}`{=html}"

# Automatic cloze questions
cloze(42) # Numerical
#> [1] "`{1:NUMERICAL:=42.000000:0.000000#}`{=html}"
cloze("Australia") # Short answer
#> [1] "`{1:SHORTANSWER:%100%Australia#}`{=html}"
cloze("rep_len", c("rep", "rep.int", "rep_len", "replicate")) # Single choice
#> [1] "`{1:MULTICHOICE:%0%rep#~%0%rep.int#~%100%rep_len#~%0%replicate#}`{=html}"
cloze(c("A", "B", "C"), LETTERS) # Multiple choice
#> [1] "`{1:MULTIRESPONSE:%100%A#~%100%B#~%100%C#~%0%D#~%0%E#~%0%F#~%0%G#~%0%H#~%0%I#~%0%J#~%0%K#~%0%L#~%0%M#~%0%N#~%0%O#~%0%P#~%0%Q#~%0%R#~%0%S#~%0%T#~%0%U#~%0%V#~%0%W#~%0%X#~%0%Y#~%0%Z#}`{=html}"
```

--------------------------------

### Install development version of moodlequiz from GitHub

Source: https://numbats.github.io/moodlequiz/index.html

Installs the development version of the moodlequiz package from GitHub using the remotes package. Requires the remotes package to be installed.

```r
remotes::install_github("numbats/moodlequiz")
```

--------------------------------

### Create an essay question with {type=essay}

Source: https://numbats.github.io/moodlequiz/index.html

Use this question header to create an essay question in the quiz. The type is set to `essay`, and the question text follows the header. This example is part of the penguins quiz and demonstrates how to specify a question type that is not multiple choice.

```markdown
## Telling the story {type=essay}

**Tell the story**

Write a short paragraph about how a penguin's weight relates to their species and sex.

```

--------------------------------

### cloze_shortanswer(options, weight = max(options), feedback = "", case_sensitive = FALSE)

Source: https://numbats.github.io/moodlequiz/reference/cloze_questions.html

Creates a short-answer cloze question where the student provides a text response. The options argument is a named vector where names are answers and values are weights.

```APIDOC
## cloze_shortanswer(options, weight = max(options), feedback = "", case_sensitive = FALSE)

### Description
Creates a short-answer question where the student provides a text response.

### Usage
cloze_shortanswer(options, weight = max(options), feedback = "", case_sensitive = FALSE)

### Arguments
- **options** (named vector) - Required - A named vector of answer options. Names correspond to answers, values specify weights.
- **weight** (numeric) - Optional - Weight for the question. Defaults to the highest weight in `options`.
- **feedback** (character) - Optional - Feedback for answers.
- **case_sensitive** (logical) - Optional - Whether the answer should be case-sensitive. Defaults to `FALSE`.

### Value
A character string containing the Moodle-compatible XML or inline text for the specified cloze question.

### Example
r
cloze_shortanswer(
  options = c("Melbourne" = 1),
  case_sensitive = FALSE
)
#> [1] "`{1:SHORTANSWER:%100%Melbourne#}`{=html}"

```

--------------------------------

### Create a multiple choice question with shuffleanswers and answer divs

Source: https://numbats.github.io/moodlequiz/index.html

Use this question header to create a multiple choice question with shuffled answers. The `shuffleanswers=1` option enables answer shuffling. Answers are specified in `::: {.answer fraction="..."}` divs, with the fraction indicating the percentage of credit (100 for correct, 0 for incorrect). The R code blocks inside the answer divs are the answer choices.

```markdown
## Multiple choice {type=multichoice shuffleanswers=1}

Which of the following generates random numbers from a Normal distribution

::: {.answer fraction="100"}
```{r}
rnorm(10)
```
:::

::: {.answer fraction="0"}
```{r}
runif(10)
```
:::

::: {.answer fraction="0"}
```{r}
rnorm(10)^2
```
:::

```

--------------------------------

### moodlequiz front matter with category and replicates

Source: https://numbats.github.io/moodlequiz/index.html

YAML front matter for a moodlequiz R Markdown document. Sets the title, specifies the moodlequiz output format with one replicate per question, and assigns the quiz category 'penguins'.

```yaml
---
title: Learning with penguins
output: 
  moodlequiz::moodlequiz:
    replicates: 1
moodlequiz:
  category: penguins
---
```

--------------------------------

### BibTeX citation for moodlequiz

Source: https://numbats.github.io/moodlequiz/authors.html

Use this BibTeX entry to cite the moodlequiz R package in academic work. It includes the package title, authors, year, version note, and URL.

```bibtex
@Manual{,
  title = {moodlequiz: R Markdown format for 'Moodle' XML cloze quizzes},
  author = {Mitchell O'Hara-Wild and Emi Tanaka},
  year = {2026},
  note = {R package version 0.2.1.9000},
  url = {https://github.com/numbats/moodlequiz},
}
```

--------------------------------

### cloze_numerical(answer, weight = 1, tolerance = 0, feedback = "")

Source: https://numbats.github.io/moodlequiz/reference/cloze_questions.html

Generates a numerical cloze question where students input a numeric response with an optional tolerance.

```APIDOC
## cloze_numerical(answer, weight = 1, tolerance = 0, feedback = "")

### Description
Generates a numerical question where students input a numeric response with optional tolerance.

### Usage
cloze_numerical(answer, weight = 1, tolerance = 0, feedback = "")

### Arguments
- **answer** (numeric) - Required - The correct numerical answer(s).
- **weight** (numeric) - Optional - Weight for the question. Defaults to `1`.
- **tolerance** (numeric) - Optional - Acceptable range of deviation. Defaults to `0`.
- **feedback** (character) - Optional - Feedback for answers.

### Value
A character string containing the Moodle-compatible XML or inline text for the specified cloze question.

### Example
r
cloze_numerical(
  answer = 5.5,
  tolerance = 4.5
)
#> [1] "`{1:NUMERICAL:=5.500000:4.500000#}`{=html}"

```

--------------------------------

### cloze_multichoice(options, weight = max(options), feedback = "", type = c("vertical", "horizontal"), shuffle = FALSE)

Source: https://numbats.github.io/moodlequiz/reference/cloze_questions.html

Creates a multiple-choice cloze question where students can select one or more correct answers. The type argument controls the presentation style.

```APIDOC
## cloze_multichoice(options, weight = max(options), feedback = "", type = c("vertical", "horizontal"), shuffle = FALSE)

### Description
Creates a multiple-choice question where students can select one or more correct answers.

### Usage
cloze_multichoice(options, weight = max(options), feedback = "", type = c("vertical", "horizontal"), shuffle = FALSE)

### Arguments
- **options** (named vector) - Required - A named vector of answer options. Names correspond to answers, values specify weights.
- **weight** (numeric) - Optional - Weight for the question. Defaults to the highest weight in `options`.
- **feedback** (character) - Optional - Feedback for answers.
- **type** (character) - Optional - Presentation style: `"vertical"` or `"horizontal"`.
- **shuffle** (logical) - Optional - Whether answer options should be shuffled. Defaults to `FALSE`.

### Value
A character string containing the Moodle-compatible XML or inline text for the specified cloze question.

### Example
r
cloze_multichoice(
  options = c("a" = 1, "F" = 0, "g" = 1, "V" = 0, "K" = 0),
  type = "vertical"
)
#> [1] "`{1:MULTIRESPONSE:%100%a#~%0%F#~%100%g#~%0%V#~%0%K#}`{=html}"

```

--------------------------------

### Usage of cloze_shortanswer, cloze_multichoice, cloze_singlechoice, cloze_numerical, and cloze

Source: https://numbats.github.io/moodlequiz/reference/cloze_questions.html

Usage signatures for the five cloze question functions. Use these to create short-answer, multiple-choice, single-choice, numerical, and automatic cloze questions for Moodle quizzes.

```r
cloze_shortanswer(
  options,
  weight = max(options),
  feedback = "",
  case_sensitive = FALSE
)

cloze_multichoice(
  options,
  weight = max(options),
  feedback = "",
  type = c("vertical", "horizontal"),
  shuffle = FALSE
)

cloze_singlechoice(
  options,
  weight = max(options),
  feedback = "",
  type = c("dropdown", "vertical", "horizontal"),
  shuffle = FALSE
)

cloze_numerical(answer, weight = 1, tolerance = 0, feedback = "")

cloze(x, ...)
```

--------------------------------

### cloze_singlechoice(options, weight = max(options), feedback = "", type = c("dropdown", "vertical", "horizontal"), shuffle = FALSE)

Source: https://numbats.github.io/moodlequiz/reference/cloze_questions.html

Generates a single-choice cloze question where students select one correct answer from a list. The type argument controls the presentation style.

```APIDOC
## cloze_singlechoice(options, weight = max(options), feedback = "", type = c("dropdown", "vertical", "horizontal"), shuffle = FALSE)

### Description
Generates a single-choice question where students select one correct answer from a list.

### Usage
cloze_singlechoice(options, weight = max(options), feedback = "", type = c("dropdown", "vertical", "horizontal"), shuffle = FALSE)

### Arguments
- **options** (named vector) - Required - A named vector of answer options. Names correspond to answers, values specify weights.
- **weight** (numeric) - Optional - Weight for the question. Defaults to the highest weight in `options`.
- **feedback** (character) - Optional - Feedback for answers.
- **type** (character) - Optional - Presentation style: `"dropdown"`, `"vertical"`, or `"horizontal"`.
- **shuffle** (logical) - Optional - Whether answer options should be shuffled. Defaults to `FALSE`.

### Value
A character string containing the Moodle-compatible XML or inline text for the specified cloze question.

### Example
r
cloze_singlechoice(
  choices(
    c("New South Wales", "Victoria", "Queensland", "Western Australia",
      "South Australia", "Tasmania", "Australian Capital Territory",
      "Northern Territory"),
    "Victoria"
  ),
  type = "dropdown"
)
#> [1] "`{1:MULTICHOICE:%0%New South Wales#~%100%Victoria#~%0%Queensland#~%0%Western Australia#~%0%South Australia#~%0%Tasmania#~%0%Australian Capital Territory#~%0%Northern Territory#}`{=html}"

```

--------------------------------

### cloze(x, ...)

Source: https://numbats.github.io/moodlequiz/reference/cloze_questions.html

Automatic question type selection based on the class of the answer. The correct answer determines the type: numeric uses cloze_numerical(), character uses cloze_shortanswer() or cloze_singlechoice()/cloze_multichoice() if selectable options are given.

```APIDOC
## cloze(x, ...)

### Description
Automatic question types based on the class of the answers.

### Usage
cloze(x, ...)

### Arguments
- **x** - Required - The correct answer which also determines the question type (e.g. `numeric` will use `cloze_numerical()` and `character` will use `cloze_shortanswer()` or `cloze_singlechoice()`/`cloze_multichoice()` if selectable options are given as the second argument).
- **...** - Optional - Additional arguments passed to other `cloze()` methods (such as the available options and other `cloze_*()` arguments).

### Value
A character string containing the Moodle-compatible XML or inline text for the specified cloze question.

### Examples
r
cloze(42) # Numerical
#> [1] "`{1:NUMERICAL:=42.000000:0.000000#}`{=html}"
cloze("Australia") # Short answer
#> [1] "`{1:SHORTANSWER:%100%Australia#}`{=html}"
cloze("rep_len", c("rep", "rep.int", "rep_len", "replicate")) # Single choice
#> [1] "`{1:MULTICHOICE:%0%rep#~%0%rep.int#~%100%rep_len#~%0%replicate#}`{=html}"
cloze(c("A", "B", "C"), LETTERS) # Multiple choice
#> [1] "`{1:MULTIRESPONSE:%100%A#~%100%B#~%100%C#~%0%D#~%0%E#~%0%F#~%0%G#~%0%H#~%0%I#~%0%J#~%0%K#~%0%L#~%0%M#~%0%N#~%0%O#~%0%P#~%0%Q#~%0%R#~%0%S#~%0%T#~%0%U#~%0%V#~%0%W#~%0%X#~%0%Y#~%0%Z#}`{=html}"

```

--------------------------------

### Reference boxplot: penguin weight by species and sex

Source: https://numbats.github.io/moodlequiz/index.html

The reference R code chunk that produces the boxplot of penguin weight by species and sex, used as the expected output for the cloze question. It uses `ggplot2` with `geom_boxplot()` and a custom fill scale.

```r
```{r boxplot-sex, fig.cap="Boxplots of penguin weight by species and sex"}
penguins |> 
  ggplot(aes(x = body_mass_g, y = sex, fill = species)) +
  geom_boxplot() +
  scale_fill_manual(values = c("darkorange","darkorchid","cyan4")) + 
  theme_minimal()
```
```

--------------------------------

### Cloze question: Complete ggplot boxplot code

Source: https://numbats.github.io/moodlequiz/index.html

A cloze question that asks students to complete the code to produce a boxplot of penguin weight by species and sex. The inline `r cloze()` calls embed the answer options for the x, y, fill, and geom function.

```r
library(ggplot2)
penguins |> 
  ggplot(aes(x = `r cloze("body_mass_g", colnames(penguins))`, y = `r cloze("sex", colnames(penguins))`, fill = `r cloze("species", colnames(penguins))`)) +
  `r cloze("geom_boxplot")`() +
  scale_fill_manual(values = c("darkorange","darkorchid","cyan4")) + 
  theme_minimal()
```
Tokens:
Raw