Using Time Axes

Axes.Time are highly configurable but may be hard to understand at first glance.

Time Axes are unlike other Plottable Axes because by default, they can have multiple tiers. The top tier will correspond to a smaller unit of time (like months, for example), and lower tiers corresponds to a larger units of time (like years).

Time axes won’t display all their tiers if it doesn’t make sense to do so. When the domain is large, a Time Axis may just show years.

If you pan or zoom on a Plottable Time Axis, you’ll see the tier configurations smoothly turning into other configurations. For example, zooming in on an axis showing only years will reveal a tier for months (try it on the axis above!).

To use different axis configurations than the ones Plottable provides, there is an .axisConfigurations() endpoint. It works as a getter and a setter. When called as a getter:

axis.axisConfigurations();

it returns Plottable's default configurations:

[
  [
      { interval: Plottable.TimeInterval.second, step: 1, formatter: Plottable.Formatters.time("%I:%M:%S %p") },
      { interval: Plottable.TimeInterval.day, step: 1, formatter: Plottable.Formatters.time("%B %e, %Y") }
  ],
  [
      { interval: Plottable.TimeInterval.second, step: 5, formatter: Plottable.Formatters.time("%I:%M:%S %p") },
      { interval: Plottable.TimeInterval.day, step: 1, formatter: Plottable.Formatters.time("%B %e, %Y") }
  ],

  ...

  [
    { interval: TimeInterval.year, step: 1000, formatter: Plottable.Formatters.time("%Y") }
  ]
];

timeAxis.axisConfigurations() returns an array of arrays, which we'll call defaultConfigurations.

defaultConfigurations[0] determines the narrowest configuration — which tiers will show on the axis when it is all the way zoomed in. There are two objects in defaultConfigurations[0] -- the first corresponds to the top tier, and the second to the tier below it.

Looking at the first object in the first array in defaultConfigurations, we see that the interval attribute is set to TimeInterval.second, which means that the ticks will be measured in terms of seconds. The step is set to 1, so the ticks will be placed one unit apart. Combining these two attributes, we see that the ticks will be placed one second apart.

The formatter works the same way as on other Plottable Axes. The data value at any position on the axis will be passed through that formatter to create the axis label.

The second object will have ticks one day apart, and has a formatter that shows the month, day, and year in a human-readable way. This determines what is displayed on the axis' second tier.

As we zoom out on the Time Axis, labels no longer fit in their current configuration, and Plottable moves to the next configuration in defaultConfigurations.

When we’re all the way zoomed out, Plottable draws the axis based on the last configuration in defaultConfigurations. This array only has one object, so the Axis will have only one tier.

Lower Granularity: Only showing Days, Months, and Years

This can be done by starting with the Plottable Configurations and altering them. You can iterate through each tierConfiguration, and only keep tierConfigurations with an interval of days, months, or years by inserting them into a new array. Then, call .axisConfigurations() with your new array, and you have an axis that only shows intervals of time that are one day or larger.

var scale = new Plottable.Scales.Time();
var axis = new Plottable.Axes.Time(scale, "bottom");
var configs = axis.axisConfigurations();
var newConfigs = [];
configs.forEach(function(tierConfiguration){
  var newTierConfiguration = [];
  tierConfiguration.forEach(function(row){
    if(row.interval === "day" ||
      row.interval === "month" ||
      row.interval === "year"){
      newTierConfiguration.push(row);
    }
  });
  newConfigs.push(newTierConfiguration);
});
axis.axisConfigurations(newConfigs);

Four Tier Axis

You can build an axis with an unlimited number of tiers. This time axis has 4 tiers:

var newConfigs = [];
var tiers = [];
tiers.push({ formatter: new Plottable.Formatters.time("%H:%M"),
           interval: Plottable.TimeInterval.hour,
           step: 12 });
tiers.push({ formatter: new Plottable.Formatters.time("%d"),
           interval: Plottable.TimeInterval.day,
           step: 1 });
tiers.push({ formatter: new Plottable.Formatters.time("%B"),
           interval: Plottable.TimeInterval.month,
           step: 1 });
tiers.push({ formatter: new Plottable.Formatters.time("%Y"),
           interval: Plottable.TimeInterval.year,
           step: 1 });
newConfigs.push(tiers);
timeAxis.axisConfigurations(newConfigs);