See `this example question `__.
********
Notation
********
Use :math:`j` as the imaginary unit
-----------------------------------
In the :ref:`question-constants` tab of the question editor, turn off ``i``, and define a new constant with :guilabel:`Name` ``j``, :guilabel:`Value` ``sqrt(-1)`` and :guilabel:`LaTeX` ``j``.
*************
Question text
*************
.. _conditional-visibility:
Show one of several blocks of text based on a random variable
------------------------------------------------------------------
Suppose you have a random variable ``a``, which has the value 1,2 or 3, corresponding to three different scenarios.
First, write out the text for each scenario.
.. image:: /_static/how_do_i/conditional_visibility.png
:alt: The conditional visibility button on the toolbar of the content editor
There is a button in the :ref:`rich text editor ` labelled :guilabel:`Conditional visibility`.
This allows you to give an expression (in :ref:`JME` syntax) which dictates whether or not the selected text is shown.
For each scenario, select the corresponding text and click on the :guilabel:`Conditional visibility` button.
Enter ``a=1`` for the first block, ``a=2`` for the second, and ``a=3`` for the third.
When you run the question, only the block of text corresponding to the value of ``a`` is shown.
You can see an example of this technique in the question `Conditional visibility `__.
Display a dollar sign
--------------------------
Because the dollar symbol is used to delimit portions of LaTeX maths, you need to escape dollar signs intended for display by placing a backslash before them -- that is, write ``\$``.
See `this example question `__.
Use random names for people in question statements
--------------------------------------------------
Whenever you have a named person in a question, you should try to randomise the name.
It doesn't really matter what people are called in word problems, but it can have a bad effect on students' perceptions of the world if the plumber's always called Gary and the nurse is always called Julie.
We've written a "random person" extension which makes it easy to randomly pick a name for a person, and use the correct pronouns.
There's `documentation on the extension's GitHub repository `__, and `an example question `__ showing how to use it most effectively.
Randomise the names of variables in an expression
-------------------------------------------------
Suppose you want the student to solve an equation in terms of some variables, but you want to change the names of those variables each time the question is run.
There are a couple of ways of achieving this.
One straightforward method is to use the :jme:func:`expression` command to substitute variable names, randomly generated as strings, into JME expressions as variables.
See `this example question `__.
Use commas or spaces to separate powers of 1,000 in numbers
-----------------------------------------------------------
By default, numbers substituted into question text do not have any separators between powers of 1,000.
When working with real-world data, separating blocks of figures can improve readability.
Use the :jme:func:`formatnumber` function to render numbers following one of the supported :ref:`number-notation` styles.
`This example question `__ shows the :jme:func:`formatnumber` function in use.
Show amounts of money with trailing zeros
-----------------------------------------
Use the :jme:func:`currency` function to ensure that amounts of money are displayed as you'd expect: the figure is either a whole number or given to two decimal places, and the appropriate symbol for the unit of currency is shown before or after the figure.
See `this example question `__.
Pad a number with leading zeros
-------------------------------
Convert the number to a string, then use the :jme:func:`lpad` function to add zeros to the start until it's the desired length.
For example, to pad a number :math:`n` so that it's four digits long, use ``lpad(string(n), 4, '0')``.
See `this example question `__.
*****
LaTeX
*****
Include a randomised LaTeX command
---------------------------------------
If you want to include a LaTeX command in a string variable, remember that backslashes and curly braces in strings must be escaped, unless the string is marked as :jme:func:`safe`.
That means you should type two backslashes where you'd normally type one, and add a backslash before each left or right curly brace, for example ``\\frac\{1\}\{2\}`` produces the LaTeX ``\frac{1}{2}``.
You need to do this because the backslash is used as an escape character in strings so you can include quote marks, which would normally end the string.
(For example, ``"he said \"hello\" to me"``)
If the string is wrapped in :jme:func:`safe`, then you don't need to escape curly braces, but you do still need to double each backslash. For example, ``safe("\\frac{1}{2}")``.
If you substitute a string variable into a mathematical expression using ``\var``, it's normally assumed to represent plain text and displayed using the plain text font.
If your string is really a partial LaTeX expression, you must mark it as such by wrapping it in ``latex()``, e.g. ``\var{latex(mystring)}``.
See `this example question `__.
The majority of the time, substituting raw LaTeX into a question is not the neatest way of achieving what you want.
It's often possible to achieve the desired effect by good use of the :ref:`simplify ` command.
However, if you do need to substitute raw LaTeX code into question text for some reason, the :jme:func:`latex` command is normally what you want.
See `this example question `__, which shows how different methods of substituting a string into question text end up being displayed.
Display a set of tuples
-----------------------
:jme:data:`list` values are normally displayed in LaTeX using square brackets.
To display them as tuples, enclosed with parentheses, you can use ``latex('(' + join(tuple,',') + ')')``.
See `this example question `__.
Show the components of a vector as multiples of basis vectors
-------------------------------------------------------------
Given a vector ``a``, you can render it in LaTeX as a sum of multiples of basis vectors :math:`\boldsymbol{i}`, :math:`\boldsymbol{j}` and :math:`\boldsymbol{k}` as follows::
\simplify{ {a[0]}*v:i + {a[1]}*v:j + {a[2]}*v:k }
See `this example question `__.
Display a surd
--------------
Suppose you have a number :math:`n` which you wish to display as a surd, for example :math:`\sqrt{3}`.
If :math:`n` can be written as a surd, then :math:`n^2` is an integer, so ``\simplify{ sqrt({n^2}) }`` will produce the desired rendering.
When :math:`n` itself is an integer, the :term:`sqrtSquare` simplification rule will rewrite the above expression to just :math:`n`.
`This example question `__ shows how to display surd fractions.
Customise the LaTeX rendering of a particular variable name
-----------------------------------------------------------
In the :ref:`JavaScript API `, there's a dictionary of special cases for rendering variable names at ``Numbas.jme.display.specialNames``.
For example, to render the name ``hbar`` as :math:`\hbar`, in the question preamble set::
Numbas.jme.display.specialNames['hbar'] = ['\\hbar'];
See `this example question `__.
Render plain text inside LaTeX
------------------------------
To render a string of plain text, use the ``\text`` LaTeX macro. For example::
\frac{\text{amount of stuff}}{15 \times(\text{stuff quotient})} = x
produces :math:`\frac{\text{amount of stuff}}{15 \times(\text{stuff quotient})} = x`.
See `this example question `__.
*******
Marking
*******
Mark an equation
----------------
See the section in the mathematical expression part's documentation on :ref:`marking an equation `.
Mark a percentage
-----------------
`This question `__ shows how to use the *quantity with units* custom part type to makr a percentage given by the student.
Check that the student has simplified a polynomial fraction
-----------------------------------------------------------
`This question `__ uses pattern-matching to check that the student's answer is in the form :math:`\frac{x+?}{?}`.
In combination with the normal mathematical expression marking algorithm, this confirms that the student has simplified a fraction of the form :math:`\frac{x+a}{x+b}`.
Check that the student has factorised a quadratic expression
------------------------------------------------------------
`This question `__ uses :ref:`pattern-matching ` to check that the student's answer is the product of two factors.
In combination with the normal mathematical expression marking algorithm, this confirms that the student has factorised the expression.
Limit the number of times a student can submit an answer
--------------------------------------------------------
It's a principle of the design of Numbas that students can submit answers to each question part as many times as they like.
The student might accidentally submit, or change their mind.
In summative assessments, there is the possibility that students could gain an unfair advantage by changing their answer after seeing that it is incorrect.
To avoid this, use the :ref:`exam feedback settings ` so that the student doesn't receive any feedback until the exam is over.
In an :ref:`explore mode ` question, you can use an information-only part to give the student feedback about a part that they have just answered, and give them the opportunity to try again, up to a predefined limit.
See `this example question `__.
Allow "this is impossible" as a response to a prompt
----------------------------------------------------
You can use a :ref:`gap-fill ` part with a :ref:`custom marking algorithm ` to show both an answer input box, and a tick box that the student can use to say that the given task is impossible.
See `this example question `__.
Ask the student to fill in a table of values
--------------------------------------------
The "Spreadsheet" custom part type provided by the spreadsheets extension lets you give the student a table to fill in.
See `this example question `__ which asks the student to fill in a table of values for a quadratic function.
Use data entered by the student when marking later parts
--------------------------------------------------------
This pattern is commonly used when assessing a physical experiment carried out by the student, where you'd like to test how they gather and interpret data.
There are two methods, each with pros and cons.
First, you could use :ref`adaptive marking ` to replace question variables with values entered by the student in an initial "data entry" part.
This works well when you don't have many variables or parts, but because you need to set up the replacements for each part which uses the student's data, it isn't great for longer questions.
See `this example question `__ which asks the student to measure a cuboid box and then calculate its volume.
The other option is to use :ref:`explore mode `, and replace question variables when you move on from the data entry part.
You only need to set up the variable replacements once.
See `this example question `__ which asks the student to measure a cuboid box and then calculate its volume.
Mark gap-fill answers as a set
------------------------------
You might want the student to give several distinct examples from a set of valid answers.
If the student repeats an answer, they should only get credit for the first use.
You can use a :ref:`gap-fill ` part with a :ref:`custom marking algorithm ` to show input boxes for each answer, and then convert the list of interpreted answers to a set and award credit proportional to the size of the intersection of this set with the set of acceptable answers.
Each gap's own marking algorithm determines what feedback icon is shown for that gap.
In most cases where the marking for a gap-fill part depends on all of the gaps together, it doesn't make sense to show a feedback icon next to an individual gap; in these cases, you should turn off :term:`Show score feedback icon?` on each of the gaps.
See `this example question `__ which asks the student to give three different letters of the alphabet.
*******************
Variable generation
*******************
Make sure generated variables satisfy a condition
-------------------------------------------------
A common pattern is that you would like to generate parameters for a system such that the solution variables have "nice" values from a certain set.
For example, you'd like to generate a quadratic equation with random coefficients, and you'd like the solutions to be integers.
In cases like these, you can usually work backwards: pick values for the solutions, and then pick the other values so that those values are satisfied.
In `this example question `__, the student must solve a pair of simultaneous equations in $x$ and $y$.
If picking integer coefficients completely at random for these equations, then the equations might have no solution, or have a non-integer solution.
Instead, in the example, the values of $x$ and $y$ are picked first, and then their coefficients on the left-hand side can be chosen freely.
The constant terms on the right-hand sides of the equations are then entirely determined.
In cases where it's not clear how to work backwards from a good solution, you can use the :ref:`variable testing ` tools to specify a condition that the question's variables must satisfy, and Numbas will re-generate sets of values until the condition is satisfied.
Generate a random list of unique numbers
----------------------------------------
Suppose you want to pick a list of numbers from a given range, but don't want any repeats.
Use the :jme:func:`shuffle` function to put the numbers in random order, then take as many as you need from the front of the resulting list.
The example below picks three distinct numbers between 0 and 10::
shuffle(0..10)[0..3]
See `this example question `__.
Generate a random number excluding some number
----------------------------------------------
Suppose you want to generate a random number from a range, excluding some number in the range. Use the :jme:func:`random` function with the :jme:func:`except` operator. In this example, we generate a random positive or negative number in the range -5 to 5 by excluding 0 from a range::
random(-5..5 except 0)
Assign several variables corresponding to a scenario
----------------------------------------------------
A simple way of randomising a question, particularly when working with real-world data, is to come up with a number of distinct scenarios.
Use the :data:`dictionary` data type to list the values of variables corresponding to each scenario, then pick randomly from a list of these dictionaries.
See `this example question `__.
`This more sophisticated example `__ combines lists of names with JSON data to construct a table of data about people's hobbies.
Load JSON data
--------------
`JSON `__ is a commonly-used format to store data in a way that is easy for both people and computers to read.
The following questions show how to use large JSON data sets in Numbas questions:
* `Items from the Cooper-Hewitt collection `__, with associated images.
* `Data about members of the Scottish Parliament `__.
*****
Maths
*****
Find the factors of a number
---------------------------------
If your number is small enough - as a rule of thumb, at most 5 digits - the easiest way to list all the factors of a number :math:`N` is to check each lower number for divisibility by :math:`N`::
filter(x|n, x, 1..n)
See `this example question `__.
Find the prime factorisation of a number
----------------------------------------
Primality testing is a difficult topic, but if your number is small enough it's easiest just to check against a hard-coded list of prime numbers.
The following produces a list of pairs ``[prime, power]`` for the prime-power factors of the number ``n``::
filter(x[1]>0,x,zip(primes,factorise(n)))
See `this example question `__, which also produces LaTeX code to show the factorisation.
Randomly give two of hypotenuse, opposite, and adjacent side of a triangle
--------------------------------------------------------------------------
`This question `__ shows how to randomly generate a Pythagorean triple - a right-angled triangle with integer-length sides - and randomly show two of the lengths to the student.
The student is asked to calculate the length of the third side.
Take a logarithm to a randomly-chosen base.
-------------------------------------------
The built-in JME functions :jme:func:`ln` and :jme:func:`log` compute logarithms to base :math:`e` and :math:`10`, respectively.
:jme:func:`log` can take a second parameter defining the base.
For example::
log(x,3)
Computes :math:`\log_3(x)`.
`This example question `__ shows how to ask the student to enter a mathematical expression containing a logarithm to a randomly-chosen base, or with an unbound variable as the base.
**********
JavaScript
**********
Define a recursive function
---------------------------
While custom functions can't easily refer to other custom functions defined in the question, they can contain nested function definitions.
You can use this to define a recursive function, and then call it immediately.
See `this example question `__, which computes factorials recursively.
Do something at a certain stage in the question's progress
----------------------------------------------------------
The ``question`` object has a ``signals`` attribute, which you can use in the :ref:`question preamble ` to wait for certain events.
Here are some examples:
* `HTMLAttached `__ - When the question's HTML has been displayed in the page.
* `adviceDisplayed `__ - When the question advice is displayed.