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
- New
- Annotate
- Bar
- Box
- ConfusionMatrix
- Contains
- DataAt
- Draw
- GetArtist
- GetPlotRect
- GetTitle
- GetXAxis
- GetYAxis
- Heatmap
- Hist
- Pan
- Plot
- PrCurve
- Reference
- ResetLimits
- ResetView
- RocCurve
- Scatter
- SetCategories
- SetGrid
- SetLegend
- SetLegendCorner
- SetLogX
- SetLogY
- SetTitle
- SetXLabel
- SetXLim
- SetYLabel
- SetYLim
- Size
- Text
- Zoom
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) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| text | String | the string |
| x | Float | x of the point |
| y | Float | y of the point |
| text_x | Float | x of the text's left end |
| text_y | Float | y 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[]) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | legend entry, or empty |
| ys | Float | one 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[]) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | label under the box |
| values | Float | the 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) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| counts | Int | rows are the actual classes, columns the predicted ones, as Metrics->ConfusionMatrix returns for two classes ([[TN, FP], [FN, TP]]) |
| classes | String | one name per class, or Nil for 0, 1, 2, ... |
| normalize | Bool | true 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) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| px | Float | pixel x |
| py | Float | pixel y |
Return
| Type | Description |
|---|---|
| Bool | true when inside |
DataAt #
The data position under a pixel of the last Draw.
method : public : DataAt(px:Float, py:Float) ~ Float[]Parameters
| Name | Type | Description |
|---|---|---|
| px | Float | pixel x |
| py | Float | pixel y |
Return
| Type | Description |
|---|---|
| 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) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| scene | PlotScene | the scene to add primitives to |
| x | Float | left of the rectangle |
| y | Float | top of the rectangle |
| width | Float | width of the rectangle |
| height | Float | height of the rectangle |
GetArtist #
One thing drawn on the axes.
method : public : GetArtist(index:Int) ~ ArtistParameters
| Name | Type | Description |
|---|---|---|
| index | Int | position from 0, in the order added |
Return
| Type | Description |
|---|---|
| Artist | the artist |
GetPlotRect #
The plot area of the last Draw, in the canvas's pixels.
method : public : GetPlotRect() ~ Float[]Return
| Type | Description |
|---|---|
| Float | [left, top, right, bottom], or Nil before the first Draw |
GetXAxis #
The resolved x axis of the last Draw.
method : public : GetXAxis() ~ PlotAxisReturn
| Type | Description |
|---|---|
| PlotAxis | the axis, or Nil before the first Draw |
GetYAxis #
The resolved y axis of the last Draw.
method : public : GetYAxis() ~ PlotAxisReturn
| Type | Description |
|---|---|
| PlotAxis | the 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[]) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| values | Float | the cells, rows x columns |
| row_names | String | one label per row, or Nil for 0, 1, 2, ... |
| col_names | String | one 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) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| values | Float | the cells, rows x columns |
| row_names | String | one label per row, or Nil for 0, 1, 2, ... |
| col_names | String | one label per column, or Nil for 0, 1, 2, ... |
| annotate | Bool | true to print every value in its cell |
| decimals | Int | decimals 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) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | legend entry, or empty |
| values | Float | the data |
| bins | Int | number 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) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | legend entry, or empty |
| values | Float | the data |
| bins | Int | number of bins, or 0 for Sturges' rule |
| density | Bool | true for density instead of counts |
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) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| dx | Float | pixels the pointer moved right |
| dy | Float | pixels the pointer moved down |
Return
| Type | Description |
|---|---|
| Bool | true when the view changed |
Plot #
Adds a line.
method : public : Plot(name:String, xs:Float[], ys:Float[]) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | legend entry, or empty |
| xs | Float | x values |
| ys | Float | y 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[,]) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | legend entry, or empty |
| curve | Float | [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) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| x1 | Float | start x |
| y1 | Float | start y |
| x2 | Float | end x |
| y2 | Float | end y |
ResetLimits #
Returns both ranges to being derived from the data.
method : public : ResetLimits() ~ NilResetView #
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() ~ NilRocCurve #
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[,]) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | legend entry, or empty |
| curve | Float | [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[]) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | legend entry, or empty |
| xs | Float | x values |
| ys | Float | y 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[]) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| name | String | legend entry, or empty |
| xs | Float | x values |
| ys | Float | y values, one per x |
| colors | Float | one value per point mapped onto the color scale, or Nil for one color |
| sizes | Float | one 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[]) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| names | String | one per category |
SetGrid #
Turns the grid lines on or off (on by default).
method : public : SetGrid(on:Bool) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| on | Bool | true 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) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| on | Bool | true to draw the legend |
SetLegendCorner #
Puts the legend in a corner of the plot area.
method : public : SetLegendCorner(corner:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| corner | String | "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) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| on | Bool | true for a log axis |
SetLogY #
Draws y on a base-10 log scale; every y must then be positive.
method : public : SetLogY(on:Bool) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| on | Bool | true for a log axis |
SetTitle #
Sets the title above the plot.
method : public : SetTitle(title:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| title | String | the text |
SetXLabel #
Sets the x-axis title.
method : public : SetXLabel(text:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| text | String | the label |
SetXLim #
Fixes the x range instead of deriving it from the data.
method : public : SetXLim(min:Float, max:Float) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| min | Float | left end |
| max | Float | right end, above min |
SetYLabel #
Sets the y-axis title.
method : public : SetYLabel(text:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| text | String | the label |
SetYLim #
Fixes the y range instead of deriving it from the data.
method : public : SetYLim(min:Float, max:Float) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| min | Float | bottom |
| max | Float | top, above min |
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) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| x | Float | x of the text's left end |
| y | Float | y of the text's baseline |
| text | String | the 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) ~ BoolParameters
| Name | Type | Description |
|---|---|---|
| px | Float | pixel x of the anchor |
| py | Float | pixel y of the anchor |
| factor | Float | above 1 zooms in, below 1 zooms out |
Return
| Type | Description |
|---|---|
| Bool | true when the view changed |