#plot API reference

Data plotting to SVG: turn numbers into a self-contained <svg> chart string you can write to a .svg file or drop into HTML. A unified chart renders one or more Series (line / points / both / area, solid or dashed, with optional error bars and marker shapes) with a legend; line / scatter / bar / bars / histogram are focused wrappers. bars groups or stacks multiple series and supports negative (diverging) values. Charts support log scales, a date axis, fonts, configurable margins, positioned legends, reference lines, data labels, and native <title> hover tooltips. save writes the SVG to a file. Pure Jennifer over math and time / fs / strings / lists / convert; both binaries; the visual companion to the stats / ml numeric stack.

Import with import "plot.j" as plot;. See the plot guide for prose and examples.

#Functions

#plot.bar(labels as list of string, values as list of float, opts as Options)

A single-series vertical bar chart: one bar per labelled category, from zero (negative values diverge below). A convenience over bars.

Parameters

• labels {list of string} - the category labels
• values {list of float} - the bar heights
• opts {Options} - chart options

Returns {string} - a complete SVG document

Throws

• {Error} - kind "plot" when labels / values are empty or unequal length

#plot.bars(labels as list of string, data as list of Series, opts as Options)

A multi-series bar chart: one group of bars per labelled category. Each Series contributes its ys (one value per category) as a colour; series are drawn side by side ("grouped", opts.barMode) or on top of each other ("stacked"). Values may be negative (bars diverge from a zero baseline). A named series is listed in the legend.

Parameters

• labels {list of string} - the category labels, drawn under each group
• data {list of Series} - the series (each ys the same length as labels)
• opts {Options} - chart options

Returns {string} - a complete SVG document

Throws

• {Error} - kind "plot" when labels / data are empty or a series length differs

#plot.chart(data as list of Series, opts as Options)

Render one or more Series on shared axes, with a legend for named series. Each series draws per its mark (line / points / both / area), with optional dashing, marker shapes, and error bars. The domain spans every series, its error bars, and any reference-line value on a linear axis.

Parameters

• data {list of Series} - the series to plot (each non-empty, xs / ys equal length)
• opts {Options} - chart options

Returns {string} - a complete SVG document

Throws

• {Error} - kind "plot" when data is empty, a series is malformed, or a log axis sees a non-positive value

#plot.defaults()

Sensible defaults: a 640x400 canvas, no title / labels, blue data on white, a sans-serif 11px base font, gridlines and a top-right legend on, linear scales, grouped bars, tooltips on, no data labels, no reference lines.

Returns {Options} - the default options

#plot.floats(xs as list of int)

Convert a list of int to a list of float, since the chart functions take float data and an int list does not match a float parameter.

Parameters

• xs {list of int} - the integers

Returns {list of float} - the same values as floats

#plot.histogram(data as list of float, bins as int, opts as Options)

A histogram of data into bins equal-width buckets over the data range, drawing the bucket counts as adjacent bars.

Parameters

• data {list of float} - the samples
• bins {int} - the number of buckets (>= 1)
• opts {Options} - chart options

Returns {string} - a complete SVG document

Throws

• {Error} - kind "plot" when data is empty or bins < 1

#plot.hline(value as float, label as string)

A horizontal reference line at y = value (a threshold / target).

Parameters

• value {float} - the y value
• label {string} - an optional caption ("" = none)

Returns {RefLine} - the reference line

#plot.line(xs as list of float, ys as list of float, opts as Options)

A line chart of a single series. A convenience over chart.

Parameters

• xs {list of float} - the x coordinates
• ys {list of float} - the y coordinates
• opts {Options} - chart options

Returns {string} - a complete SVG document

Throws

• {Error} - kind "plot" when xs / ys are empty or unequal length

#plot.points(name as string, xs as list of float, ys as list of float)

A points (scatter) series (mark "points").

Parameters

• name {string} - the legend label
• xs {list of float} - the x coordinates
• ys {list of float} - the y coordinates

Returns {Series} - the series

#plot.save(svg as string, path as string)

Write an SVG chart string to a file, returning the path. A convenience over fs.writeString so plot.save(plot.line(...), "chart.svg") reads in one line. (Jennifer values have no methods, so it is plot.save($svg, path), not $svg.save(path).)

Parameters

• svg {string} - the SVG document (from any chart function)
• path {string} - the destination file path

Returns {string} - the path written

#plot.scatter(xs as list of float, ys as list of float, opts as Options)

A scatter plot of a single series. A convenience over chart.

Parameters

• xs {list of float} - the x coordinates
• ys {list of float} - the y coordinates
• opts {Options} - chart options

Returns {string} - a complete SVG document

Throws

• {Error} - kind "plot" when xs / ys are empty or unequal length

#plot.series(name as string, xs as list of float, ys as list of float)

A line series (mark "line"). Set .mark / .color / .dash / .yErr / .shape on the result.

Parameters

• name {string} - the legend label
• xs {list of float} - the x coordinates
• ys {list of float} - the y coordinates

Returns {Series} - the series

#plot.vline(value as float, label as string)

A vertical reference line at x = value (a marker in time / along x).

Parameters

• value {float} - the x value
• label {string} - an optional caption ("" = none)

Returns {RefLine} - the reference line

#Structs

#plot.Options

Chart options: canvas size, captions, colours, fonts, margins, axis modes, legend placement, data labels, tooltips, and reference lines. Copy defaults() and set the fields you want.

#plot.RefLine

A reference line drawn across the plot at a constant value on one axis - a threshold, target, or marker.

#plot.Series

One plotted data series. For line / scatter / area xs and ys are the coordinates; for bars only ys (the per-category values) is used. yErr, when the same length as ys, draws symmetric error bars (linear y only); shape picks the scatter marker.