Formulas question documentation

Introduction

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^{(add link)}. For creating simple question, see Tutorial^{(add link)}.

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 { and } 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 # symbol and followed by any characters of [A-Z a-z 0-9], such as #1, #2a, #2b and #A. 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 {#1} instead of #1, for example:

The following is the question 1, part a and part b: {#1a} {#1b}
The following is the question 2: {#2}

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 _0 for the first answer box, _1 for the second answer box, etc., and _u 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

What are the (x,y) coordinates of the particle? Answer : ({_0}, {_1}) {_u}

The box {_0} is corresponds to the special variable _0 in the Grading variables. By default, all missing placeholder are automatically appended at the end. That is {_0}{_u} for one answer subquestion, and {_0}{_1}{_u} for two answers subquestion.

An exception for the substitution is that there will only be one longer answer box when {_0}{_u} 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:

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:

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 [a-z A-Z 0-9 _] (Numbers and underscore cannot be located at the start of string). Examples of valid variable are:

x y1 z_1 foo_bar

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 [ and ]. An element in list can be referred using syntax A[b], for example, [4,5,6][0] gives the first number, that is, 4. These types are listed below:

Number	A number, for example: 1.2e-3
String	Characters enclosed by two double quotes, for example: "Hello"
List of numbers	Numbers enclosed by [ and ], for example: [4,5,6], The equivalent short hand syntax is [4:7] or [4:7:1]
List of strings	Strings enclosed by [ and ], for example: ["A", "B", "C"]
Algebraic variable	A set of numbers (see syntax) defined in the non-random variable scope, for example: {1:100}

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 { and }. 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 [2,3] is 1/5:

F = { [0,0], [1,1], [2,4], [3,9], [4,16] };

Set of numbers

A set of numbers is numbers enclosed by { and }. You can also specified a range in the format of start:stop:interval, where the numbers that satisty ( start + n × interval ) < stop, n = 0,1,2,3... will be added. If the interval is not specified, value 1 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.

A = {1,2,3,4,5,6,7,8}; B = {0:1:0.1}; C = {1:10, 10:100:10, 100, 200};

Shuffled list

A list can be passed to the shuffle function. For the example below, the instantiated variable S with take one of the permutation of the input list, say [4,3,2,5] or [2,5,4,2]. The probability of each list is therefore 1/4! = 1/24.

S = shuffle([2,3,4,5]);

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 name = expression ;.

For loop

It allows a simple iteration in the form of for(element:list). All elements element in the list will be iterated.

Examples

Assignment	Comment
a = 1; # Comment	Text after # and up to the end of line is treated as comment
b = exp(3.333);
d = round(b, 1);	round rounds the number to the desired decimal place
e = 1 + sin(2) + pow(a,2);
A = [1,2,3];
x = A[0];
y = A[a];
z = A[2];
w = A[0] + A[1] + A[2];
m = max(x, y);
distance = sqrt(x*x + y*y + z*z);
theta = atan2(y, x);
smaller = x < y;	smaller is equal to 1: x = A[0] = 1,      y = A[a] = A[1] = 2,      hence (1 < 2) = 1 (true).
con = (x < y) + (y < z);	con is equal to 2
B = fill(3,0);	B is equal to [0,0,0]
C = map("sqrt",fill(3,16));	Square root of [16,16,16], so C is [4,4,4]
s = 0; for (i:A) s = s + i;	s is equal ot 6 after the loop for (i:[1:3])(i:[0:3]) in Google Code Archive
B[i] = sum(map("+",A,fill(3,i)));	B is equal to [6,9,12]
p = pick(a+9,"","A","B");	pick() always choose the first element if the index is out of range
u = {-3,-2,-1,1:100}; v = {-100:100:1};	u and v 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 pick() as a safe variant if applicable.
• Logical true is treated as 1 and false is 0, so the variable con above gets the value 2.
• There is no branching, however, you may use the ternary operator (condition) ? (true) : (false) for number or the pick() 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 { and }.

Each text field have a scope of variables. All variables x of either number or string in the scope of the text can be used to replace the corresponding placeholder {x} 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 {=x/1000}. 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:

What is the speed of the rocket if it travels with distance {=x/1000} km in {t} s?

---

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.

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:

pi()
[sin(pi()/2), cos(pi()/2)]
[ans[0], ans[1], ans[2]]
ans

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.

"exp(-a x)"
"a x^2 + b y^2"
["a sin(x)", "b cos(x)"]

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:

a = 2;
b = 3;
x = {-100:100:1};
y = {1:100:1};

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 3.2 and the student's answer is 3.1, 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 < 0.05. Similarly, the relative error is defined by the absolute error divided by the absolute value of model answer. See the _err and _relerr in grading variables below for more details.