Note: You are currently viewing documentation for Moodle 3.3. Up-to-date documentation for the latest stable version of Moodle is probably available here: Formulas question documentation.

Formulas question documentation: Difference between revisions

From MoodleDocs
(Redirected page to Formulas question type)
 
(34 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Introduction ==
#REDIRECT [[Formulas_question_type]]
This question type aims to be generic so that various type of non-trivial questions can be created easily. The variable system and answer boxes allows great flexibility to define question and simplify the job to make complex question. In this documentation, various parts of this question type are described, including the formatting, variables, grading, unit system and trial mark sequence.
 
For a brief explanation of the question options in editing interface, see QuestionOptions<sup>(add link)</sup>. For creating simple question, see Tutorial<sup>(add link)</sup>.
 
== Question text placeholder ==
You can insert the subquestion text and answer boxes at a given location using placeholders. To substitute a placeholder by its the contents, the placeholder name must be enclosed by <span style="font-family: monospace;color:#f98012;font-size:113%;">{</span> and <span style="font-family: monospace;color:#f98012;font-size:113%;">}</span> in the text.
 
=== Placeholder of the subquestions ===
 
This kind of placeholder allows you to insert subquestion in a particular location in the main question.
 
The placeholders name is a string starting with <span style="font-family: monospace;color:#f98012;font-size:113%;">#</span> symbol and followed by any characters of <span style="font-family: monospace;color:#f98012;font-size:113%;">[A-Z a-z 0-9]</span>, such as <span style="font-family: monospace;color:#f98012;font-size:113%;">#1</span>, <span style="font-family: monospace;color:#f98012;font-size:113%;">#2a</span>, <span style="font-family: monospace;color:#f98012;font-size:113%;">#2b</span> and <span style="font-family: monospace;color:#f98012;font-size:113%;">#A</span>. Subquestion can be labelled by a placeholder name in the options called 'Placeholder'. Note that, by default, the subquestion will be appended at the end if no placeholder is specified. To use them in the main question text, type <span style="font-family: monospace;color:#f98012;font-size:113%;">{#1}</span> instead of <span style="font-family: monospace;color:#f98012;font-size:113%;">#1</span>, for example:
 
<pre style="color:#f98012;font-size:113%;">The following is the question 1, part a and part b: {#1a} {#1b}
The following is the question 2: {#2}</pre>
 
===Placeholder of answer boxes===
 
This kind of placeholder provides a simple way to arrange the answer boxes in the subquestion text.
 
It is particularly useful when the subquestion requires more than one answer. This flexibility allows you to place the answer boxes in the form of matrix, coordinates, embedding into the question text or any other way you want.
 
The placeholder names are <span style="font-family: monospace;color:#f98012;font-size:113%;">_0</span> for the first answer box, <span style="font-family: monospace;color:#f98012;font-size:113%;">_1</span> for the second answer box, etc., and <span style="font-family: monospace;color:#f98012;font-size:113%;">_u</span> for the unit box. The number of the answer boxes that can be used is the same as the number of elements entered in the Answer. For example, with two answers for one subquestion, the following can be used
 
<pre style="color:#f98012;font-size:113%;">What are the (x,y) coordinates of the particle? Answer : ({_0}, {_1}) {_u}</pre>
 
The box <span style="font-family: monospace;color:#f98012;font-size:113%;">{_0}</span> is corresponds to the special variable <span style="font-family: monospace;color:#f98012;font-size:113%;">_0</span> in the Grading variables. By default, all missing placeholder are automatically appended at the end. That is <span style="font-family: monospace;color:#f98012;font-size:113%;">{_0}{_u}</span> for one answer subquestion, and <span style="font-family: monospace;color:#f98012;font-size:113%;">{_0}{_1}{_u}</span> for two answers subquestion.
 
An exception for the substitution is that there will only be one longer answer box when <span style="font-family: monospace;color:#f98012;font-size:113%;">{_0}{_u}</span> are immediately neighbour to each other, and there is only one numerical answer and unit. In this case, the answer and unit box will merge together as one long answer box, and the students are expected to type them in the same box.
 
----
 
==Variable system==
 
 
Variables can be used to substitute question texts, define the answers and specify grading criteria. One of the main purpose of the variable system is to simplify the task to make variation of the questions. Since the variables are generated at the beginning of a quiz, the quiz will be halted if any errors occur. Hence, in order to minimize the error, the system is designed to only have deterministic variables type, constant length lists and no branching.
 
===Scope of variable===
 
There are four types of variables, each with a different scope of application, defined at four locations:
 
{| class="nicetable"
|-
! Variable type and location
! Scope of application
|-
| Random variables
| The place to define the variation of variables for the whole questions.
|-
|-
| Global variables
| The scope includes all (instantiated) random variables.
|-
| Local variables
| The scope includes all global variables. Note: Each subquestion has its own local variables scope.
|-
| Grading variables
| The scope includes all local variables, plus special variables (e.g. _0, _1) depending on students' response.
|-
|}
 
These variables can be used at the following location as follows:
 
{| class="nicetable"
|-
! Location
! Variables that can be used
|-
| Main text
| All global variables can be used in the substitution
|-
| Subquestion text
| All local variables for the subquestion can be used in the substitution
|-
| Answer
| All local variables for the subquestion can be used in the expression
|-
| Grading criteria
| All grading variables can be used in the expression
|-
|}
 
===Variable name===
 
A variable name is a string of alphanumeric characters <span style="font-family: monospace;color:#f98012;font-size:113%;">[a-z A-Z 0-9 _]</span> (Numbers and underscore cannot be located at the start of string). Examples of valid variable are:
 
<pre style="color:#f98012;font-size:113%;">x y1 z_1 foo_bar</pre>
 
===Variable type===
 
Each variable will be assigned with a type implicitly. A type is either number, string or algebraic variable, plus list of numbers or list of strings. List is defined as the elements enclosed by <span style="font-family: monospace;color:#f98012;font-size:113%;">[</span> and <span style="font-family: monospace;color:#f98012;font-size:113%;">]</span>. An element in list can be referred using syntax <span style="font-family: monospace;color:#f98012;font-size:113%;">A[b]</span>, for example, <span style="font-family: monospace;color:#f98012;font-size:113%;">[4,5,6][0]</span> gives the first number, that is, <span style="font-family: monospace;color:#f98012;font-size:113%;">4</span>. These types are listed below:
 
{| class="nicetable"
|-
| '''Number'''
| A number, for example: <span style="font-family: monospace;color:#f98012;font-size:113%;">1.2e-3</span>
|-
| '''String'''
| Characters enclosed by two double quotes, for example: <span style="font-family: monospace;color:#f98012;font-size:113%;">"Hello"</span>
|-
| '''List of numbers'''
| Numbers enclosed by <span style="font-family: monospace;color:#f98012;font-size:113%;">[</span> and <span style="font-family: monospace;color:#f98012;font-size:113%;">]</span>, for example: <span style="font-family: monospace;color:#f98012;font-size:113%;">[4,5,6]</span>, The equivalent short hand syntax is <span style="font-family: monospace;color:#f98012;font-size:113%;">[4:7]</span> or <span style="font-family: monospace;color:#f98012;font-size:113%;">[4:7:1]</span>
|-
| '''List of strings'''
| Strings enclosed by <span style="font-family: monospace;color:#f98012;font-size:113%;">[</span> and <span style="font-family: monospace;color:#f98012;font-size:113%;">]</span>, for example: <span style="font-family: monospace;color:#f98012;font-size:113%;">["A", "B", "C"]</span>
|-
| '''Algebraic variable'''
| A set of numbers (see syntax) defined in the non-random variable scope, for example: <span style="font-family: monospace;color:#f98012;font-size:113%;">{1:100}</span>
|-
|}
 
===Random variables===
 
During the quiz creation, each random variables will be assigned by ''one'' value defined by the expression. Hence, each student can have their own set of value for the quiz attempt.
 
A random variable has different syntax than other variables and it only be defined in the field '''Random variables'''. These variables can be defined by assigning a set of elements or a shuffling of a list. The probability of selecting each element is equal so that each element has equal chance to be drawn. There are three main types of expressions:
 
====Set of elements====
A set of elements is elements enclosed by <span style="font-family: monospace;color:#f98012;font-size:113%;">{</span> and <span style="font-family: monospace;color:#f98012;font-size:113%;">}</span>. The element can be either a number, a string, a number list, or a string list. For example, the variable below is a set of list of numbers, and the probability for element <span style="font-family: monospace;color:#f98012;font-size:113%;">[2,3]</span> is 1/5:
 
<pre style="color:#f98012;font-size:113%;">F = { [0,0], [1,1], [2,4], [3,9], [4,16] };</pre>
 
====Set of numbers====
A set of numbers is numbers enclosed by <span style="font-family: monospace;color:#f98012;font-size:113%;">{</span> and <span style="font-family: monospace;color:#f98012;font-size:113%;">}</span>. You can also specified a range in the format of <span style="font-family: monospace;color:#f98012;font-size:113%;">start:stop:interval</span>, where the numbers that satisty ( <span style="font-family: monospace;color:#f98012;font-size:113%;">start</span> + ''n'' × <span style="font-family: monospace;color:#f98012;font-size:113%;">interval</span> ) < <span style="font-family: monospace;color:#f98012;font-size:113%;">stop</span>, ''n'' = 0,1,2,3... will be added. If the interval is not specified, value <span style="font-family: monospace;color:#f98012;font-size:113%;">1</span> will be used. Note that the last end point is ''not'' included by definition, but may be include for non-integer due to numerical errors. The set of numbers defined below demonstrate different range syntax. Also, the probability of the elements in each set are 1/8, 1/10 and 1/20 respectively.
 
<pre style="color:#f98012;font-size:113%;">A = {1,2,3,4,5,6,7,8}; B = {0:1:0.1}; C = {1:10, 10:100:10, 100, 200};</pre>
 
====Shuffled list====
A list can be passed to the shuffle function. For the example below, the instantiated variable <span style="font-family: monospace;color:#f98012;font-size:113%;">S</span> with take one of the permutation of the input list, say <span style="font-family: monospace;color:#f98012;font-size:113%;">[4,3,2,5]</span> or <span style="font-family: monospace;color:#f98012;font-size:113%;">[2,5,4,2]</span>. The probability of each list is therefore 1/4! = 1/24.
 
<pre style="color:#f98012;font-size:113%;">S = shuffle([2,3,4,5]);</pre>
 
===Variable assignments===
 
Variable assignments allow you to define and manipulate variables. It can be defined in the option field of global variables, local variables and grading variables.
 
====Expression====
It is any combination of numbers and/or variables together with operators and functions listed in the Appendix. Typically, it is just a simple mathematical formula evaluated to a number. The variables used in the expression must be defined before.
 
====Assignment====
It is used to assign the evaluated result of an expression to a variable, in the form of <span style="font-family: monospace;color:#f98012;font-size:113%;">name = expression ;</span>.
 
====For loop====
It allows a simple iteration in the form of <span style="font-family: monospace;color:#f98012;font-size:113%;">for(element:list)</span>. All elements element in the list will be iterated.
 
====Examples====
{| class="nicetable"
|-
! Assignment
! Comment
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">a = 1; # Comment</span>
| Text after <span style="font-family: monospace;color:#f98012;font-size:113%;">#</span> and up to the end of line is treated as comment
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">b = exp(3.333);</span>
|
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">d = round(b, 1);</span>
| <span style="font-family: monospace;color:#f98012;font-size:113%;">round</span> rounds the number to the desired decimal place
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">e = 1 + sin(2) + pow(a,2);</span>
|
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">A = [1,2,3];</span>
|
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">x = A[0];</span>
|
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">y = A[a];</span>
|
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">z = A[2];</span>
|
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">w = A[0] + A[1] + A[2];</span>
|
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">m = max(x, y);</span>
|
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">distance = sqrt(x*x + y*y + z*z);</span>
|
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">theta = atan2(y, x);</span>
|
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">smaller = x < y;</span>
| <span style="font-family: monospace;color:#f98012;font-size:113%;">smaller</span> is equal to <span style="font-family: monospace;color:#f98012;font-size:113%;">1</span>:<br><span style="font-family: monospace;color:#f98012;font-size:113%;">x = A[0] = 1</span>,      <span style="font-family: monospace;color:#f98012;font-size:113%;">y = A[a] = A[1] = 2</span>,      hence <span style="font-family: monospace;color:#f98012;font-size:113%;">(1 < 2) = 1 (true).</span>
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">con = (x < y) + (y < z);</span>
| <span style="font-family: monospace;color:#f98012;font-size:113%;">con</span> is equal to 2
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">B = fill(3,0);</span>
| <span style="font-family: monospace;color:#f98012;font-size:113%;">B</span> is equal to <span style="font-family: monospace;color:#f98012;font-size:113%;">[0,0,0]</span>
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">C = map("sqrt",fill(3,16));</span>
| Square root of <span style="font-family: monospace;color:#f98012;font-size:113%;">[16,16,16]</span>, so <span style="font-family: monospace;color:#f98012;font-size:113%;">C</span> is <span style="font-family: monospace;color:#f98012;font-size:113%;">[4,4,4]</span>
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">s = 0;<br> for (i:A) s = s + i;</span>
| <span style="font-family: monospace;color:#f98012;font-size:113%;">s</span> is equal ot <span style="font-family: monospace;color:#f98012;font-size:113%;">6</span> after the loop <span style="font-family: monospace;color:#f98012;font-size:113%;">for (i:[1:3])</span><sup>(i:[0:3]) in Google Code Archive</sup>
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">B[i] = sum(map("+",A,fill(3,i)));</span>
| <span style="font-family: monospace;color:#f98012;font-size:113%;">B</span> is equal to <span style="font-family: monospace;color:#f98012;font-size:113%;">[6,9,12]</span>
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">p = pick(a+9,"","A","B");</span>
| <span style="font-family: monospace;color:#f98012;font-size:113%;">pick()</span> always choose the first element if the index is out of range
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">u = {-3,-2,-1,1:100};</span><br><span style="font-family: monospace;color:#f98012;font-size:113%;">v = {-100:100:1};</span>
| <span style="font-family: monospace;color:#f98012;font-size:113%;">u</span> and <span style="font-family: monospace;color:#f98012;font-size:113%;">v</span> define algebraic variables, the numbers are the points for evaluation
|-
|}
 
'''Notes'''
* '''Index out of range''' cannot be checked by the validation during question save, so you have to check it yourself. Otherwise, the quiz initialization for some students may fail. Use <span style="font-family: monospace;color:#f98012;font-size:113%;">pick()</span> as a safe variant if applicable.
* Logical true is treated as <span style="font-family: monospace;color:#f98012;font-size:113%;">1</span> and false is <span style="font-family: monospace;color:#f98012;font-size:113%;">0</span>, so the variable con above gets the value 2.
* There is no branching, however, you may use the ternary operator <span style="font-family: monospace;color:#f98012;font-size:113%;">(condition) ? (true) : (false)</span> for number or the <span style="font-family: monospace;color:#f98012;font-size:113%;">pick()</span> function for general case.
* The available functions are listed in the Appendix. There are many additional functions for the numeric list operation, and few for the list of string.
 
===Using variable in text===
 
It is simple to substitute the variables in the text, you only need to enclose the corresponding variables by <span style="font-family: monospace;color:#f98012;font-size:113%;">{</span> and <span style="font-family: monospace;color:#f98012;font-size:113%;">}</span>.
 
Each text field have a scope of variables. All variables <span style="font-family: monospace;color:#f98012;font-size:113%;">x</span> of either number or string in the scope of the text can be used to replace the corresponding placeholder <span style="font-family: monospace;color:#f98012;font-size:113%;">{x}</span> in the text.
 
It is also possible to evaluate an expression directly in the text by adding an equal sign at the beginning of the bracket such as <span style="font-family: monospace;color:#f98012;font-size:113%;">{=x/1000}</span>. It is easier to use if the named variables are not required. However, no error check will be done unless the question is being instantiated in the quiz. An example is the rescaling of meter to kilometer below:
 
<pre style="color:#f98012;font-size:113%;">What is the speed of the rocket if it travels with distance {=x/1000} km in {t} s?</pre>
 
----
 
==Answer and grading criteria==
 
For a subquestion to become valid, you must give a mark and define an answer for it. Also, grading critera must be specified in order to check the correctness of a student's answer.
 
===Answer type===
 
This question support four answer types. Each type will accept a particular set of numbers, operators, functions and possibly algebraic variables. Depending on the quiz purpose, some or all of these answer types may be used.
 
{| class="nicetable"
|-
! Answer type
! Description
|-
| Number
| You can type in the standard scientific E notation such as: 3.14, 6.626e-34.
|-
| Numeric
| You can type in numbers and arithmetic operations + - * / ^ and ( ) and the constant pi such as: 5+1/2, 2^9, 3pi.
|-
| Numerical formula
| You can type in everything of numeric plus a set of single variable functions sin(), cos(), tan(), asin(), acos(), atan(), exp(), log10(), ln(), sqrt(), abs(), ceil(), floor() such as: sin(pi/12), 10 ln(2)
|-
| Algebraic formula
| You can type in every numerical formula and any algebraic variables.
|}
 
'''Notes'''
* Students will also need to know these rules in order to input the answer correctly.
* The possible input have the following relation: Number ⊂ Numeric ⊂ Numerical formula ⊂ Algebraic formula.
* The answer will need a list of string for Algebraic formula and list of number for other answer type.
* "^" in the algebraic formula means "power", not "exclusive or".
* Juxtaposition between numbers or symbols mean multiplication.
* The format check in the quiz interface will show warning sign when the format is wrong for the answer type. It does not give any information about the correct answer.
* All symbols will be treated as algebraic variable in the answer type of algebraic formula. Hence, you may need to hint students what symbols should be used in the question.
 
===Model answer===
 
Depending on the answer type, the answer options will accept either expression that evaluated to a list of numbers or strings (for algebraic formula). The size of the list will determine how many input boxes for this subquestion. If only one answer is required, you can specify a number or string instead of the one element list.
 
For the answer type of Number, Numeric and Numerical formula, a list of numbers (or a single number) is required. Suppose the variables are defined, each line below is a possible answer:
 
<pre style="color:#f98012;font-size:113%;">pi()
[sin(pi()/2), cos(pi()/2)]
[ans[0], ans[1], ans[2]]
ans
</pre>
 
 
For the answer type of Algebraic formula, a list of strings (or a single string) is required. Suppose the variables are defined, each line below is a possible answer.
 
<pre style="color:#f98012;font-size:113%;">"exp(-a x)"
"a x^2 + b y^2"
["a sin(x)", "b cos(x)"]
</pre>
 
Note that all algebraic variables must be defined in order to be usable in the answer. For the answers above to work, you will need to define the following variables:
 
<pre style="color:#f98012;font-size:113%;">a = 2;
b = 3;
x = {-100:100:1};
y = {1:100:1};
</pre>
 
===Grading criteria===
 
A grading criteria is required to determine the correctness of the student's answer. It requires an expression evaluated to a number in which 0 means false and 1 means true. Typically, it is either the relative error or absolute error with a tolerance level.
 
For the question with only one answer, the absolute error is simply the different between the model answer and student's answer. Hence if the true answer is <span style="font-family: monospace;color:#f98012;font-size:113%;">3.2</span> and the student's answer is <span style="font-family: monospace;color:#f98012;font-size:113%;">3.1</span>, then absolute error is | 3.2 − 3.1 | = 0.1. You may want to limit the range of correct response, say, 0.05. In this case, you should select absolute error <span style="font-family: monospace;color:#f98012;font-size:113%;">< 0.05</span>. Similarly, the relative error is defined by the absolute error divided by the absolute value of model answer. See the <span style="font-family: monospace;color:#f98012;font-size:113%;">_err</span> and <span style="font-family: monospace;color:#f98012;font-size:113%;">_relerr</span> in grading variables below for more details.
 
===Grading variables===
 
For the typical case, the absolute error and relative error can satisfy most grading criteria. However, sometimes there is a need for other grading criteria.
 
In the scope of Grading variables, it contains all local variables and student's answer. With the answer from student, you can then define your own grading criteria. The information related to the student's answer and model answer is stored in the set of special variables started by underscore as shown below:
 
{| class="nicetable"
|-
! Variable name
! Description
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">_0, _1, _2, ...</span>
| The student's answer of each "coordinates". The first "coordinate" is <span style="font-family: monospace;color:#f98012;font-size:113%;">_0</span> corresponding to the answer box <span style="font-family: monospace;color:#f98012;font-size:113%;">{_0}</span> in the subquestion, etc.
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">_a</span>
| It is a list of model answer, which is the answer defined in the answer field.
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">_r</span>
| It is a list of students' response with the same size as <span style="font-family: monospace;color:#f98012;font-size:113%;">_a</span>. The 0-th element is the same as <span style="font-family: monospace;color:#f98012;font-size:113%;">_0</span>, etc.
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">_d</span>
| It is a list of the different between each elements, given by <span style="font-family: monospace;color:#f98012;font-size:113%;">_d = diff(_a,_r);</span>. See Appendix for the details of the function.
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">_err</span>
| Absolute error, using Euclidean norm <span style="font-family: monospace;color:#f98012;font-size:113%;">❘a-r❘</span>, i.e. <span style="font-family: monospace;color:#f98012;font-size:113%;">_err = sqrt(sum(map("*",_d,_d)));</span>
|-
| <span style="font-family: monospace;color:#f98012;font-size:113%;">_relerr</span>
| Relative error, divide the absolute error by the norm of model answer <span style="font-family: monospace;color:#f98012;font-size:113%;">❘a-r❘/❘a❘</span>, i.e. <span style="font-family: monospace;color:#f98012;font-size:113%;">_relerr = _err/sqrt(sum(map("*",_a,_a)));</span>
|}

Latest revision as of 23:17, 21 January 2018