Closes #157; Add Multi-axis Support

[rsandor]

Description

This adds left/right multi-axis support to all real-time plots, and specific support for the real-time line chart. We abstract the range option to allow the programmer to supply a left and right range if they so desire.

TODO

• Add support for basic line charts with multi-axes
• Test: Epoch.Time.Plot
• Test: Epoch.Time.Line
• Test: Epoch.Util.flatten

Code Example

// Specify the left and right ranges
var leftRange = [0, 100];
var rightRange = [-10, 10];

// Setup two series, each using a different range
var data = [
  {
    label: 'Left Ranged Series',
    values: [
      { time: 0, y: 0 },
      { time: 1, y: 10 },
      { time: 2, y: 99 },
      ...
    ],
    // This is how your tell a layer to use a specific range...
    range: leftRange
  },
  {
    label: 'Right Ranged Series',
    values: [
      { time: 0, y: -9.8 },
      { time: 1, y: 2.4 },
      { time: 2, y: -0.5 },
      ...
    ],
    // Again, we must define the range for this particular series...
    range: rightRange
  }
];

// Create the real-time line plot with two ranges
var chart = new Epoch.Time.Line({
  range: {
    left: leftRange,
    right: rightRange
  },
  data: data,
  axes: ['left', 'right', 'bottom']
});

[rsandor]

I am considering allowing the programmer to use the names left and right when defining data for the series, like so:

var data = [
  { range: 'left', values: [...] },
  { range: 'right', values: [...]}
];

What do you guys think about this?

[rca]

Awesome! 🙌

+1 being able to specify the range right in the data array.

Based on the code sample above, it looks like a fixed range needs to be given; is it possible to auto-scale? Not sure what the implementation would look like, possibly specify true rather than a [min, max] arrray?

var chart = new Epoch.Time.Line({
  range: {
    left: true,
    right: true
  },
  [...]
});

Do you have any thoughts on how to go about suggesting what dataset is associated with a particular axis, either by color coding the labels the same color as the dataset or some other means? For instance, in the example above, I have no idea what the range of either dataset is. Color coding becomes ambiguous as soon as there are multiple datasets on an axis, though. Maybe the answer is axis titles and a legend?

In any case, this looks great!

[rca]

Also, with respect to fixed vs. dynamic ranges, would it be possible to reconfigure the range when data is being updated?

[rsandor]

@rca - In the visualizations I have seen (mostly static, mind you) they usually use the context of the data with an associated legend. I don't think you can clearly understand a multi-axis chart without these. Thus I think it is up to the visualization designer to clearly communicate the data or trend they are trying to show with any real-time line chart.

To this end there is an effort currently under way to add a new "legends" plugin for Epoch that can help when creating visualizations such as these (see #2 and #146). I have always been of the belief that legends and labels are outside the scope of the project. Recently I have been thinking that there should be "helpers" that make it easy to generate markup and basic styles that can be mutated to fit a particular design. Any help with legends and labels support would be greatly appreciated.

[rsandor]

@rca - Added the ability to automatically generate the axes ranges by using labels. Here's how it works, define you data like so:

var data = [
  { label: 'Layer 1', range: 'range-a', data: [...] },
  { label: 'Layer 2', range: 'range-b', data: [...] },
  { label: 'Layer 3', range: 'range-a', data: [...] }
];

Each layer in the data is as associated with a "range label" which can then be applied to the left or right side of the chart when you make it:

var chart = new Epoch.Time.Line({
  data: data,
  range: {
    left: 'range-a',
    right: 'range-b'
  }
});

The left axis will automatically fit the min and max of the collected values from both layers 1 and 3. The right side will use the min and max of layer 2 only.

Does this suffice for the "automatic" ranges?

[rca]

I see your point about legends and labels being out of scope. Helpers would definitely be useful, for example "what's the color of the first dataset", "give me the label for the first dataset", etc.

[rca]

Taking a look at dynamic range definitions now, nice! :)

[rca]

By the way, given the discussion about legends and axis labels not being part of Epoch itself, what is the purpose of making label part of the chartData array?

[rsandor]

The label field harkens way back to the early days when I had intended to create legend helpers. I decided against focusing on it, and now I'm coming back around :) It has also been used to apply specific classes to layers so you can style semantically.

[rsandor]

This is ready to go. Merging.