Plotter Library Reference

The plotter library in EasyBite provides a stateful, high-level API for creating a wide variety of charts—line plots, histograms, bar and pie charts, and more—by leveraging the [Plotters] crate for rendering and minifb for on-screen display. Scripts record drawing commands against a thread-local Figure, then invoke showplot, showimage, or savefig to produce the final output. All functions return Result types, so errors (such as missing figures or mismatched array lengths) are surfaced cleanly instead of crashing the runtime.

---

Function	Parameters	Description
FIGURE & AXES
figure	([width, height]) (Number, optional)	Create a new canvas. Defaults to 800×600 if omitted.
title	([text]) (String)	Set the figure’s title.
xlabel	([text]) (String)	Set the x-axis label.
ylabel	([text]) (String)	Set the y-axis label.
legend	([show]) (Bool, optional)	Toggle legend display. Defaults to true if no arg.
grid	([show]) (Bool, optional)	Toggle grid lines. Defaults to true if no arg.
clear	([])	Clear the current figure (drops all settings & commands).
subplots	([nrows, ncols]) (Number, both required)	Divide canvas into an nrows×ncols grid of subplots.
BASIC PLOTTING
plot	([x: Array, y: Array, color?: String])	Draw a line through points (x[i], y[i]). Default color "blue".
scatter	([x: Array, y: Array, color?: String])	Draw markers at (x[i], y[i]). Default color "red".
histogram	([data: Array, bins?: Number, color?: String])	Plot a histogram of data into bins buckets. Defaults: 10 bins, color "green".
bar	([categories: Array, values: Array, color?: String])	Draw vertical bars at each category. Default color "blue".
pie	([labels: Array, data: Array, colors?: Array])	Draw a pie chart. If colors omitted, cycles ["red","blue",…].
ADVANCED & SPECIALIZED
step	([x: Array, y: Array, color?: String])	Draw a step plot. Default color "blue".
area	([x: Array, y: Array, color?: String])	Draw a filled area under the (x, y) curve. Default "blue".
boxplot	([data: Array<Array>, labels?: Array, color?: String])	Draw one or more box-and-whisker plots. Default "purple".
violin	([data: Array<Array>, labels?: Array, color?: String])	Draw violin distributions. Default "blue".
errorbar	([x: Array, y: Array, yerr: Array, color?: String])	Draw error bars at (x[i], y[i]) with ±yerr[i]. Default "black".
heatmap	([data: Array<Array>, color?: String])	Render a heatmap of the matrix. Default "blue".
contour	([data: Array<Array>, x_range: Tuple, y_range: Tuple, color: String])	Draw contour lines. Requires explicit color.
quiver	([x: Array, y: Array, u: Array, v: Array, color?: String])	Draw arrows at (x[i],y[i]) with components (u[i],v[i]). Default "black".
stem	([x: Array, y: Array, marker_color?: String, line_color?: String])	Draw stems with markers. Defaults: marker "black", line "blue".
bubble	([x: Array, y: Array, sizes: Array, color?: String])	Draw circles at (x[i], y[i]) sized by sizes[i]. Default "blue".
stackedbar	([categories: Array, values: Array<Array>, colors?: Array])	Draw stacked bars. If colors omitted, cycles defaults.
polar	([theta: Array, r: Array, color?: String])	Draw in polar coordinates. Default "blue".
candlestick	([times: Array, open: Array, high: Array, low: Array, close: Array, color_up?: String, color_down?: String])	Draw candlestick chart. Default up "green", down "red".
radar	([labels: Array, data: Array<Array>, color?: String])	Draw radar/spider chart. Default "blue".
waterfall	([x_labels: Array, values: Array, color?: String])	Draw waterfall chart. Default "blue".
OUTPUT & RENDER
savefig	([path]) (String)	Save current figure as PNG.
showplot	([])	Render figure in an interactive window (blocks until closed).
showimage	([path]) (String)	Load & display an image file in a window.

---

Detailed Examples

1. Simple Line Plot

import plotter

plotter.figure()                              // 800×600 canvas
plotter.plot([ [0,1,2], [3,1,4], "red" ])      // red line
plotter.title([ "Monthly Sales" ])            
plotter.xlabel([ "Month" ])                   
plotter.ylabel([ "Sales ($k)" ])              
plotter.legend([])                            // show legend
plotter.showplot()                            

Output:
Interactive window showing a red line through (0,3), (1,1), (2,4), with title and axis labels.

---

2. Histogram with Custom Bins

import plotter

set data to [1,2,2,3,5,5,6,7,8,9]
plotter.figure([600, 400])                    // 600×400 canvas
plotter.histogram([ data, 5, "purple" ])      // 5-bin purple histogram
plotter.grid([])                              // show grid lines
plotter.savefig([ "hist.png" ])               // save to file

Output:
File hist.png: a 600×400 purple histogram with 5 bins and grid lines.

---

3. Pie Chart

import plotter

set labels to [ "A", "B", "C", "D" ]
set values to [ 10, 20, 30, 40 ]
plotter.figure()                              // new canvas
plotter.pie([ labels, values ])               // default colors cycle
plotter.showplot()                            

Output:
A pie chart window with four slices sized 10%, 20%, 30%, 40% in default colors.

---

4. Box Plot of Two Distributions

import plotter

plotter.figure()
plotter.boxplot([
  [[1,2,3,4], [2,3,5,7]],    // two series
  ["A","B"],                 // labels
  "orange"                   // color
])
plotter.showplot()

Output:
Two side-by-side orange boxplots labeled A and B.

---

5. Heatmap with Default Color

import plotter

set mat to [
  [1,3,2],
  [4,6,5],
  [7,9,8]
]
plotter.figure([300,300])
plotter.heatmap([ mat ])
plotter.savefig([ "heatmap.png" ])

Output:
A 300×300 PNG heatmap of mat in blue scale.

---

6. Contour Lines over a Grid

import plotter, math

declare z[10][10]

for i from 0 to 9
    for j from 0 to 9
        z[i][j] to math.sin(i / 2) * math.cos(j / 3)
    end for
end for

plotter.figure()
plotter.contour([ z, [0,9], [0,9], "black" ])
plotter.showplot()

Output:
Black contour lines of the 2D sine-cosine surface.

---

7. Financial Candlestick Chart

import plotter

let dates = ["2025-04-01","2025-04-02","2025-04-03"]
let open  = [100, 102, 101]
let high  = [105, 103, 102]
let low   = [ 98, 100,  99]
let close = [103, 100, 101]

plotter.figure()
plotter.candlestick([ dates, open, high, low, close ])  // green up, red down
plotter.showplot()

Output:
A candlestick chart window showing three trading days with default green/red coloring.

---

8. Error Bar Plot

import plotter

set x    to [0, 1, 2, 3]
set y    to [2, 3, 1, 4]
set yerr to [0.5, 0.3, 0.2, 0.4]

plotter.figure()
plotter.errorbar([ x, y, yerr, "magenta" ])
plotter.showplot()

9. Quiver Field

import plotter

set x to [0, 1, 2]
set y to [0, 1, 0]
set u to [1, 0, -1]
set v to [0, 1, 0]

plotter.figure()
plotter.quiver([ x, y, u, v ])
plotter.showplot()

10. Area Chart

import plotter

set x to [0, 1, 2, 3]
set y to [1, 4, 2, 5]

plotter.figure()
plotter.area([ x, y, "teal" ])
plotter.showplot()

11. Step Plot

import plotter

set x to [0, 1, 2, 3]
set y to [2, 1, 3, 2]

plotter.figure()
plotter.step([ x, y ])
plotter.showplot()

12. Violin Plot

import plotter

set data2d to [
  [1,2,3,2,1],
  [2,3,4,3,2]
]

plotter.figure()
plotter.violin([ data2d, ["A","B"], "cyan" ])
plotter.showplot()

13. Stem Plot

import plotter

set x to [0, 1, 2]
set y to [1, 3, 2]

plotter.figure()
plotter.stem([ x, y, "red", "black" ])
plotter.showplot()

14. Bubble Chart

import plotter

set x     to [1, 2, 3]
set y     to [2, 4, 1]
set sizes to [10, 40, 20]

plotter.figure()
plotter.bubble([ x, y, sizes, "orange" ])
plotter.showplot()

15. Stacked Bar Chart

import plotter

set cats   to ["Q1","Q2","Q3"]
set vals2d to [
  [3, 5, 2],
  [2, 1, 4]
]

plotter.figure()
plotter.stackedbar([ cats, vals2d ])
plotter.showplot()

16. Polar Plot

import plotter

set theta to [0, 1.57, 3.14]
set r     to [1,   2,     1]

plotter.figure()
plotter.polar([ theta, r, "purple" ])
plotter.showplot()

17. Radar Chart

import plotter

set labels to ["Speed","Power","Agility"]
set stats2d to [
  [5, 7, 6]
]

plotter.figure()
plotter.radar([ labels, stats2d, "green" ])
plotter.showplot()

18. Waterfall Chart

import plotter

set steps  to ["Start","Gain","Loss","End"]
set values to [100, 30, -20, 110]

plotter.figure()
plotter.waterfall([ steps, values, "brown" ])
plotter.showplot()