Skip to content
Classroom

Graph & Table Macros

Generating plots and tables from question code.

drawgraph, arraytable and matrixtable do not exist

Earlier versions of this page documented all three. None appears anywhere in the engine. The real macros are showplot and showasciisvg for graphs, and showarrays, showdataarray, horizshowarrays and showrecttable for tables.

Each of these returns markup, which you interpolate into qtext or solution.

Graphs

showplot($funcs, $xmin, $xmax, $ymin, $ymax, $labels, $grid, $width, $height)

Plots one or more functions. Everything after $funcs is optional and defaults to -5, 5, -5, 5, 1, 1, 200, 200 — a ±5 window with labels and grid on, 200×200 pixels.

$plot = showplot("x^2 - 4")
$plot = replacealttext($plot, "Graph of an upward-opening parabola with vertex (0, -4), crossing the x-axis at -2 and 2.")

Pass an array to draw several curves on the same axes:

$plot = showplot(array("x^2", "2*x + 1"), -10, 10, -5, 20)
$plot = replacealttext($plot, "Graph of the parabola y = x^2 and the line y = 2x + 1 for x from -10 to 10; they cross near x = -0.41 and x = 2.41.")

Then place it in the question text:

<p>The graph of `f(x) = x^2 - 4`:</p>
$plot

What a showplot entry can hold

Each curve is one string of fields separated by commas. Only the first field is required. To skip a field, leave it empty: "x^2,red,-2,2,,closed" skips the start marker and puts a closed dot at the right end, (2, 4).

"function,color,xmin,xmax,startmarker,endmarker,strokewidth,strokedash"
Field What it does
function the curve, as an expression in x. A leading y = is ignored.
color the line colour, such as red, blue or green. Black if empty.
xmin, xmax draw the curve only between these two x-values. The whole window if empty.
startmarker, endmarker closed or open puts a dot at that end of the curve, and arrow puts an arrowhead there.
strokewidth the line width. 1 if empty.
strokedash dash draws a dashed line. Anything else is solid.

A piecewise function, with the open and closed ends a student has to read:

$plot = showplot(array("x+2,blue,-4,1,closed,open", "-x+3,blue,1,4,closed,closed"), -5, 5, -5, 5)
$plot = replacealttext($plot, "Graph of a piecewise function. The line y = x + 2 runs from a closed dot at (-4, -2) to an open dot at (1, 3). The line y = -x + 3 runs from a closed dot at (1, 2) to a closed dot at (4, -1).")

A dot or arrowhead goes at the very end of the curve as drawn. With xmin and xmax empty, the curve runs slightly past the left and right edges of the picture, so a dot there is cut off. If the curve leaves the window through the top or bottom before it ends, the marker lands outside the picture. Whenever you use a marker, give xmin and xmax at which the curve is still inside the window.

Some entries draw something other than a curve:

Entry Draws
"dot,x,y,closed,color,label,labelpos" one point, open if the fourth field is open. The label is optional and sits above the point unless labelpos says below, left, right, or a combination such as aboveright.
"text,x,y,words,color,pos,angle" text, centred on (x, y) unless pos says otherwise
"x=3,color,ymin,ymax" a vertical line, from ymin to ymax if they are given
"x=y^2,color,ymin,ymax" a sideways curve, with x as an expression in y, for y from ymin to ymax. Give both: if they are empty, y runs over the window's x-range, not its y-range.
"<f(x)", "<=f(x)", ">f(x)", ">=f(x)" the region below (<) or above (>) the curve, shaded in a see-through version of the colour; "<x^2" on its own shades blue. With < or > the boundary is dashed.
"x<3", "x>=3" … the region left or right of a vertical line, shaded red or green if that is the colour, and blue otherwise. With < or > the line is dashed.
"[f(t),g(t)],color,tmin,tmax" a parametric curve in t, for t from tmin to tmax (the window's x-range if they are empty)

Give a region shaded above or below a curve nothing after its colour. xmin and xmax shorten its boundary but not its shading, so the picture no longer matches the inequality, and an empty colour field followed by other fields shades the region grey.

Inside a label or text, write a comma as \, so it is not read as the start of the next field. Never put an apostrophe (') or a double quote (") in a text entry: either one stops the whole graph from being drawn. For a derivative, type the prime character ′, as in "text,1,1,f′(x)". If you pass the plot to replacealttext, also write > in a text entry as &gt;: a bare > there stops the whole graph from being drawn too. In a replacealttext description, and in labels and text when you keep the automatic description, put a space after <: y<x hides the rest of the description from students who use text alternatives.

Add replacealttext to describe a drawn graph

A drawn showplot graph has no description of its own. showplot does write one automatically, and an entry starting alt: replaces it, but either one reaches only students who have chosen text alternatives instead of graphs. A student using a screen reader with graphs drawn hears a description only if you add one with replacealttext. Once you call it, students using text alternatives get only its text as well: the automatic description, with its table of values, and any alt: entry are dropped, so write it for both groups. Students whose Graph Display is image-based get a picture whose alternative text is always just "Graphs", whatever you set.

showasciisvg($script, $width, $height, $alt)

Full control, for anything showplot cannot express — you write the ASCIIsvg drawing script directly.

$fig = showasciisvg("axes(1,1,1,1); plot('x^2'); dot([2,4]);", 300, 300,
                    "A parabola with the point (2, 4) marked.")

Always pass $alt

$alt is the alternative text a screen reader announces. Without it the figure is invisible to those students, and an assessment that depends on reading a graph becomes unanswerable. replacealttext($plot, $alttext) sets it on a plot built some other way.

Building up a plot

Macro Adds
addlabel($plot, $x, $y, $lbl, $color, $loc, $angle, $size) a label at graph coordinates (it takes no alt text; describe labels with replacealttext)
addlabelabs($plot, $x, $y, $lbl, …) a label at pixel coordinates
adddrawcommand($plot, $cmd) a raw ASCIIsvg command
addplotborder($plot, $left, $bottom, $right, $top) padding around the plot
addfractionaxislabels($plot, $step, $axis) fraction-formatted tick labels
addimageborder($img, $w, $m) a border around an <img> (no effect on a plot)
changeimagesize($img, $w, $h) resize an <img>. It does not work on a plot; set showplot's $width/$height instead
invertplot($plot) reflect across y = x — not available on this platform's engine build
mergeplots($plota, …) combine plots into one figure
replacealttext($plot, $alttext) set the alternative text of a showplot plot. Call it last: addlabel, addlabelabs, adddrawcommand, addfractionaxislabels and mergeplots no longer work on a plot that already has alt text (addplotborder still does). On showasciisvg output the original $alt stays in place, so pass $alt there instead

Plotting data rather than a formula

Macro Draws
arraystodoteqns($x, $y, $color) a scatter of closed dots from paired arrays, as showplot entries ($color defaults to blue)
arraystodots($x, $y) not a drawing: "x,y" strings for a drawing question's $answers. Passed to showplot, they plot as horizontal lines
connectthedots($xarray, $yarray, $color, $thick, $startdot, $enddot) a polyline through the points 
$x = consecutive(1, 6)
$y = rands(2, 20, 6)
$scatter = showplot(arraystodoteqns($x, $y), 0, 7, 0, 22)
$scatter = replacealttext($scatter, "Scatter plot of six points: (1, $y[0]), (2, $y[1]), (3, $y[2]), (4, $y[3]), (5, $y[4]), (6, $y[5]).")

Tables

showarrays($header1, $array1, $header2, $array2, …, $options)

The main table macro. Arguments alternate header, array — one pair per column — and it needs at least two arguments.

$x = consecutive(-3, 3)
$y = calconarray($x, "x^2")
$table = showarrays("x", $x, "f(x)", $y, array("caption" => "Values of f(x) = x^2"))

An optional trailing array sets caption, align (one letter per column, c, l or r; a string shorter than the number of columns repeats its first letter for every column) and tablealign ("center" centres the table itself):

$table = showarrays("x", $x, "f(x)", $y,
                    array("caption" => "Values of f", "align" => "c"))

Give every table a caption

caption is what a screen reader announces to introduce the table. A table of unexplained numbers is the most common accessibility defect in generated questions.

horizshowarrays(…)

The same header/array pairs, laid out with each array as a row rather than a column. It takes no trailing options array (one passed anyway becomes an extra row headed "Array"), so it has no caption. Introduce the table in the question text instead. Use it for short wide data — a single input/output pair reads better horizontally.

showdataarray($array, $n, $options)

A single array wrapped into $n columns. For a plain list of values that does not need headers.

$table = showdataarray($data, 4)

showrecttable($matrix, $clabel, $rlabel, $align)

A rectangular table from a two-dimensional array, with column and row labels — the macro for matrices and two-way tables. $align is a single letter, c, l or r, applied to every cell. There is no options array and no caption, so introduce the table in the question text. If the label counts do not match the array's dimensions, it returns an error message instead of a table.

$table = showrecttable($m, array("A", "B"), array("Row 1", "Row 2"))

Images

textonimage() composites text onto an image. addimageborder and changeimagesize adjust one. All of them return markup to interpolate, as above.

See Also