High level API

The high level API allows to construct more complex graphs, based on the Shapes API. At this level, we are given a collection of data that has to be shown on a graph, and take care of normalizing the data, so that for instance if you display multiple line graphs on the same chart, the scales are normalized.

Common structure

All graph objects - that is, objects returned by some graph functions below - have the field curves that contains an array, and possibly more fields, depending on the graph. Each element curves has the properties:

• item, which is a reference to the corresponding data item,
• index
• and one or more field containing shape objects, for instance sector in the case of the pie graph, or line and area for the line charts.

Thus, a graph object has the shape:

{
  curves: [
    {
      item: <datum>,
      index: <index>,
      <label>: <shape object>,
      ...
    },
    ...
  ],
  ...
}

All of the following graph APIs accept a parameter named compute which is a hash table of functions that should be evaluated for each curve to be drawn. A typical use would be to compute a color based on the index or the data item, like:

{
  compute: {
    color: function(i, item) {
      ...
    }
  }
}

All curves in the curves array will contain the corresponding properties in addition to index and item; for instance in the example above each curve will have the color property. Each function in the compute hash receives two parameters index and item; where it makes sense it also receives a third parameter group containing a group index (for items that are clustered).

This feature is useful if the resulting graph will be rendered with a somewhat static template engine, such as Mustache, that needs to have all fields precomputed. More flexible template engines, such as the one in Ractive, allow custom expressions to be evaluated in templates, so there will be generally no need for the compute parameter.

Charts

• [Pie charts](Pie charts)
• [Bar charts](Bar charts)
• [Stock charts](Stock charts)
• [Smooth line charts](Smooth line charts)
• [Radar charts](Radar charts)
• [Stack charts](Stack charts)
• [Tree charts](Tree charts)
• [Waterfall charts](Waterfall graphs)
• [Force-directed graphs (experimental)](Force-directed graphs)
• [Sankey diagrams](Sankey Diagrams)
• [Voronoi diagrams](Voronoi Diagrams)