Skip to content

High level API

Jump to bottom
andreaferretti edited this page Feb 16, 2015 · 9 revisions

High level API (graphs)

Based on the shapes above, we can construct more complex graphs. At this level, the API assume one has 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.

All graph objects - that is, objects returned by some graph functions - have the field curves that contains an array, and possibly more fields, depending on the graph. Each element of 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.

Pie graph

The Pie graph can be used as follows:

var Pie = require('paths/pie');
var pie = Pie({
  data: [
    { name: 'Italy', population: 59859996 },
    { name: 'Mexico', population: 118395054 },
    { name: 'France', population: 65806000 },
    { name: 'Argentina', population: 40117096 },
    { name: 'Japan', population: 127290000 }
  ],
  accessor: function(x) { return x.population; },
  compute: {
    color: function(i) { return somePalette[i]; }
  },
  center: [20, 15],
  r: 30,
  R: 50
});

Parameters:

  • center, r, R: have the same geometric meaning as in the Sector function
  • data: contains an array with the data to plot. The precise form of the data is not important, because the actual value of the data will be extracted by the accessor function.
  • accessor: a function that is applied to each datum in data to extract a numeric value
  • compute (optional): see the introduction.

The object returned by the Pie function contains the curves array, on which one can iterate to draw the sectors. Each member of this array has the properties sector, index and item, the latter containing the actual datum associated to the sector.

Bar graph

The Bar graph can be used as follows:

var Bar = require('paths/bar');
var bar = Bar({
  data: [
    [
      { name: 'Italy', population: 59859996 },
      { name: 'Spain', population: 46704314 }
      { name: 'France', population: 65806000 },
      { name: 'Romania', population: 20121641 },
      { name: 'Greece', population: 10815197 }
    ],
    [
      { name: 'Zambia', population: 14580290 },
      { name: 'Cameroon', population: 20386799 }
      { name: 'Nigeria', population: 173615000 },
      { name: 'Ethiopia', population: 86613986 },
      { name: 'Ghana', population: 24658823 }
    ]
  ],
  accessor: function(x) { return x.population; },
  compute: {
    color: function(i) { return somePalette[i]; }
  },
  width: 500,
  height: 400,
  gutter: 10
});

Parameters:

  • width, height: have the obvious geometric meaning
  • data: contains an array of arrays with the data to plot. The precise form of the data is not important, because the actual value of the data will be extracted by the accessor function. Each array will be represented by a series of bars with the same index.
  • accessor: a function that is applied to each datum inside each item in data to extract a numeric value
  • gutter (optional): the space to leave between each group of bars
  • compute (optional): see the introduction.

The bar chart allows multiple histograms to be drawn side by side. If you just have one series to be plotted, put it inside an array of length one anyway, like this:

Bar({
  data: [[2, 5, 3, 9, 7]],
  ...
});

The object returned by the Bar function contains the curves array, on which one can iterate to draw the rectangles. Each member of this array has the properties line, index and item, the latter containing the actual datum associated to the rectangle.

Stock graph

The Stock graph is used to represent one or more line charts. It can be used as follows:

var Stock = require('paths/stock');
var data = [
  [
    { year: 2012, month: 1, value: 13 },
    { year: 2012, month: 2, value: 12 },
    { year: 2012, month: 3, value: 15 }
  ],
  [
    { year: 2012, month: 1, value: 21 },
    { year: 2012, month: 2, value: 22 },
    { year: 2012, month: 3, value: 22 }
  ]
];

function date(data) {
  var d = new Date();
  d.setYear(data.year);
  d.setMonth(data.month - 1);
  return d.getTime();
}

var stock = Stock({
  data: data,
  xaccessor: date,
  yaccessor: function(d) { return d.value; },
  width: 300,
  height: 200,
  compute: {
    color: function(i) { return somePalette[i]; }
  },
  closed: true
});

Parameters:

  • width and height: have the obvious geometric meaning; data will be rescaled to fit into a rectangle of these dimensions
  • data: contains the actual data to plot. It should be an array of arrays, each internal array representing a time series to be plotted. The actual format of the data in the time series is not important; the actual abscissa and ordinate of the point are extracted by the xaccessor and yaccessor function.
  • xaccessor, yaccessor: two functions that extract from each datum its x and y coordinates. They default to function(d) { return d[0] } and function(d) { return d[1] } respectively, so if data is passed as an array of arrays of arrays of 2 elements, the accessor functions are optional.
  • closed (optional, default false): a boolean used to decide how to construct the paths for the area plots. If closed is set to true, these will be stretched to include part of the x axis, even if the data are not around 0. Use this if you want to be sure that the area paths touch the horizontal axis
  • compute (optional): see the introduction.

The Stock function will then return an object with the properties curves, xscale and yscale. Under curves it contains an array of objects, each having the properties line, area, item and index. line and area are two polygon objects, as in the previous paragraph; the first one holds the polygon for the line chart, while the second one is a closed polygon that can be used to draw the area fill. Under item one finds the original element in the data.

Finally, xscale and yscale are the scales used to represent the data on the given width and height. They can be used to find the coordinates of the axis and draw them.

Smooth line graph

The smooth line graph is used to represent one or more line charts; unlike Stock it interpolates between the data points with smooth Bézier curves. The API for paths.smooth-line is identical to paths.stock, so the two can be used interchangeably.

  • [Radar charts](Radar charts)
  • [Tree charts](Tree charts)
  • [Waterfall graphs](Waterfall graphs)
  • [Force-directed graphs (experimental)](Force-directed graphs)
  • [Sankey diagrams](Sankey Diagrams)
Clone this wiki locally