SVG Plotting

The jQuery SVG plotting extension (jquery.svgplot.js) provides support for plotting numeric functions with SVG.
Since 1.3.0.

The SVG plotting entry point is within the SVG wrapper object as svg.plot, which allows you to configure the plot and render it using SVG. Many functions return the plot object so that further calls may be chained together.

svg.plot.noDraw().title('Functions').
	addFunction('sine', Math.sin, 'blue', 3).
	addFunction('cosine', Math.cos, [-Math.PI, Math.PI], 20, 'red', 3).
	addFunction('decaying', decay, 'green', 3).
	areaFormat('ivory', 'gray').
	gridlines({stroke: 'gray', strokeDashArray: '2,2'}, 'gray').
	status(setStatus);
svg.plot.xAxis.scale(-1, 3.5).ticks(1, 0.2);
svg.plot.yAxis.scale(-1.5, 1.5).ticks(1, 0.2);
svg.plot.legend.settings({fill: 'lightgoldenrodyellow', stroke: 'gray'});

svg.plot.noDraw().
	legend.show(true).area(legendAreas[plotLegend]).end().
	xAxis.scale(plotZooms[plotZoom][0], plotZooms[plotZoom][1]).end().
	yAxis.scale(plotZooms[plotZoom][2], plotZooms[plotZoom][3]).end().
	chartArea(chartAreas[plotLegend]).equalXY(plotEqual).redraw();

addFunction | area | container | equalXY | format | functions | gridlines | noDraw | redraw | status | title

SignatureReturnsComments
addFunction(name, fn, range, points, stroke, strokeWidth, settings) SVGPlot object Add a function to be shown on the plot. The details are encapsulated in a SVGPlotFunction object.

name (string, optional) is the name of this function.

fn (function) is the function to be plotted. It takes a single numeric value as a parameter and returns a numeric value.

range (number[2], optional) is the minimum and maximum x-values to be plotted. If not specified it defaults to the full range of the x-axis.

points (number, optional) is the number of points within the range to plot. More points produce a smoother curve, but generate a larger SVG document. If not specified it defaults to 100.

stroke (string, optional) is the colour of the plotted lines. If not specified it defaults to black.

strokeWidth (number, optional) is the width of the plotted lines.

settings (object, optional) is additional settings (SVG attributes) for the plotted values.

svg.plot.addFunction('sine', Math.sin,
	[-Math.PI, Math.PI], 50, 'green', 3);
area(left, top, right, bottom) SVGPlot object or number[4] Set the insets for the main plot area. If the parameter value is less than or equal to 1 it is taken as the proportion of the width/height. If more than 1 it is the number of pixels. The default is [0.1, 0.1, 0.8, 0.9].

left (number) is the left position or (number[4]) all the positions in an array.

top (number) is the top position (omitted if left is an array).

right (number) is the right position (omitted if left is an array).

bottom (number) is the bottom position (omitted if left is an array).

svg.plot.area(0.1, 0.1, 0.9, 0.8);

If no parameters are provided, the function returns the current plot area.

var area = svg.plot.area();
alert(area[0] + ',' + area[1]);
container(cont) SVGPlot object or SVG element Set the container, which should be a svg element, for the plot elements. A default container is created automatically.

cont (SVG element) is the new plot container.

svg.plot.container(svg.svg(0, 0, 600, 350));

If no parameters are provided, the function returns the current plot container.

var cont = svg.plot.container();

Since 1.3.1.
equalXY(value) SVGPlot object or boolean Set whether the units along the x- and y-axes are of equal size. value (boolean) is the new setting. When true (default) the plot area may be reduced along one axis to fit the axis and maintain a constant unit size. When false the axes expand to fill the plot area available.

svg.plot.equalXY(false);

If no parameters are provided, the function returns the current equal X/Y setting.

if (svg.plot.equalXY()) ...
format(fill, stroke, settings) SVGPlot object or format object Set the background of the plot area.

fill (string) is how to fill the plot background (default 'none').

stroke (string, optional) is the colour of the outline (default 'black').

settings (object, optional) is additional formatting (SVG attributes) for the plot background.

svg.plot.format('ivory', 'gray', {fillOpacity: 0.5});

If no parameters are provided, the function returns the current area format as an object with at least fill and stroke attributes.

var format = svg.plot.format();
alert(format.fill);
functions(i) SVGPlotFunction or SVGPlotFunction[] Retrieve a single function or the current set of functions to be plotted.

i (number, optional) is the index of the required function

var fn = svg.plot.functions(0);

If no parameters are provided, the function returns the list of all functions.

var allFns = svg.plot.functions();
gridlines(xSettings, ySettings) SVGPlot object or object[2] Set the gridlines formatting for the plot. The default is no gridlines.

xSettings (string) is the colour of the gridlines along the x-axis, or (object) formatting (SVG attributes) for the gridlines along the x-axis, or null for none.

ySettings (string) is the colour of the gridlines along the y-axis, or (object) formatting (SVG attributes) for the gridlines along the y-axis, or null for none.

svg.plot.gridlines('green',
	{stroke: 'yellow', strokeWidth: 2});

If no parameters are provided, the function returns the current gridline format objects in an array.

var gridlines = svg.plot.gridlines();
alert(gridlines[0].stroke);
noDraw() SVGPlot object Suppress drawing of the plot until redraw() is called. Normally the plot is redrawn whenever anything changes, but this function allows multiple changes to be made before redrawing.

svg.plot.noDraw();
redraw() SVGPlot object Redraw the entire plot with the current settings and values. Normally the plot is redrawn whenever anything changes, but this function signals a redraw after pausing it with noDraw().

svg.plot.redraw();
status(onstatus) SVGPlot object Set the callback function for status updates. When the mouse hovers over a plot line, a call is made to this function with name of the current series. On mouse exit the function is called with a blank value.

onstatus (function) is the callback function.

svg.plot.status(setStatus);

Since 1.4.3 - function no longer has to be global.
title(value, offset, colour, settings) SVGPlot object or object Set the title of the plot.

value (string) is the title (default '').

offset (number, optional) is the pixel offset from the top of the plot (default 25).

colour (string, optional) is the fill colour for the title.

settings (object, optional) is formatting (SVG attributes) for the title (default textAnchor: 'middle').

svg.plot.title('Functions', 'blue', {stroke: 'yellow'});

If no parameters are provided, the function returns the current title settings as an object with value, offset, and settings attributes (colour appears in settings as fill).

var title = svg.plot.title();
alert(title.value);

Since 1.4.2 - added colour.

The following variables are available for general use.

NameTypeComments
legend SVGPlotLegend The plot's legend.

svg.plot.legend.settings(
	{fill: 'lightgoldenrodyellow', stroke: 'gray'});
xAxis SVGPlotAxis The plot's x-axis.

svg.plot.xAxis.title('X');
yAxis SVGPlotAxis The plot's y-axis.

svg.plot.yAxis.title('Y');

SVG Plot Function

The function object, SVGPlotFunction, contains details about a function being plotted. Add a new function with svg.plot.addFunction(), or retrieve the existing functions with svg.plot.functions().

end | fn | format | name | points | range | SVGPlotFunction

SignatureReturnsComments
SVGPlotFunction(plot, name, fn, range, points, stroke, strokeWidth, settings) SVGPlotFunction Create a new plot function definition. It is only used internally as part of the addFunction() call.

plot (SVGPlot) is the parent plot.

name (string, optional) is the name of this function.

fn (function) is the function to be plotted. It takes a single numeric value as a parameter and returns a numeric value.

range (number[2], optional) is the minimum and maximum x-values to be plotted. If not specified it defaults to the full range of the x-axis.

points (number, optional) is the number of points within the range to plot. More points produces a smoother curve, but produces a larger SVG document. If not specified it defaults to 100.

stroke (string, optional) is the colour of the plotted lines. If not specified it defaults to black.

strokeWidth (number, optional) is the width of the plotted lines.

settings (object, optional) is additional settings for the plotted values.
end() SVGPlot object Finish with this function and return to the parent plot.

svg.plot.functions(i).format(...).end()...;
fn(name, fn) SVGPlotFunction object or function Set or retrieve the function for this function definition.

name (string, optional) is the function's name.

fn (function) is the function to be plotted.

func.fn(Math.sin);

If no parameters are provided, the function returns the current function.

var func = func.fn();
format(stroke, strokeWidth, settings) SVGPlotFunction object or object Set or retrieve the formatting for this function definition.

stroke (string) is the line's colour.

strokeWidth (number, optional) is the line's width.

settings (object, optional) is additional formatting settings (SVG attributes) for the plotted values.

func.format('lightyellow', 'yellow', {strokeOpacity: 0.5});

If no parameters are provided, the function returns the current formatting settings as an object with at least stroke and strokeWidth attributes.

var format = func.format();
alert(format.stroke);
name(name) SVGPlotFunction object or string Set or retrieve the name for this function definition.

name (string) is the functions' name.

func.name('sine');

If no parameters are provided, the function returns the current name.

var name = func.name();
points(value) SVGPlotFunction object or number Set or retrieve the number of points plotted for this function.

value (number) is number of points to be plotted.

func.points(50);

If no parameters are provided, the function returns the current number of points.

var points = func.points();
range(min, max) SVGPlotFunction object or number[2] Set or retrieve the range of values plotted for this function.

min (number) is start of the plotted range or null to use the range of the x-axis.

max (number) is the end of the plotted range (omitted if min is null).

func.range(-3, 3);

If no parameters are provided, the function returns the current range.

var range = func.range();
alert(range[0] + ' - ' + range[1]);

SVG Plot Axis

The axis object, SVGPlotAxis, contains details about an axis on the plot. The plot maintains two references to axes: xAxis and yAxis.

end | format | line | scale | SVGPlotAxis | ticks | title

SignatureReturnsComments
SVGPlotAxis(plot, title, min, max, major, minor) SVGPlotAxis Create a new plot axis. It is only used internally as part of the plot initialisation.

plot (SVGPlot) is the parent plot.

title (string) is the title of the axis.

min (number, optional) is the minimum value displayed on this axis (default 0).

max (number, optional) is the maximum value displayed on this axis (default 100).

major (number, optional) is the distance between major ticks (default 10).

minor (number, optional) is the distance between minor ticks (default 0).

var axis = new SVGPlotAxis('X', -3, 3, 1, 0.2);
end() SVGPlot object Finish with this axis and return to the parent plot.

svg.plot.xAxis.labels(...).end()...;
format(colour, format) SVGPlotAxis object or object Set or retrieve the label format for this axis.

colour (string, optional) is the fill colour for the labels.

format (object) is formatting settings (SVG attributes) for the labels on this axis.

svg.plot.xAxis.format('red', {stroke: 'black'});

If no parameters are provided, the function returns the current label format settings (with colour as fill).

var format = svg.plot.xAxis.format();
alert(format.fill);

Since 1.4.2 - added colour.
line(colour, width, settings) SVGPlotAxis object or object Set or retrieve the line formatting for this axis.

colour (string) is the line's colour.

width (number, optional) is the line's width.

settings (object, optional) is additional formatting settings (SVG attributes) for the line.

svg.plot.xAxis.line('gray', 2, {strokeDashArray: '3,2'});

If no parameters are provided, the function returns the current line settings as an object with at least stroke and strokeWidth attributes.

var lineFormat = svg.plot.xAxis.line();
alert(lineFormat.stroke);
scale(min, max) SVGPlotAxis object or object Set or retrieve the scale for this axis.

min (number) is the minimum value shown.

max (number) is the maximum value shown.

svg.plot.yAxis.scale(-5, 105);

If no parameters are provided, the function returns the current scale as an object with min and max attributes.

var scale = svg.plot.yAxis.scale();
alert(scale.min + ' - ' + scale.max);
ticks(major, minor, size, position) SVGPlotAxis object or object Set or retrieve the ticks for this axis.

major (number) is the distance between major ticks.

minor (number) is the distance between minor ticks.

size (number, optional) is the length of the major ticks (default is 10, minor ticks are half size).

position (string, optional) is the location of the ticks: 'nw' (above or to the left), 'se' (below or to the right), 'both' (default).

svg.plot.yAxis.ticks(10, 5);

If no parameters are provided, the function returns the current ticks settings as an object with major, minor, size, and position attributes.

var ticks = svg.plot.yAxis.ticks();
alert(ticks.major);
title(title, offset, colour, format) SVGPlotAxis object or object Set or retrieve the title for this axis.

title (string) is the title text.

offset (number, optional) is the distance to offset the title position.

colour (string, optional) is the fill colour for the title.

format (object, optional) is formatting settings (SVG attributes) for the title.

svg.plot.xAxis.title('Year', 'green', {stroke: 'black'});

If no parameters are provided, the function returns the current title settings as an object with title, offset, and format attributes (colour appears in format as fill).

var titleSettings = svg.plot.xAxis.title();
alert(titleSettings.title);

Since 1.4.2 - added colour.

SVG Plot Legend

The legend object, SVGPlotLegend, contains details about the legend for the plot. Access the legend via svg.plot.legend.

area | end | settings | show | SVGPlotLegend

SignatureReturnsComments
SVGPlotLegend(plot, bgSettings, textSettings) SVGPlotLegend Create a new plot legend. It is only used internally as part of the plot initialisation.

plot (SVGPlot) is the parent plot.

bgSettings (object, optional) is additional formatting settings for the legend background.

textSettings (object, optional) is additional formatting settings for the legend text.
area(left, top, right, bottom) SVGPlotLegend object or number[4] Set or retrieve the legend area. If the parameter value is less than or equal to 1 it is taken as the proportion of the width/height. If more then 1 it is the number of pixels.

left (number) is the left position or (number[4]) all the positions in an array.

top (number) is the top position (omitted if left is an array).

right (number) is the right position (omitted if left is an array).

bottom (number) is the bottom position (omitted if left is an array).

svg.plot.legend.area(
	[0.005, 0.1, 0.125, 0.5]);

If no parameters are provided, the function returns the current area.

var area = svg.plot.legend.area();
end() SVGPlot object Finish with this legend and return to the parent plot.

svg.plot.legend.settings(...).end()...;
settings(sampleSize, bgSettings, textSettings) SVGPlotLegend object or object Set or retrieve additional settings for the legend area.

sampleSize (number, optional) the size of the sample box to display.

bgSettings (object) is additional formatting settings (SVG attributes) for the legend background.

textSettings (object, optional) is additional formatting settings (SVG attributes) for the legend text.

svg.plot.legend.settings(
	{fill: 'lightgoldenrodyellow',
	stroke: 'gray'});

If no parameters are provided, the function returns the current settings as an object with sampleSize, bgSettings, and textSettings attributes.

var settings =
	svg.plot.legend.settings();
alert(settings.sampleSize);
show(show) SVGPlotLegend object or boolean Set or retrieve whether the legend should be shown.

show (boolean) is true to display it, false to hide it.

svg.plot.legend.show(true);

If no parameters are provided, the function returns the current visibility.

if (svg.plot.legend.show()) ...