--- title: "moodef: Defining Moodle Quizzes from R" date: "2025-01-18" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{moodef: Defining Moodle Quizzes from R} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` # Introduction [*Moodle*](https://moodle.org/) is a widespread open source learning platform. It is the official teaching support platform of the University of Granada (Spain), where we develop this package. The goal of the `moodef` package is to harness the power of R to make defining *Moodle* elements easier. In particular, this first version is focused on the definition of questions for quizzes. The process is as follows: we define the questions in R, from the definition, we generate an XML file that we can import directly into *Moodle*. What does this package provide? On the one hand, we have simplified the process of manually defining the questions, considering only the essential parameters for each type. On the other hand, the package offers an infrastructure that allows the automatic or semi-automatic generation of questions from R: to define a question we simply need to include a row in a data frame, a CSV file or an *Excel* file. The rest of this document is structured as follows: First, the question definition styles and the general process of defining questions is presented. Next, we show the types of questions considered and how to define them. Finally, the document ends with conclusions. # Question Definition Styles One of the primary objectives in designing this package has been to simplify the question definition process. For example, while it is possible to explicitly define the question type, it can also be inferred from the provided definition. In certain cases, you may need to specify additional details, such as the orientation of answer presentation, but generally, the type is deduced from the content of the definition. At a global level, **category level**, several elements can be defined for all questions, including: - **Category** - **Copyright** - **License** - **Author** - **Fraction** - **Feedback** (correct, incorrect, or partially correct responses) The package supports two styles of question definition: the **simple style** and the **extended style**. In the extended style, some of the global elements can be redefined for individual questions. ## Simple Style In the simple style, the most frequently used default values are assumed for each question. This allows you to define only the specific components of the question: - **Statement** - An **optional image** - **Answers** All questions belong to the same category and share the globally defined values for copyright, license, author, fraction, and feedback. Fraction does not make sense for all question types. ## Extended Style The extended style allows you to define or override additional elements for each question. These elements are optional, and if not explicitly defined, the global values are used. In addition to the components of the simple style, the following elements can be specified for each question: - **Category** - **Fraction** - **Identifier** - **Name** - **Author** - **Feedback** (general, correct, incorrect, or partially correct responses) - Feedback for each **answer** - **Tags** # Question Definition Process Questions are defined within the framework of a *category* (a *Moodle* concept). The **category level** includes the general configuration parameters that apply to all questions, as explained in the previous section. Within the category definition, a set of questions is then defined. Questions can be created either by: - Using a specific function for each question, - defining a data frame, or - importing a definition from a CSV or *Excel* file. Once the questions are defined, the XML structure can be generated either as a string or as a file for direct import into *Moodle*. In this section, we will explain the three steps of this process: 1. **Define the category** 1. **Define questions** 1. **Generate the XML file** ## Define the category To define a category we use the function `question_category()` and we have to indicate its name: It creates an object of class `question_category`. Below is a call to the function with the values of the parameters that we usually define. ```{r setup} library(moodef) qc <- question_category(category = 'Initial test', copyright = 'Copyright © 2025 Universidad de Granada', license = 'License Creative Commons Attribution-ShareAlike 4.0', author = 'Jose Samos') ``` In addition to the category name in the `category` parameter, we define the `copyright`, `license` and `author` parameters that will appear between comments in the XML file associated with each question, as can be seen below. ````{verbatim, lang = "xml"} $course$/top/Initial test ... ... ]]> ... ... ```` Below is the function call being executed, including the values for the remaining parameters. ```{r} qc <- question_category(category = 'Initial test', first_question_number = 1, copyright = 'Copyright © 2025 Universidad de Granada', license = 'License Creative Commons Attribution-ShareAlike 4.0', author = 'Jose Samos', fraction = 0, correct_feedback = 'Correct.', partially_correct_feedback = 'Partially correct.', incorrect_feedback = 'Incorrect.', adapt_images = TRUE, width = 800, height = 600) ``` We are going to discuss the use of each parameter. Questions have a name, which is displayed as a summary in the *Moodle* question bank. In the extended style, the name can be explicitly defined. However, if it is not defined—or in the case of the simple style—we generate the name by combining the question number (obtained from `first_question_number` parameter), the deduced question type, and the beginning of its statement. For example, the following is a generated question name. ````{verbatim, lang = "xml"} ... q_001_multichoice_what_are_the_basic_arithmetic_operations ... ```` Using the parameter `first_question_number`, the number that will be assigned to the first question is defined, with a three-digit format. This number will increase for each question. The `fraction` attribute is used in various question types to determine how a specific answer impacts the question's score. Specifically, for incorrect answers in the `multichoice` and `truefalse` types, the value calculated by dividing `fraction` by the number of incorrect answers available is considered as the amount deducted in case of an incorrect response. If it has a value of 0, incorrect answers for those question types are not penalized. For each question we can indicate feedback text for cases in which the answer is correct, partially correct or incorrect: The corresponding values are provided by the `correct_feedback`, `partially_correct_feedback` and `incorrect_feedback` parameters. Finally, each question stem can include an image. Sometimes the images we use have very different sizes and require a prior transformation to homogenize their presentation. This transformation can be carried out automatically by indicating it using the parameter `adapt_images` (default is `FALSE`). Using the parameters `width` and `height` we indicate the size of the resulting image. It is advisable to test this functionality and adjust the size accordingly by viewing the result when defining a questionnaire in *Moodle*. **The original images are not modified**, only those that are embedded in the XML file. ## Define questions Once we have a `question_category` object created, we can define questions that are added to it. We can define the questions one by one using a definition function or in bulk using a data frame, a CSV file or an *Excel* file. Below we show the possibilities offered. ### Definition function We provide two functions for defining questions: `define_question()` and `define_extended_question()`. These are used to define questions in the simple style and the extended style, respectively. **They can be mixed**. #### Simple Style The minimum we have to define about a question is its statement. Here's how to define a question using the `define_question()` function. ```{r example1} qc <- qc |> define_question( question = 'Describe the addition operation.' ) ``` Below is the definition of a simple style question with all possible parameters, which we explain below. ```{r example2} qc <- qc |> define_question( type = 'v', question = 'Place the name of the operations as they appear in the figure.', image = system.file("extdata", "ops.png", package = "moodef"), image_alt = 'Operations', answer = 'Addition', a_1 = 'Multiplication', a_2 = 'Division', a_3 = 'Subtraction' ) ``` The type of question can be explicitly indicated using its associated code. If it is not specified, it is deduced from the statement and the answers. In this case, the `type` parameter is used to distinguish between two types of questions and to specify the presentation of the answers. It can take four values: empty, `h`, `v`, or `x`. In the example above, the value is `v`. As we will see in the next section, this indicates that it is not a `multichoice` question and that the answers are displayed vertically. The question statement is defined using the `question` parameter. An image can be displayed after the statement. The file containing the image is specified using the `image` parameter. In the example, we use the name of a file included in this package. Each image must also include a description, which is defined with the `image_alt` parameter. Finally, the answers to the question are defined. The first answer is indicated using the `answer` parameter. If additional answers are needed, they can be included as variable parameters using any parameter names (or no names), as many as required. #### Extended Style We can achieve the same definition as above using the extended style. In this case, the result will be exactly the same as before, but this function allows for the definition of additional parameters. ```{r example2-2} qc <- qc |> define_extended_question( type = 'v', question = 'Place the name of the operations as they appear in the figure.', image = system.file("extdata", "ops.png", package = "moodef"), image_alt = 'Operations', answer = 'Addition', a_1 = 'Multiplication', a_2 = 'Division', a_3 = 'Subtraction' ) ``` The previous definition is equivalent to the following. In the code below, the default obtained values have been used. We could modify any of the indicated values or add new ones according to our needs. For example, additional answers, feedback for the answers, and tags to describe the questions can be defined. ```{r example2-3} qc <- qc |> define_extended_question( category = 'Initial test', type = 'ordering<|>v', fraction = 0, id = '', name = 'q_001_ordering_v_place_the_name_of_the_operations_as_they', author = 'Jose Samos', fb_general = '', fb_correct = 'Correct.', fb_partially = 'Partially correct.', fb_incorrect = 'Incorrect.', question = 'Place the name of the operations as they appear in the figure.', image = system.file("extdata", "ops.png", package = "moodef"), image_alt = 'Operations', answer = 'Addition', a_1 = 'Multiplication', a_2 = 'Division', a_3 = 'Subtraction', fb_a_1 = '', fb_a_2 = '', fb_a_3 = '', tag_1 = '' ) ``` ### Definition using a CSV file or an *Excel* file We can create an empty CSV file with the necessary columns using the `create_question_csv()` function. In addition to the file name, we can specify the separator to use (`,` or `;`), and if we need to use the extended style, we indicate it with the parameter `extended = TRUE` (default is `FALSE`). ```{r} file <- create_question_csv(file = tempfile(fileext = '.csv')) ``` The content of the file for the simple style is shown below. ````{verbatim, lang = "csv"} "type","question","image","image_alt","answer","a_1","a_2","a_3" ```` For the extended style, the content is also shown afterward. ````{verbatim, lang = "csv"} "category", "type", "fraction", "id", "name", "author", "fb_general", "fb_correct", "fb_partially", "fb_incorrect", "question", "image", "image_alt", "answer", "a_1", "a_2", "a_3", "a_4", "fb_answer", "fb_a_1", "fb_a_2", "fb_a_3", "fb_a_4", "tag_1", "tag_2", "tag_3" ```` We can add as many additional columns as we deem necessary. In the case of the extended style, the same number of answer columns as feedback columns must be included, and at least one tags column must be present (even if the values in these columns are not defined). From that file, we can include rows using a text editor, R or some tool to edit CSV files in spreadsheet format. Below is the content of a CSV file included in this package for the simple style in table format.
```{r echo=FALSE, results = "asis"} file <- system.file("extdata", "questions.csv", package = "moodef") df <- read_question_csv(file = file) df$a_3 <- NULL pander::pandoc.table(df, split.table = Inf) ```
Once available, we can generate all the questions using the `define_questions_from_csv()` function, as shown below. ```{r, eval=FALSE} file <- system.file("extdata", "questions.csv", package = "moodef") qc <- qc |> define_questions_from_csv(file) ``` There are types of questions in which two string values must be indicated for each answer. The criterion we have adopted to include two values in a cell is to use a separator and define them in a single string, the separator is `<|>`: It can be seen in the definition of some of the previous questions, for example, `Addition<|>+` or `1.33<|>0.03`. In this example, questions with images have not been included due to the difficulty of referencing the image files in the package from the CSV file, but they can be included without any problem. For *Excel* files the definition is carried out in the same way. The corresponding functions are: `create_question_excel()` and `define_questions_from_excel()`. ### Definition using a data frame We can also define questions in bulk using a data frame. An empty data frame can be created with the `create_question_data_frame()` function (which can also be used with the parameter `extended = FALSE`, as shown in the previous example for the CSV file) or read from a CSV file using the `read_question_csv()` function. In this example, we will read a data frame that includes images in the question statements. ```{r} file <- system.file("extdata", "questions_image.csv", package = "moodef") df <- read_question_csv(file = file) ``` The content of the data frame is shown below.
```{r echo=FALSE, results = "asis"} pander::pandoc.table(df, split.table = Inf) ```
In this case we are going to update the figure data with the files included in the package (in a local example, this is not necessary). ```{r} df[1, 'image'] <- system.file("extdata", "divide.png", package = "moodef") df[2, 'image'] <- system.file("extdata", "ops.png", package = "moodef") ``` From R we can add new rows or modify existing ones. As we have explained in the previous section, there are questions in which we need to define two values in a cell using a separator: `<|>`. To facilitate the definition of these cells, we have defined the function `vector_to_string()` that, from a vector, generates a string including that separator, as shown in the following example. ```{r} s <- vector_to_string(c('Addition', '+')) s ``` Once the definition of the questions in the data frame is finished, we can add it to the `question_category` object using the `define_questions_from_data_frame()` function, as it's shown in the following. ```{r, eval=FALSE} qc <- qc |> define_questions_from_data_frame(df) ``` ## Generate the XML file Once the questions we need have been defined, the next step is to generate the XML file. We use the `generate_xml_file()` function, to which we have to indicate a file name. ```{r} file <- tempfile(fileext = '.xml') qc <- qc |> generate_xml_file(file) ``` The generated file is the one that we can import from *Moodle* in the *Question Bank* section. If we have included images, the file size increases considerably because they are embedded in XML (not referenced). ```{r} file.size(file) ``` The definition file for a single question is shown below. ````{verbatim, lang = "xml"} $course$/top/Initial test q_001_multichoice_what_are_the_basic_arithmetic_operations

What are the basic arithmetic operations?

]]> 1.0 0.5 0 true true abc 0 Correct. Partially correct. Incorrect. Addition, subtraction, multiplication and division. Correct. Addition and subtraction. Incorrect. Addition, subtraction, multiplication, division and square root. Incorrect. ```` # Kind of questions We have simplified and generalized the definition process for 10 types of questions, so that we do not even have to indicate the type to define them, it is deduced from the definition: It depends on the value of the `answer` field. In some cases a character in the `type` field is used to distinguish between two types whose definition is identical or to indicate the orientation of the answers (horizontal or vertical), as we will see below. For each kind of questions, the code for its type is specified, followed by (separated by ':') the code that can also be used to deduce the same type. When no value is required, it is expressed as `''` (there is no need to include the quotation marks; simply leave the cell blank or use the default parameter value). **Either of the two codes provided can be used interchangeably to identify the question type.** ## Essay (`essay`: `''`) Only includes the question statement with or without an image (the `answer` field is empty). The answer to the question is made through free text. Below is an example that we had shown before. ```{r} qc <- qc |> define_question( question = 'Describe the addition operation.' ) ``` ## True/False (`truefalse`: `''`) The `answer` field contains the correct answer. If this is one of the literals corresponding to the Boolean values (`'True'` or `'False'`), nothing else needs to be indicated. Here is an example. ```{r} qc <- qc |> define_question( question = 'The square root is a basic arithmetic operation.', answer = 'False' ) ``` If we use the extended style for defining the question, we can specify feedback for each answer. ## Numerical (`numerical`: `''`) If the value of field `answer` is a number with or without decimal places, or a vector of two numbers, it is a `numerical` question. In this type of questions we only have to indicate correct values of the answer. If, instead of a value, we indicate a vector of two values, the second number represents the margin of error in which the answer is accepted as valid. Below are two examples. ```{r} qc <- qc |> define_question( question = 'What is the result of SQRT(4)?', answer = '2', a_1 = '-2' ) |> define_question( question = 'What is the result of 4/3?', answer = c('1.33', '0.03') ) ``` In this case as well, with the extended definition style, feedback can be defined for each answer. ## Short Answer (`shortanswer`: `''`) If only field `answer` is defined and it is not a Boolean or numeric value, it is of type `shortanswer`, for example: ```{r} qc <- qc |> define_question( question = 'What basic operation does it have as a + symbol?', answer = 'Addition' ) ``` Feedback for the answer can also be defined using the extended style. ## Multiple Choice (`multichoice`: `''`) If field `answer` and the rest of the answers are of type string, it is of type `multichoice`. The content of field `answer` is the correct answer. Here is an example. ```{r} qc <- qc |> define_question( question = 'What are the basic arithmetic operations?', answer = 'Addition, subtraction, multiplication and division.', a_1 = 'Addition and subtraction.', a_2 = 'Addition, subtraction, multiplication, division and square root.' ) ``` As mentioned earlier, feedback for the answers can be specified using the extended definition style. ## Ordering (`ordering<|>h`: `h` or `ordering<|>v`: `v`) The `ordering` type is defined as a `multichoice` type. To differentiate it, the `type` parameter is assigned a value other than its default empty value. Assigning `h` displays the answers horizontally, while `v` displays them vertically. To specify the detailed name, you must also indicate the orientation using `ordering<|>h` for horizontal or `ordering<|>v` for vertical. In the example below, the two questions are the same, only the way the answers are presented changes. ```{r} qc <- qc |> define_question( type = 'h', question = 'Order the result from smallest to largest.', answer = '6/2', a_1 = '6-2', a_2 = '6+2', a_3 = '6*2' ) |> define_question( type = 'v', question = 'Order the result from smallest to largest.', answer = '6/2', a_1 = '6-2', a_2 = '6+2', a_3 = '6*2' ) ``` ## Drag and Drop into Text (`ddwtos`: `''`) and Select Missing Words (`gapselect`: `x`) In questions of these types the objective is to fill in the gaps with the terms indicated. If the variable `type` has the default value (empty string), the values are filled by dragging and dropping. If we define a value `x` in the variable `type`, they are filled by selecting from a list. Gaps in the statement are defined by numbers in double brackets, as shown in the following examples. ```{r} qc <- qc |> define_question( question = 'The symbol for addition is [[1]], the symbol for subtraction is [[2]].', answer = '+', a_1 = '-' ) |> define_question( type = 'x', question = 'The symbol for addition is [[1]], the symbol for subtraction is [[2]].', answer = '+', a_1 = '-' ) ``` We must specify as many answers as there are gaps, in the correct order. Alternatively, a single gap can be defined with multiple selectable answers, where the correct answer will be the first one. ## Matching (`matching`: `''`) If the answers are made up of vectors of pairs of strings, we are in a type `matching` question. Below we show an example. ```{r} qc <- qc |> define_question( question = 'Match each operation with its symbol.', answer = c('Addition', '+'), a_1 = c('Subtraction', '-'), a_2 = c('Multiplication', '*') ) ``` ## Drag and Drop Markers (`ddmarker`: `''`) The `ddmarker` question type allows users to drag markers onto predefined areas of an image. Each marker corresponds to a specific target, enabling visually interactive and location-based assessments. In this case, even if the **category level** specifies that images should be transformed, the image remains unchanged because the definition specifies the position of the image where the cursors must be placed for the answer to be correct. ```{r example2-dd} qc <- qc |> define_question( question = 'Place the cursor over the indicated operation.', image = system.file("extdata", "ops.png", package = "moodef"), image_alt = 'Operations', answer = 'rectangle<|>142,85;554,553<|>Sum' ) ``` # Conclusions The `moodef` package makes it easy to define questions for *Moodle* quizzes. We can define the questions one by one by calling a function or in bulk using a CSV file, *Excel* file or a data frame. We have simplified and generalized the definition so that the types considered are defined with the same parameters. Two definition styles are offered: simple and extended. The extended mode allows defining elements that are considered default in the simple mode. The functionality offered by the package can be used to manually define the questions quickly or to define them automatically or semi-automatically from R. The result of the definition process is an XML file that can be imported directly into the *Moodle* question bank.