Introduction

Before reading this tutorial, you may want to follow the InstallationGuide to install this plugin. For more examples, you can download them from the download area to see how exactly they work. The screenshot of all examples in the XML file can be found here.

Editing interface

As shown in the screenshot, there are number of options in the editing interface. It basically consists of four parts: | Main question | Include the main question text and definition of random variables | |:--------------|:------------------------------------------------------------------| | Subquestion | Include the subquestion text, answer, unit and grading criteria | | Extra options | These are the options that influence all subquestions. | | Check variable instantiation | A simple way to instantiate different random variables. |

The brief explanation of all question options can be found in the QuestionOptions. For the details of the variable system and advance usage, please see Documentation.

Example 1: Simple example

To successfully create a question, you must input at least one answer and fill all input field marked by '*'. They are

• 'Answer mark': A number larger than 0. If this field is not specified, it will be deleted when you save this question.
• 'Answer': A list of number for answer type of numerical value, or a list of string for answer type of algebraic formula.
• 'Grading criteria': A criterion to gauge whether the answer is correct or not. Usually, it is absolute error or relative error.

To create a simple question:

• Type a name in the question name
• In the question text, type: What is 3 + 4?
• In the answer mark, type: 1
• In the answer, type: 7
• In the grading criteria, choose Absolute error == 0
• click save.

Congratulation, you have created your first question !!! The input in the editing interface should look like this:

The resulting question should look like this:

It is a simple question that is the same numerical question type build into the Moodle. If you do not need any features of this formulas question type, you should use the build-in question type as those will be supported over many years.

| Note: Directly copying of examples in this tutorial may not work because of the extra HTML tags during copying. Hence, it is better to type it yourself. | |:---------------------------------------------------------------------------------------------------------------------------------------------------------|

Multiple subquestions

For a single subquestion, it makes almost no difference if the question text is put in the main question or subquestion. However, when there are more than one subquestions, you may want to place the subquestions in some particular location that subquestion placeholder will be useful. If all you want is stacking subquestions at the end one by one, then you do not need to use subquestion placeholder discuss in this section.

A placeholder is used to hold a place for the insertion of other texts. The subquestion placeholder is used to identify the location to insert the subquestion in the 'Main question text'. In the editing interface of subquestion, there is an input box called 'Placeholder' in which you can type the name of the placeholder for this subquestion. The placeholders name here must be prefixed by a '#' symbol such as

```

1

2

3a

3b

A

B

```

To use them in the main question text, you need to enclose it by the curly bracket '{' and '}'.

Example 2: Subquestion placeholder

To see the effect of the subquestion placeholder, enter the #1 in the 'Placeholder' and the following text in the 'Main question text':

What is 1 + 2? {#1} (This text will be displayed below the placeholder)

In the figure below, you can see that the {#1} is replaced by the subquestion text. Since there is no subquestion text, the answer box will be placed at the end of the subquestion. The resulting question should look like this:

Note: * By default, if 'Placeholder' is left empty, the text in the subquestion will simply be appended at the end of the main question. * The bracket { } are required to enclose both placeholders and variables when they are used in the question text. * You may also use other html formatting such as table to display subquestions side by side. * Never add line break and html tag between variables and placeholder, such as red color for {A and green for closing bracket }. They will not be recognized correctly. * Note that you can use any html syntax in the question text. * Do not copy the above examples directly, you have to paste it as plain text.

Multiple answer boxes

Since this question type allows multiple answers in one subquestion, it provides a simple way to specify the location of the answer boxes. By default, all answer boxes will be simply added at the end of a subquestion that it is not useful when there is more than a simple single answer.

To specify the answer boxes for each of them, you can use the following placeholder in the field of 'Subquestion text' of each subquestion:

{_0} {_1} {_2} ... {_u}

The {_0} is the first answer box, the {_1} is the second answer box, etc, and {_u} is the unit box of this subquestion.

Unlike the subquestion placeholder in the main text, the name of the answer box placeholder are fixed. The number of the answer boxes that you can be used is the same as the number of elements you entered in the 'Answer'.

This can be very useful when you want to, say

• Embed the answer box inside the question: For a circle with area of 16 sqaure inch, the length of the circle is {_0} inch.

• Prefix or postfix some text for a question such as unit: What is the speed of the car? speed = {_0} {_u}

• Complex question that has their own format What is the coordinate of point A? x = {_0}, y = {_1} What is the identity matrix? {_0} {_1} {_2} {_3}

Example 3: Appearance of different answer boxes

To see the effect of different arrange of answer box placeholder, enter the above examples as separate subquestions. Note that you can use the navigation above the subquestion to switch between subquestion. The resulting question should be something like this:

Note: * By default, any missing placeholder will be added at the end. If there is nothing in this field, you will have somethings like {_0}{_u} or {_0}{_1}{_u}, ... * If {_0}{_u} are next to each other, the answer and unit box will merge together as one long answer box . * If no unit has been defined for the subquestion, the unit box {_u} will simply be ignored. * If you do not type in any text in the Subquestion answer format, by the above rule, you will get one long input box. * You can also use local variables in the subquestion text similar to the way global variables in the main question text. * You may write the subquestion text here if you like

Variables and random values

Using random variables allows you to assign each student with a different numeric value for the same base question.

There are two ways to define variables, one is to generate random value and the other one is to calculate new variables. Both of them are mainly in the form of variable = expression;

Random variables

To declare a random variable, you simply need to specify the set of elements for it to choose from, e.g.

A = {1,2,3}; B = {2:10, 20, 50, 100}; D = { [1,3], [2,4], [3,5] };

where the elements can be either a number, a string or a list. A list can only be either a list of numbers or a list of strings, enclosed by '[' and ']'.. Its size is always fixed.

In the above case, 'A' will have either a value of 1, 2 or 3, with equal probability, when a student attempt a new quiz.

Global and local variables

In the input field of 'Global variables' and 'Local variables', you can specify any mathematical expression, e.g.

a = 1.11111; b = exp(3); c = A + a + b; d = sin(1.5*pi()) + c; e = round(a, 0); # You can round the number if you desire f = ["zero","one","two","three"][A]; distance = sqrt(a*a + b*b);

Note: 'Global variables' includes all 'Random variables', while 'Local variables' includes all 'Global variables'. Also, each subquestion can only access their own local variables, but not the other subquestion.

Using variables in question text

You only need to write down the declared variable enclosed by '{' and '}' in the question text area.

All global variables can be used in 'Main question text', while all local variables can be used in the 'Subquestion text'.

Using the variables system can simplify the creation of questions with variation and it allows a simpler method to create sensible question with simple answer.

Example 4: Question with variation

• In the 'Random variable', type x1 = {-6,-5,-4}; x2 = {-1,-2,-3}; s = {0:4};

• In the 'Local variable', type: b = -(x1 + x2); c = x1*x2; symbol = pick(s,"t","w","x","z"); # or symbol = ["t","w","x","z"][s], but the pick() will not generate error during quiz creation.

• In the 'Answer', type [x1,x2]

• In the 'Grading criteria', choose "Absolute error == 0", or type _err == 0

• In the 'Subquestion text', type: What is the root of quadratic equation f({symbol}) = {symbol}^2^ + {b} {symbol} + {c} ? (smaller first) {symbol} = {_0} or {symbol} = {_1}

The input in the editing interface should look like this:

The resulting question should look like this:

Answer type

There are four answer types that can be used. You may want to use some or all of them depending on the purpose of the "quiz", the level of the student and the question you want to ask.

The answer types are classified into two groups: either the answer evaluated to a number or evaluated to a algebraic formula. These answer types allow different level of flexibility for the students to input answers.

In the quiz, there is a functionality of format check that check the students input dynamically. Please note that the format check only give a warning sign for the wrong input format from the students. It gives no information about the correctness of the answer. It only means that the result is a valid number or algebraic formula under the given answer type. The main purpose of the format check is to prevent students entering answers in the wrong place, such as typing a number in the unit box, or type an algebraic formula in an answer box of number.

Numerical type answer

There are three numerical types that you can choose: "Number", "Numeric" or "Numerical formula". These are just the names for different input flexibility. Hence, if you find the name difficult to understand, you can change the their name in the language setting, please consult the Moodle documentation for how to change language string.

The "Number" is the most restricted form that students can only input a number. The "Numeric" is a less restricted form than the "Number" that students can input numbers and operators between them such as "+", "/", etc. The "Numerical formula" is a less restricted form than the "Numeric" that students can use various function such as "exp", "sin", etc. Note that all answers input by students must be evaluated to a number, otherwise the answer will be treated as wrong.

Please read the answer type in the documentation for full details. You should provide the appropriate information for your students so that they can fill out the answer correctly.

In the editing interface, these three answer types require a list of number in the 'Answer' input field (or a single number if there is only one number).

Algebraic type answer

The algebraic answer type allows the students inputting algebraic formula in the answer box. To define a algebraic question, you will need to do at least the following in the editing interface:

• Select the "Algebraic formula" in the 'Answer type'
• Define algebraic variables
• Provide an answer in the 'Answer', which must be a list of string
• In the grading criteria, choose "Absolute error". Note that relative error is not defined.

Algebraic variables is just a set of numbers, the syntax is the same as the one used in the 'Random variables', but it is defined in the variable scopes other than the 'Random variables'. The algebraic formula is of this form because the comparison of the algebraic formula using a simple evaluation method: If two algebraic formulas are the same, they should give (almost) zero values at all evaluation point defined in the set of numbers. Please read the grading variable in documentation for more details.

Example 5: Simple algebraic question

As a simple example of algebraic formula, type the following in the subquestion:

• In the answer mark, enter: 2
• In the local variable, enter: x = {1:100}; # An algebraic variable is a set of number. WARNING: Single point like x={1} never work! y = {-10:10:1e-9}; # The set of points must be in the valid domain of the formula below
• In the answer type, choose "Algebraic answer"
• In the answer, enter with the quote: "sqrt(x^2 + y^2)"
• In the grading criteria, choose Absolute error < 1e-10 (See Documentation for how the answers are checked)
• In the question text, enter: What is length of the vector (x,y)?

The input in the editing interface should look like this:

The resulting question should look like this:

Example 6: Algebraic question with variation

The algebraic formula can also use variation in this question, which may be useful for training purpose. As an example, type the following:

• In Random variables, enter: a = {3:10}; b = {3:8};
• In the answer mark, enter: 2
• In the local variable, enter: x = {1:100}; base = a*b; # The reason of defining variable here is to show compute value in answer expo = b-1; # Otherwise, you may type {{{ "a b x^(b-1)" }}} in the answer instead
• In the answer type, choose "Algebraic answer"
• In the answer, enter with the quote: "base x^expo"
• In the grading criteria, choose Absolute error < 1e-10
• In the question text, enter using editor: Differentiate {a}x^{b}:

The input in the editing interface should look like this:

The resulting question should look like this:

Hint

• Becare not to have any html tag between the variables and placeholders!
• You may either specify the questions in the 'Main question text' or in the 'Subquestion answer format'. There is minor formatting though.
• List index is started from 0 !
• The only error during question generation is the index out of range, which cannot be detected by the validation when you save the question. So, you must be very careful about the list indexing, especially the index from random variable.
• If your answer is not a integer, you should never use the condition of absolute error == 0 because there is numerical error in the calculation.
• For the full list of function available, see appendix in the documentation.
• You can put the subquestion placeholder in a table so that the question can be displayed side by side.
• The variable and placeholder in the question text need to be enclosed by '{}' because they are required to identify the location of insertion.