How do I…

This section largely draws from the “How-tos” project on the numbas.mathcentre.ac.uk editor, where we gather example questions created to demonstrate authoring techniques.

If you’ve got a question that isn’t answered here, try asking on the Numbas users mailing list.

Delivering an exam

Delay showing students scores until a certain date

This is only possible when delivering the exam through the Numbas LTI provider.

First, turn off the feedback options Show current score? and Show answer state?, so students don’t get any feedback while completing the exam.

Then, set Reveal answers to all questions to When entering in review mode.

Finally, after uploading the exam to the Numbas LTI provider, set the Allow students to review attempt from setting to the date and time after which you’d like to allow students to see their scores and feedback.

When a student completes the exam, they won’t see any feedback. Once the chosen time has passed, the student will be able to re-enter the exam in review mode and see their scores and full feedback.

Images, diagrams and other media

Include an image

It’s best practice to attach images to questions so that they’re distributed with the final compiled exam, rather than linking to images stored on a webserver.

When editing a content area, click on the Insert/Edit Image button. You can then either pick an image you’ve already uploaded, or click the Choose file button to upload an image from your computer.

You can resize images and add a title attribute by selecting the image in the content area and clicking on the Insert/Edit Image button.

Embed a video

Upload your video to somewhere like YouTube or Vimeo. Including videos in downloaded exam packages is a terrible idea, so we discourage that.

Click the Embed image/video button, and paste in the URL of your video.

Include an interactive diagram

There are a few ways of including an interactive diagram in a Numbas question.

JSXGraph is a JavaScript library for creating interactive diagramss. There is an extension which allows you to create JSXGraph diagrams using JME or JavaScript code.

GeoGebra applets are much easier to create and use, but are loaded from geogebra.org so the student must have internet access in order to use any questions containing GeoGebra applets. For more information, see the page on the GeoGebra extension.

Eukleides is a Numbas extension designed to easily produce accessible, dynamic diagrams. Interactivity is limited to dragging points, which can be used to construct the rest of the diagram.

Substitute random variables into an image

Text inside an SVG image follows the same variable substitution rules as prose text: expressions enclosed in curly braces are evaluated and replaced with the resulting string.

Pay attention to the text alignment options when designing your image: randomly generated values are usually not the same width as the expressions they replace.

See the question Volume of a swimming pool for an example of an SVG image with variables substituted into text.

Display a random line in a GeoGebra applet

A neat way to create a random line is to randomly pick the positions of two points on the line.

Create two points in your GeoGebra worksheet, and a line between those two points. Set the positions of the points in the parameters to the geogebra_applet() function.

See this example question.

Use student input in a JSXGraph diagram

This question shows how to construct a line corresponding to an equation given by the student.

Appearance and display

Change how the question looks

You can use the formatting tools in the question editor to style your text. However, if you repeat the same styles over and over, or want to change aspects of the layout such as space between elements or decoration, you’ll need to write some CSS.

CSS is a language for defining how things should look - there’s a good introduction at Khan Academy. In the Numbas editor, you can add CSS rules to a question in the Preamble section.

The following questions demonstrate how to use CSS to change the look of a Numbas question:

Set an attribute on an HTML element based on the value of a question variable

Use the Source code view in a content area to edit its HTML code. You can set the value of an attribute on an HTML tag to the result of a JME expression by prefixing the attribute’s name with eval-. Variables are substituted into the attribute’s value using curly braces.

For example, this tag will have its class attribute set to the value of the variable classes:

<div eval-class="{classes}">

See this example question.

Question text

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.

The conditional visibility button on the toolbar of the content editor

There is a button in the rich text editor labelled Conditional visibility. This allows you to give an expression (in JME syntax) which dictates whether or not the selected text is shown. For each scenario, select the corresponding text and click on the 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 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 formatnumber() function to render numbers following one of the supported Number notation styles.

This example question shows the formatnumber() function in use.

Show amounts of money with trailing zeros

Use the 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 lpad() function to add zeros to the start until it’s the desired length.

For example, to pad a number \(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 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 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 simplify command.

However, if you do need to substitute raw LaTeX code into question text for some reason, the 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

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 \(\boldsymbol{i}\), \(\boldsymbol{j}\) and \(\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 \(n\) which you wish to display as a surd, for example \(\sqrt{3}\).

If \(n\) can be written as a surd, then \(n^2\) is an integer, so \simplify{ sqrt({n^2}) } will produce the desired rendering.

When \(n\) itself is an integer, the sqrtSquare simplification rule will rewrite the above expression to just \(n\).

This example question shows how to display surd fractions.

Customise the LaTeX rendering of a particular variable name

In the 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 \(\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 \(\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 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 \(\frac{x+?}{?}\). In combination with the normal mathematical expression marking algorithm, this confirms that the student has simplified a fraction of the form \(\frac{x+a}{x+b}\).

Check that the student has factorised a quadratic expression

This question uses 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 exam feedback settings so that the student doesn’t receive any feedback until the exam is over.

In an 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 gap-fill part with a 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.

Variable generation

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 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.

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 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:

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 \(N\) is to check each lower number for divisibility by \(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 ln() and log() compute logarithms to base \(e\) and \(10\), respectively. log() can take a second parameter defining the base. For example:

log(x,3)

Computes \(\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 functoin 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 question preamble to wait for certain events.

Here are some examples: