Horizon

Wiki ▸ API Reference ▸ Horizon

A horizon chart. To create a horizon chart, first create a context. For example:

var context = cubism.context(), // a default context
    horizon = context.horizon(); // a default horizon chart

Next you'll need an array of metrics to visualize, which typically requires one or more source, such as Graphite or Cube:

var cube = context.cube("http://cube.example.com");

var metrics = [
  cube.metric("sum(request.eq(language,'en'))"),
  cube.metric("sum(request.eq(language,'es'))"),
  cube.metric("sum(request.eq(language,'de'))"),
  cube.metric("sum(request.eq(language,'fr'))")
];

Equivalently, you could use cube.metric as the metric accessor, and simplify the definition of the metrics as an array of strings:

var horizon = context.horizon()
    .metric(cube.metric);

var metrics = [
 "sum(request.eq(language,'en'))",
 "sum(request.eq(language,'es'))",
 "sum(request.eq(language,'de'))",
 "sum(request.eq(language,'fr'))"
];

Or you could go one step further and use an array of languages:

var horizon = context.horizon()
    .metric(function(d) { return cube.metric("sum(request.eq(language,'" + d + "'))"); });

var metrics = [
 "en",
 "es",
 "de",
 "fr"
];

# horizon(selection)

Apply the horizon chart to a D3 selection. By binding the metrics to a selection, you can create a horizon chart per metric:

d3.select("body").selectAll(".horizon")
    .data(metrics)
  .enter().append("div")
    .attr("class", "horizon")
    .call(horizon);

# horizon.mode([mode])

Get or set the horizon mode, which controls how negative values are displayed. If mode is specified, sets the mode and returns the horizon chart. If mode is not specified, returns the current mode. Defaults to "offset". The following modes are supported, as illustrated in this diagram:

• offset mode translates negative values up, so they descend from the top edge of the chart.

• mirror mode inverts negative values, equivalent to taking the absolute value.

# horizon.height([pixels])

Get or set the chart height in pixels. If height is specified, sets the chart height to the specified value in pixels and returns the horizon chart. If height is not specified, returns the current height, which defaults to 30 pixels.

# horizon.metric([metric])

Get or set the chart metric accessor. If metric is specified, sets the chart metric accessor and returns the horizon chart. The metric may be specified either as a single metric, or as a function that returns a metric. If metric is not specified, returns the current metric accessor, which defaults to the identity function (so that you can bind the selection to an array of metrics, as demonstrated above). When the metric is specified as an accessor function, it is invoked for each element in the selection, being passed the bound data (d) and index (i).

# horizon.scale([scale])

Get or set the chart y-scale. If scale is specified, sets the chart y-scale to the specified value and returns the chart. If scale is not specified, returns the current y-scale which defaults to a linear scale with rounding. For example, this method can be used to apply a square-root transform.

# horizon.extent([extent])

Get or set the chart extent (if not automatic). If extent is specified, sets the chart extent accessor and returns the horizon chart. The extent may be specified either as an array of two numbers, or as a function that returns such an array. If extent is not specified, returns the current extent accessor, which defaults to null. When the extent is specified as an accessor function, it is invoked for each element in the selection, being passed the bound data (d) and index (i). If the extent is null, it will be computed automatically via metric.extent.

# horizon.title([title])

Get or set the chart title. If title is specified, sets the chart title accessor and returns the horizon chart. The title may be specified either as a string, or as a function that returns a string. If title is not specified, returns the current title accessor, which defaults to the identity function. When the title is specified as an accessor function, it is invoked for each element in the selection, being passed the bound data (d) and index (i). If the title is null, no title will be displayed.

# horizon.format([format])

Get or set the chart's value format function. If format is specified, sets the chart value formatter and returns the horizon chart. If format is not specified, returns the current formatter, which defaults to d3.format(".2s"); see d3.format for details.

# horizon.colors([colors])

Get or set the horizon layer colors. If colors is specified, sets the horizon layer colors to the specified array of colors and returns the horizon chart. If colors is not specified, returns the current array of colors, which defaults to #08519c #3182bd #6baed6 #bdd7e7 #bae4b3 #74c476 #31a354 #006d2c. The array of colors must have an even number of elements; color.length / 2 determines the number of bands. The first half of the array lists the colors used for the negative bands, and the second half lists the colors for the positive bands.

# horizon.remove(selection)

Removes the horizon chart from a D3 selection, and removes any of the chart's associated listeners. This method only removes the contents added by the horizon chart itself; typically, you also want to call remove on the selection. For example:

d3.select(".horizon")
    .call(horizon.remove)
    .remove();

Requires that the elements in the selection were previously bound to this chart.