PlotKit Home | << | >>

PlotKit Layout

PlotKit Layout is the core of the plotting engine. It deals exclusively with laying objects out on a virtual canvas that has the dimension of 1.0 x 1.0.

The layout engine abstracts away all the complex layout problems with plotting charts and presents a list of objects that need to rendered rather than mixing this with the rendering logic.

PlotKit Layout also is responsible for simple chart state querying so renderers can implement basic event support for objects on the canvas.

Constructor

new Layout(style, options);

Layout takes the following arguments:

style which can be bar, line or pie which represnts the style of the graph that is desired.

options is a dictionary/associative array of layout options. Unrecognised keys are ignored. The following options are supported:

Layout Options

Bar and Line Chart layout options

Option name	Description	Type	Default
barWidthFillFraction	Amount of space the total amount of bars should consume per X value.	Real number	0.75
barOrientation	Orientation of a bar chart. (PlotKit 0.9+ only)	String ("vertical", "horizontal")	vertical
xAxis	Minimum and Maximum values on the X axis.	Array of 2 Real numbers. (eg. [0.0, 10.0])	null
xNumberOfTicks	Used when automatically calculating axis ticks. This denotes the number of ticks there should be in the graph.	integer	10
xOriginIsZero	Should graph have X axis origin at 0	boolean	true
xTickPrecision	The number of decimal places we should round to for tick values.	integer	1
xTicks	X values at which ticks should be drawn. Automatically calculated if not defined using the parameters `xNumberOfTicks` and ``xTickPrecision``.	Array of {label: "somelabel", v:value}.	null
yAxis	Minimum and Maximum values on the Y axis.	Array of 2 Real numbers. (eg. [0.0, 10.0])	null
yNumberOfTicks	Used when automatically calculating axis ticks. This denotes the number of ticks there should be in the graph.	integer	5
yOriginIsZero	Should graph have Y axis origin at 0	true
yTickPrecision	The number of decimal places we should round to for tick values.	integer	1
yTicks	Y values at which ticks should be drawn. Automatically calculated if not defined using the parameters ``yNumberOfTicks`` and ``yTickPrecision``.	Array of {label: "somelabel", v:value}.	null

Pie Chart Layout Options

Option name	Description	Type	Default
pieRadius	Radius of the circle to be drawn.	Real number	0.4

Layout Properties

There are some properties you can access, either because you are using a layout inside a renderer or if you would like additional information. Under normal operations, you will not need to, or should modify these parameters.

Property	Type	Description
style	String	This denotes the type of chart this layout is using. Valid values are ``bar``, ``line`` or ``pie``. Renderers will use this to determine which parameter (``bars``, ``points`` or ``slices``) to access in order to get draw the chart.
bars	Array of Bar.	This is a list of rectangles with values that the renderer should plot. This will only be valid after ``evaluate()`` has run. The properties of ``bar`` is described here. This is only valid if style is ``bar``. This array is sorted by dataset and then x-values.
points	Array of Point.	This is a list of points with values that the renderer should plot. This will only be valid after ``evaluate()`` has run. The properties of ``bar`` is described here. This is only valid if style is ``line``. This array is sorted by dataset and then x-values.
slices	Array of Slice.	This is a list of pie slices with values that the renderer should plot. This will only be valid after ``evaluate()`` has run. The properties of ``bar`` is described here. This is only valid if style is ``pie``.
xticks	Array of Tick.	For style in ``bar`` or ``line``, these are the ticks on the X axis. A ``tick`` is represented as a two element array with the first element representing the x position of the tick and the second element representing the string value of the label at that position.
yticks	Array of Tick.	For style in ``bar`` or ``line``, these are the ticks on the Y axis. A ``tick`` is represented as a two element array with the first element representing the y position of the tick and the second element representing the string value of the label at that position.
datasets	Associative Array of datasets	This should normally only be used to find the number of datasets by performing ``keys(layout.datasets)``. If you are looking at this in a renderer, then the layout engine needs to be extended.

Layout Types

Here are the definition of the types that you will encounter if you access the properties of the Layout object, specifically bars, points and slices. If you are not writing a renderer, you do not need to know this.

Bar Type

Represents a bar that the renderer will draw. It contains the following properties.

Property	Type	Description
x, y	float	top left position of the bar between 0.0 and 1.0.
w, h	float	width and height of the bar from (``x``, ``y``) between 0.0 and 1.0.
xval, yval	float	The actual x value and y value this bar represents.
name	string	Name of the dataset which this bar belongs to.

Point Type

This represents a point on a line chart.

Property	Type	Description
x, y	float	top left position of the point between 0.0 and 1.0.
xval, yval	float	The actual x value and y value this bar represents.
name	string	Name of the dataset which this bar belongs to.

Slice Type

This represents a pie slice in a pie chart.

Property	Type	Description
fraction	float	The fractional value this slice represents. This number is between 0.0 and 1.0
xval, yval	float	The x and y values of this slice.
startAngle	float	This is the angle of the start of the slice, in radians.
endAngle	float	This is the angle of the end of the slice, in radians.

Layout Methods

addDataset(name, values)

Adds a dataset to the layout engine and assigns it with name. values is an array of \[x, y\] values.

removeDataset(name)

Removes a dataset from the layout engine. In order for the new data to take effect, you must run evaluate().

addDatasetFromTable(name, tableElement, xcol = 0, ycol = 1, labelCol = -1)

Handy function to read values off a table. name is the name to give to the dataset just like in addDataset(), tableElement is the table which contains the values. Optionally, the user may specify to extract alternative columns using xcol and ycol.

New in 0.9.1: If labelCol is specified to a value greater than -1, it will take the contents of that column as the xTick labels.

evaluate()

Performs the evaluation of the layout. It is not done automatically, and you must execute this before passing the layout to a renderer.

hitTest(x, y)

Used by renderers to see if a virtual canvas position corresponds to any data. The return value varies per style. For bar charts, it will return the Bar type if it is a hit, or null if not. For line charts, it will return a value if the point is underneath the highest curve, otherwise null (TODO: expand this or change implementation). For pie charts, it will return the Slice object that is at the point, otherwise null.

Note that the specification of this function is subject to change.

Layout Notes

Pie Chart Data and Ticks Restrictions

Note that you can only use one dataset for pie charts. Only the y value of the dataset will be used, but the x value must be unique and set as it will correspond to the xTicks that are given.

Labels for pie charts will only use xTicks.