API Reference

Lisa Zhang edited this page Dec 3, 2013 · 17 revisions

WikiAPI Reference

When you include the polychart2.js file, it will create object in the global namespace called polyjs. All functionality within Polychart.js is scoped under this object polyjs. This object contains three methods:

Constructors

Data: polyjs.data()

This is a constructor for creating a Polychart.js data object to be used for plotting. It can take as an input JSON or CSV formats, or an AJAX endpoint that would return data in such formats.

Chart: polyjs.chart()

Constructor for a Polychart.js chart object. This function expects as input a JSON specification object, further discussed in the chart page. The function returns an object representing the resulting graphic, and can be used to define interactions.

Pivot Table: polyjs.pivot()

Constructor for a Polychart.js pivot table object. This function expects as input a JSON specification object, further discussed in the pivot table page.

Numeral: polyjs.numeral()

Constructor for a Polychart.js numeral object, for rendering a single numerical value. This function expects as input a JSON specification object, further discussed in the numeral page.

Interactions: polyjs.handlers.*

Helper functions for creating built-in interaction handlers. Also see the section on interaction for more information about how interactions work in general.

Chart Methods

The constructor polyjs.chart() returns a Polyjs chart object that has the following methods:

chart.make(spec)

Re-rendering an existing chart with an optional new specification. The existing chart will be animated to the new state described by the new data and specification.

chart.addHandler(fn)

Add an event handler to respond to one or more events. The handler functions are called whenever an event occurs -- i.e. when User interacts with the chart. The parameter fn should either be a function, or an object with a method handle that serves as the event handler.

Concepts

Aesthetic Mapping

Aesthetics describe visual properties that can be used to describe data. Colour, size, shape, x- and y-positions are all examples of aesthetics. In Polychart, graphics definitions are specified by creating mappings between aesthetics and data. For example, defining the aesthetic colour to map to the data series temperature in a scatter plot would make the colour of the points correspond to the data value of temperature being represented.

Furthermore, aesthetics can be mapped to constants, the value of a function on a data column, or aggregate statistics calculated based on data.

Guides and Scales

If aesthetics mappings describe which data columns are mapped to which visual properties, then Scales determine how the mapping occurs. (e.g. Are lower temperature values mapped to the colour green or blue? What about higher ones?) Guides, on the other hand, visualizes the scale so the visual property can be decoded by a viewer of the graphic.

Filtering

Filters can be used when only a subset of the data set needs to be visualized. Charts, pivot tables, and numerals all use the same format for defining filters.

Chart Interaction

Once a chart object is created, interaction handlers may be added to the chart via a method call.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.