-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathREADME.Rmd
244 lines (151 loc) · 9.4 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# moodlequiz
<!-- badges: start -->
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[](https://github.com/numbats/moodlequiz/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
The `moodlequiz` R package which allows the creation of [Moodle](https://moodle.org/) quiz questions using literate programming with R Markdown. This makes it easy to quickly create a quiz that can be randomly replicated with new datasets, questions, and options for answers.
## Installation
You can install the development version of moodlequiz like so:
``` r
remotes::install_github("numbats/moodlequiz")
```
## Usage
A moodlequiz document produces a [Moodle XML file](https://docs.moodle.org/405/en/Moodle_XML_format) suitable for importing quiz questions to Moodle into the question bank. Questions can be organized into categories to use Moodle's random question functionality. An entire quiz consisting of multiple questions can be written in a single R Markdown document.
### Front matter
The front matter allows you to describe the number of random replications, and the general category for all of these questions. For example:
```yml
---
title: Learning with penguins
output:
moodlequiz::moodlequiz:
replicates: 1
moodlequiz:
category: penguins
---
```
In this case the questions will be imported into the 'penguins' category, with only 1 replicate for each question (the default).
It is possible to use randomization in R to produce many different replicates of the same question (as shown in the quiz randomization vignette).
### Body
The R Markdown document's body is used to create quiz questions with full markdown support. Any typical markdown output including figures, equations, tables and cross-references (excepting interactive outputs [#31](https://github.com/numbats/moodlequiz/issues/31)) will be imported as part of your Moodle quiz questions. As a literate programming user, writing quiz questions with full markdown support is a wonderful experience compared to the usual quiz creation workflow in Moodle.
#### Writing questions
Headers are used to separate quiz questions and organize them into subcategories.
* `# H1: Sub-category`
Questions within this header will be organised together into this sub-category.
This is useful if your quiz contains several thematically similar questions, or if you want to randomize a specific question of group of questions.
* `## H2: Quiz questions`
Quiz questions and their settings are specified within H2 headers.
For example:
````md
# Basics
## Introduction
...
## Plotting weight
...
## Telling the story {type=essay}
...
````
This example quiz consists of a single sub-category (basics) which contains three quiz 'questions' of different types:
##### Description questions
A 'description' question in Moodle doesn't contain any assessment activities. It is useful to describe the activity, such as give some background information on the dataset or learning objectives.
````md
```{r, echo = FALSE, results="asis"}
cat(readLines("man/examples/penguins.Rmd")[13:30], sep = "\n")
```
````
In this example, a description question is used to provide background context about the Palmer Archipelago penguins (along with a lovely illustration and preview of the dataset). Both the image and table will be bundled into the XML and imported as part of the Moodle quiz question.
#### Cloze questions
The cloze style questions embed many questions within the question text (https://docs.moodle.org/405/en/Embedded_Answers_(Cloze)_question_type).
There are four types of cloze questions:
- **`cloze_shortanswer()`**: Creates a short-answer question where the student provides a text response.
- **`cloze_singlechoice()`**: Generates a single-choice question where students select one correct answer from a list.
- **`cloze_multichoice()`**: Creates a multiple-choice question where students can select one or more correct answers.
- **`cloze_numerical()`**: Generates a numerical question where students input a numeric response with optional tolerance.
The single and multiple choice cloze questions support various options that change the appearance and shuffling behaviour.
There is also the **`cloze()`** function, which automatically chooses the appropriate question type based on the class of the input:
- Numerical: `cloze(42)`
- Short answer: `cloze("Australia")`
- Single choice: `cloze("rep_len", c("rep", "rep.int", "rep_len", "replicate"))`
- Multiple choice: `cloze(c("A", "B", "C"), LETTERS)`
These functions should be used with inline R code, for example: `` `r knitr::inline_expr('cloze_singlechoice(choices(c("Adelie", "Chinstrap", "Gentoo"), "Chinstrap"))')` ``
````md
```{r, echo = FALSE, results="asis"}
cat(readLines("man/examples/penguins.Rmd")[31:83], sep = "\n")
```
````
#### Other questions
Other types of questions consist of a single answer field and some question text. You can specify any type of questions (even those defined in Moodle extension packages) with `## Question {type = <TYPE>}`. Question types included in standard installations of Moodle include:
* multichoice
* truefalse
* shortanswer
* matching (not yet supported)
* essay
* numerical
````md
```{r, echo = FALSE, results="asis"}
cat(readLines("man/examples/penguins.Rmd")[84:88], sep = "\n")
```
````
In the penguins example, you can see that the question type has been set to `essay`.
---
These question types often have many question-specific options which are outlined in the [Moodle XML format](https://docs.moodle.org/405/en/Moodle_XML_format) guide. Question specific options are specified in the question headers, for example enabling `shuffleanswers` for multiple choice questions with `## Multiple choice {type=multichoice shuffleanswers=1}`.
Many of these question types require answers specified in `<answer fraction="...">...</answer>` sections. To specify the answers for a question with moodlequiz, use the answers div like so:
````md
```{r, echo = FALSE, results="asis"}
cat(readLines("man/examples/other-examples.Rmd")[6:26], sep = "\n")
```
````
## Importing questions into Moodle
### Create the XML quiz
Start by rendering the quiz to obtain the Moodle XML file for the quiz. You can try this with the Palmer penguins quiz described above, which is found here: <https://raw.githubusercontent.com/numbats/moodlequiz/refs/heads/main/man/examples/penguins.Rmd>
Once rendered, you should find a corresponding XML file in the same folder. It should look like this: <https://raw.githubusercontent.com/numbats/moodlequiz/refs/heads/main/man/examples/penguins.xml>
### Import quiz questions
To import the quiz into Moodle, go to your Moodle course's question bank. The navigation may vary among institutions, so if you struggle to find it the URL pattern is: `https://<DOMAIN>/question/edit.php?courseid=<COURSE ID>` (where `<COURSE_ID>` is the number found in most URLs of your course).
Import questions by selecting "Import" from the drop-down.
From the import form:
1. Select "Moodle XML format" as the file format
2. Select "Get category from file" under the "General" section
3. Import the XML file into the file box
4. Click import
You should now see the questions successfully imported into Moodle, along with a preview of the questions. Please report any importation issues.
### Creating a quiz
Create a quiz as you normally would in Moodle (instructions here: https://docs.moodle.org/en/Building_Quiz)
When adding a question, select "from question bank" (or "a random question" for random questions within categories).
In the question import dialogue:
1. Select the question category which was specified in the front matter (penguins)
2. Sort questions alphabetically by name by clicking on the "Question" header in the table
3. Select the questions to import via the checkboxes in the table (or select all with the checkbox in the table header)
4. Click "Add selected questions to the quiz"
Your questions are now added to the quiz! :tada:
You can now repaginate and further adjust the quiz settings as necessary.
<!-- ## Example -->
<!-- Below is an example quiz question which uses the `cloze` question type to select the code which produces the plot. -->
<!-- {style="border:1px solid black;"} -->
<!-- The above quiz is created from the R Markdown document below. Knitting the document below will generate 5 different versions of the quiz where the x, y, color, and size are mapped randomly to one of the variables in the `mtcars` data. -->
<!-- ```{r, echo = FALSE, results="asis"} -->
<!-- cat("````\n") -->
<!-- cat(readLines("man/examples/draw-scatterplots.Rmd"), sep = "\n") -->
<!-- cat("````") -->
<!-- ``` -->