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 nameDescriptionTypeDefault
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 nameDescriptionTypeDefault
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.

PropertyTypeDescription
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.

PropertyTypeDescription
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.

PropertyTypeDescription
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.

PropertyTypeDescription
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

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

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

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.

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

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.

Layout Examples