Customization with accessors

Plots work by taking each point of data and determining what it needs to do to draw that piece of data. Each type of plot has a specific set of visual properties, or attributes. Take the following examples:

• Plots.Scatter - requires each point of data to map to an X and Y coordinate. In addition, one might also want to customize the fill and the radius of each of the scatter points, perhaps depending on a datum attribute.

• Plots.Line - also requires mapping to an X and Y coordinate. However, a line plot has different attributes to be customized; in particular, one might want to change the stroke (color of the line)

In Plottable, the concept of an Accessor is used in order to define how a piece of each individual datum should be assigned to a specific attribute in your plot.

Now, we will see how to use accessors in order to create a customized Plots.Scatter.

As you can see, we not only want to plot the X and Y attributes; we also want to capture the radius and stroke as defined by our data. Our data is generated with the following code:

// Format: { "x": 1, "y": 1, "radius": 1, "stroke": "#FF0000" }
var data = [];
var colors = ["#C7254E", "#009CDE"];
for (var i = 2; i < 10; i++) {
  data.push({ "x": i, "y": i, "radius": Math.pow(i, 2), "stroke": colors[i % colors.length] });
}

Let's start off with some basic code for creating a scatter plot.

var xScale = new Plottable.Scales.Linear();
var yScale = new Plottable.Scales.Linear();
var plot = new Plottable.Plots.Scatter()
  .x(function(d) { return d.x; }, xScale)
  .y(function(d) { return d.y; }, yScale)
  .addDataset(new Plottable.Dataset(data));

The .x() and .y() methods may be familiar from our prior example; they are attributes in themselves, with accessors that retrieve the x and y attributes on the datum and runs them through their respective scales in order to generate pixel position values.

One neat trick to note is that attribute methods are typically chainable; therefore, it is possible to set many attributes in a single statement like so: plot.x(..).y(..)

If your values don't need to be scaled, you don't necessarily need to pass in a scale; it will simply use the raw value present in your datum. We leverage this technique here with the scatter plot size.

plot.size(function(d) { return d.radius; });

Sometimes, you might want to set an attribute that is not explicitly defined as a public method. In this situation, the .attr() method is provided. It functions identically to public attribute methods; the only difference in its method signature is that the first parameter is the name of the attribute. We use this technique to set the stroke and the stroke width for our scatter plot elements.

plot.attr("stroke", function(d) { return d.stroke; });
plot.attr("stroke-width", 3);

And now we just go ahead and render our plot!

plot.renderTo("svg#example");

Now it's time to move on to building flexible layouts. Full code for the above example is here:

var xScale = new Plottable.Scales.Linear();
var yScale = new Plottable.Scales.Linear();

var data = [];
var colors = ["#C7254E", "#009CDE"];
for (var i = 2; i < 10; i++) {
  data.push({ "x": i, "y": i, "radius": Math.pow(i, 2), "stroke": colors[i % colors.length] });
}

var plot = new Plottable.Plots.Scatter()
  .x(function(d) { return d.x; }, xScale)
  .y(function(d) { return d.y; }, yScale)
  .size(function(d) { return d.radius; })
  .attr("stroke", function(d) { return d.stroke; })
  .attr("stroke-width", 3)
  .addDataset(new Plottable.Dataset(data));

plot.renderTo("svg#example");