Stacked Bars, Clustered Bars, and Interaction Changes

Good Evening,

This release lays the groundwork for some major changes we've been meaning to make for a while. Rather than introduce them all at once, our goal is to add the new features in a way that preserves Plottable's existing functionality, improves on it, and eventually replaces it. (As an example, see how Axis.Category and Axis.Numeric gradually replaced the old XAxis and YAxis classes in previous releases).

Multi-Series Plots: We've known for a while that, while the "one-series-per-plot" paradigm had worked well for us thus far, we would need to augment it eventually; stacked and clustered bars demanded that the rendering code responsible for visualizing multiple datasets be aware of each other, and even using multiple Plot.Lines requires coordinating them so that each is a different color.

Interactions: While some interactions currently exist in the code base, they haven't been as carefully considered as other parts of our API, nor do they have a particularly cohesive unifying structure. They are currently under active (re)-development.

---

The changes in this release:

Plot.ClusteredBar and Plot.StackedBar

Plot.ClusteredBar and Plot.StackedBar have been added. They represent the first of the "new" style plots, which handle multiple datasets in a principled way. An example use case:

var stackedBarPlot = new Plottable.Plot.StackedBar(xScale, yScale);
stackedBarPlot.addDataset("d1", data1)
              .addDataset("d2", data2)
              .addDataset("d3", data3); // add many datasets
stackedBarPlot.project("x", "name", xScale)
              .project("y", "y", yScale); // projection works as usual

Datasets / DataSources can be added with identifying keys and their order changed. The data backing each dataset has to have the same "shape", as the same projector is used for each dataset. Currently, Plot.ClusteredBar and Plot.StackedBar can only draw vertical bars and only support datasets of the same length, but expect these restrictions to be removed with future code enhancements.

Interaction.BarHover

Interaction.BarHover adds interactivity to Plot.VerticalBar and Plot.HorizontalBar, triggering callbacks when the user mouses over a bar or mouses away from a bar. To use:

var barHover = new Plottable.Interaction.BarHover(barPlot); // either kind works
barHover.onHover(function(datum, barSelection) { // CALLBACK CODE HERE });
barHover.onUnhover(function(datum, barSelection) { // MORE CALLBACK CODE HERE });
barHover.registerWithComponent();

The callbacks are passed a d3 selection containing the bar that was just moused over or out of, as well as the data associated with the bar. In addition, the interaction can be set to either "point" mode (mousing over the rendered bar will trigger the callback) or "line" mode (mousing beyond the end of the bar will also trigger it; useful for zero-length bars).

Interaction.Drag API changes

Interaction.Drag now triggers callbacks on dragstart, drag, and dragend. In addition, its callbacks have been updated to use the new Point interface:

  export interface Point {
    x: number;
    y: number;
  }

---

Coming Up

We will continue to improve the new multi-series bar plots, while adding others such as stacked area plots and multiple-line plots (where the color scale is built-in). Also expect more Interactions to be added and the API and behavior of existing interactions to be improved.

Happy Plotting.