v2026.11.2
All Bundles
Bundle

A matplotlib-like plotting library: scatter, histogram, line and bar charts, subplots, as standalone SVG. A Figure holds one or more Axes; drawing the figure builds a PlotScene, an ordered list of pixel-space drawing primitives (lines, polylines, polygons, rects, circles, text), and a backend turns the scene into output. The SVG backend writes SVG 1.1 with no script and no external font, one decimal for every coordinate, so the same data gives the same bytes on every platform. Compile with -lib plot,gen_collect; it needs nothing else and draws without a display. Design: docs/PLOT_DESIGN.md. Examples: docs/AI.md, "Plotting".

Axes

A plot area with axes, a title, ticks, a legend and the things drawn in it.

Example

ax->Scatter("class A", xs, ys);
ax->Scatter("by score", xs, ys, score, Nil->As(Float[]));  # color by a third column
ax->Hist("residuals", errors, 20);
ax->SetLogX(true);

Operations

Annotate #

Points at a position with a text and a line: a circle at (x, y), the text at (text_x, text_y).

method : public : Annotate(text:String, x:Float, y:Float, text_x:Float, text_y:Float) ~ Nil

Parameters

NameTypeDescription
textStringthe string
xFloatx of the point
yFloaty of the point
text_xFloatx of the text's left end
text_yFloaty of the text's baseline

Bar #

Adds a bar series over the categories: one bar per category, grouped with the other bar series. SetCategories must have been called.

method : public : Bar(name:String, ys:Float[]) ~ Nil

Parameters

NameTypeDescription
nameStringlegend entry, or empty
ysFloatone height per category

Box #

Adds a box plot box: the median, the quartiles, whiskers to the furthest values within 1.5 times the interquartile range, and the values beyond as circles. The quartiles are linear interpolation between ranks (numpy's default), so the first quartile of 1 .. 4 is 1.75, not 2. Each call adds one box, left to right, labelled under the axis.

method : public : Box(name:String, values:Float[]) ~ Nil

Parameters

NameTypeDescription
nameStringlabel under the box
valuesFloatthe data

ConfusionMatrix #

Adds a confusion matrix: a heatmap whose cells are annotated, with the actual class down the side and the predicted class along the bottom.

method : public : ConfusionMatrix(counts:Int[,], classes:String[], normalize:Bool) ~ Nil

Parameters

NameTypeDescription
countsIntrows are the actual classes, columns the predicted ones, as Metrics->ConfusionMatrix returns for two classes ([[TN, FP], [FN, TP]])
classesStringone name per class, or Nil for 0, 1, 2, ...
normalizeBooltrue to show each row as fractions of its total

Contains #

Whether a pixel is inside the plot area of the last Draw.

method : public : Contains(px:Float, py:Float) ~ Bool

Parameters

NameTypeDescription
pxFloatpixel x
pyFloatpixel y

Return

TypeDescription
Booltrue when inside

DataAt #

The data position under a pixel of the last Draw.

method : public : DataAt(px:Float, py:Float) ~ Float[]

Parameters

NameTypeDescription
pxFloatpixel x
pyFloatpixel y

Return

TypeDescription
Float[x, y] in data space (category indexes on a categorical axis), or Nil before the first Draw

Draw #

Draws the axes into a scene, inside a rectangle of the canvas.

method : public : Draw(scene:PlotScene, x:Float, y:Float, width:Float, height:Float) ~ Nil

Parameters

NameTypeDescription
scenePlotScenethe scene to add primitives to
xFloatleft of the rectangle
yFloattop of the rectangle
widthFloatwidth of the rectangle
heightFloatheight of the rectangle

GetArtist #

One thing drawn on the axes.

method : public : GetArtist(index:Int) ~ Artist

Parameters

NameTypeDescription
indexIntposition from 0, in the order added

Return

TypeDescription
Artistthe artist

GetPlotRect #

The plot area of the last Draw, in the canvas's pixels.

method : public : GetPlotRect() ~ Float[]

Return

TypeDescription
Float[left, top, right, bottom], or Nil before the first Draw

GetTitle #

The title.

method : public : GetTitle() ~ String

Return

TypeDescription
Stringthe text

GetXAxis #

The resolved x axis of the last Draw.

method : public : GetXAxis() ~ PlotAxis

Return

TypeDescription
PlotAxisthe axis, or Nil before the first Draw

GetYAxis #

The resolved y axis of the last Draw.

method : public : GetYAxis() ~ PlotAxis

Return

TypeDescription
PlotAxisthe axis, or Nil before the first Draw

Heatmap #

Adds a heatmap: one colored cell per value, a color bar on the right, and the row and column labels on the axes. Row 0 is at the top. A heatmap owns its axes: it cannot be combined with other plots.

method : public : Heatmap(values:Float[,], row_names:String[], col_names:String[]) ~ Nil

Parameters

NameTypeDescription
valuesFloatthe cells, rows x columns
row_namesStringone label per row, or Nil for 0, 1, 2, ...
col_namesStringone label per column, or Nil for 0, 1, 2, ...

Heatmap #

Adds a heatmap, optionally printing each value in its cell.

method : public : Heatmap(values:Float[,], row_names:String[], col_names:String[], annotate:Bool, decimals:Int) ~ Nil

Parameters

NameTypeDescription
valuesFloatthe cells, rows x columns
row_namesStringone label per row, or Nil for 0, 1, 2, ...
col_namesStringone label per column, or Nil for 0, 1, 2, ...
annotateBooltrue to print every value in its cell
decimalsIntdecimals in the printed values, 0 to 6

Hist #

Adds a histogram with equal-width bins over the range of the data.

method : public : Hist(name:String, values:Float[], bins:Int) ~ Nil

Parameters

NameTypeDescription
nameStringlegend entry, or empty
valuesFloatthe data
binsIntnumber of bins, or 0 for Sturges' rule

Hist #

Adds a histogram, optionally normalised so its area is 1.

method : public : Hist(name:String, values:Float[], bins:Int, density:Bool) ~ Nil

Parameters

NameTypeDescription
nameStringlegend entry, or empty
valuesFloatthe data
binsIntnumber of bins, or 0 for Sturges' rule
densityBooltrue for density instead of counts

New # constructor

Constructor; Figure creates its axes.

New()

Pan #

Moves the view by a number of pixels, as a drag does: the data follows the pointer. Categorical axes and heatmaps do not pan.

method : public : Pan(dx:Float, dy:Float) ~ Bool

Parameters

NameTypeDescription
dxFloatpixels the pointer moved right
dyFloatpixels the pointer moved down

Return

TypeDescription
Booltrue when the view changed

Plot #

Adds a line.

method : public : Plot(name:String, xs:Float[], ys:Float[]) ~ Nil

Parameters

NameTypeDescription
nameStringlegend entry, or empty
xsFloatx values
ysFloaty values, one per x

PrCurve #

Adds a precision-recall curve with its average precision in the legend and both axes 0 to 1.

method : public : PrCurve(name:String, curve:Float[,]) ~ Nil

Parameters

NameTypeDescription
nameStringlegend entry, or empty
curveFloat[threshold, recall, precision] rows, as Metrics->PrCurve returns

Reference #

Adds a dashed reference line between two points in data coordinates, such as the diagonal of a ROC plot or a threshold. It is not in the legend.

method : public : Reference(x1:Float, y1:Float, x2:Float, y2:Float) ~ Nil

Parameters

NameTypeDescription
x1Floatstart x
y1Floatstart y
x2Floatend x
y2Floatend y

ResetLimits #

Returns both ranges to being derived from the data.

method : public : ResetLimits() ~ Nil

ResetView #

Returns the view to what the figure chose: the limits given to SetXLim and SetYLim (a ROC plot's -0.02 .. 1.02, say), or the range of the data where none were given. It is what a window's R key does after zooming and panning; ResetLimits instead forgets the limits altogether.

method : public : ResetView() ~ Nil

RocCurve #

Adds a ROC curve with the chance diagonal, both axes 0 to 1, and the area under the curve (trapezoid rule) in the legend.

method : public : RocCurve(name:String, curve:Float[,]) ~ Nil

Parameters

NameTypeDescription
nameStringlegend entry, or empty
curveFloat[threshold, false-positive rate, true-positive rate] rows, as Metrics->RocCurve returns

Scatter #

Adds a scatter plot of one color.

method : public : Scatter(name:String, xs:Float[], ys:Float[]) ~ Nil

Parameters

NameTypeDescription
nameStringlegend entry, or empty
xsFloatx values
ysFloaty values, one per x

Scatter #

Adds a scatter plot whose points can be colored and sized by further columns. A color column adds a color bar on the right of the plot.

method : public : Scatter(name:String, xs:Float[], ys:Float[], colors:Float[], sizes:Float[]) ~ Nil

Parameters

NameTypeDescription
nameStringlegend entry, or empty
xsFloatx values
ysFloaty values, one per x
colorsFloatone value per point mapped onto the color scale, or Nil for one color
sizesFloatone value per point mapped onto marker area, or Nil for one size

SetCategories #

Makes x categorical: ticks are these names at positions 0, 1, 2, ..., and bar series are grouped by them.

method : public : SetCategories(names:String[]) ~ Nil

Parameters

NameTypeDescription
namesStringone per category

SetGrid #

Turns the grid lines on or off (on by default).

method : public : SetGrid(on:Bool) ~ Nil

Parameters

NameTypeDescription
onBooltrue to draw the grid

SetLegend #

Turns the legend on or off (on by default; it lists the named things only).

method : public : SetLegend(on:Bool) ~ Nil

Parameters

NameTypeDescription
onBooltrue to draw the legend

SetLegendCorner #

Puts the legend in a corner of the plot area.

method : public : SetLegendCorner(corner:String) ~ Nil

Parameters

NameTypeDescription
cornerString"upper right" (the default), "upper left", "lower right" or "lower left"

SetLogX #

Draws x on a base-10 log scale; every x must then be positive.

method : public : SetLogX(on:Bool) ~ Nil

Parameters

NameTypeDescription
onBooltrue for a log axis

SetLogY #

Draws y on a base-10 log scale; every y must then be positive.

method : public : SetLogY(on:Bool) ~ Nil

Parameters

NameTypeDescription
onBooltrue for a log axis

SetTitle #

Sets the title above the plot.

method : public : SetTitle(title:String) ~ Nil

Parameters

NameTypeDescription
titleStringthe text

SetXLabel #

Sets the x-axis title.

method : public : SetXLabel(text:String) ~ Nil

Parameters

NameTypeDescription
textStringthe label

SetXLim #

Fixes the x range instead of deriving it from the data.

method : public : SetXLim(min:Float, max:Float) ~ Nil

Parameters

NameTypeDescription
minFloatleft end
maxFloatright end, above min

SetYLabel #

Sets the y-axis title.

method : public : SetYLabel(text:String) ~ Nil

Parameters

NameTypeDescription
textStringthe label

SetYLim #

Fixes the y range instead of deriving it from the data.

method : public : SetYLim(min:Float, max:Float) ~ Nil

Parameters

NameTypeDescription
minFloatbottom
maxFloattop, above min

Size #

Things drawn so far.

method : public : Size() ~ Int

Return

TypeDescription
Intthe count

Text #

Writes text at a position in data coordinates; text outside the plot area is not drawn.

method : public : Text(x:Float, y:Float, text:String) ~ Nil

Parameters

NameTypeDescription
xFloatx of the text's left end
yFloaty of the text's baseline
textStringthe string

Zoom #

Zooms both axes about a pixel of the last Draw, as a mouse wheel does: the data under the pixel stays under it. Categorical axes and heatmaps do not zoom.

method : public : Zoom(px:Float, py:Float, factor:Float) ~ Bool

Parameters

NameTypeDescription
pxFloatpixel x of the anchor
pyFloatpixel y of the anchor
factorFloatabove 1 zooms in, below 1 zooms out

Return

TypeDescription
Booltrue when the view changed