Axis

Wiki ▸ API Reference ▸ Axis

A thin wrapper on top of D3’s d3.svg.axis component that automatically updates whenever the associated context changes. To create an axis, first create a context. For example:

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

# axis(selection)

Apply the axis to a D3 selection or transition containing one or more SVG element. For example:

d3.select("body").append("svg")
    .attr("class", "axis")
    .attr("width", 1440)
    .attr("height", 30)
  .append("g")
    .attr("transform", "translate(0,30)")
    .call(axis);

To add 20px of padding on both sides, you might say:

d3.select("body").append("svg")
    .attr("class", "axis")
    .attr("width", 1480)
    .attr("height", 30)
    .style("margin-left", "-20px")
  .append("g")
    .attr("transform", "translate(20,30)")
    .call(axis);

If you want to customize the display of the axis further, you can post-process the axis display by selecting and modifying elements after the context’s change event. For example, to use left-aligned tick labels:

d3.select("body").append("svg")
    .attr("class", "axis")
    .attr("width", 1920)
    .attr("height", 1080)
    .call(axis)
    .call(function(svg) {
      context.on("change.axis", function() {
        svg.selectAll("text")
            .attr("x", 10)
            .attr("y", 10)
            .attr("dy", ".71em")
            .attr("text-anchor", "start");
      });
    });

# axis.orient([orientation])

Get or set the axis orientation. If orientation is specified, sets the axis orientation and returns the axis. If orientation is not specified, returns the current orientation, which defaults to "bottom". Valid values are "top", "bottom", "left" and "right". For a vertical axis, specify "left" or "right"; for a horizontal axis, specify "top" or "bottom".

# axis.ticks([arguments…])

Get or set the arguments that are passed to the underlying scale’s tick function. The specified arguments are passed to scale.ticks to compute the tick values. For quantitative scales, specify the desired tick count such as axis.ticks(20). For time scales, you can pass in a count or a function, such as axis.ticks(d3.time.minutes, 15).

The arguments are also passed to the scale’s tickFormat method to generate the default tick format. Thus, for log scales, you might specify both a count and a tick format function. For example:

axis.ticks(20, function(d) { return "$" + d.toFixed(2); });

# axis.tickSubdivide([count])

Get or set the tick subdivision count. If count is specified, sets the number of uniform subdivisions to make between major tick marks and returns the axis. If count is not specified, returns the current subdivision count which defaults to zero.

# axis.tickSize([major[‍[, minor], end]‍])

Get or set the size of major, minor and end ticks. The end ticks are determined by the associated scale's domain extent, and are part of the generated path domain rather than a tick line. Note that the end ticks may be close or even overlapping with the first or last tick. An end tick size of 0 suppresses end ticks. For example:

axis.tickSize(6); // sets the major, minor and end to 6 
axis.tickSize(6, 0); // sets major and minor to 6, end to 0
axis.tickSize(6, 3, 0); // sets major to 6, minor to 3, and end to 0

# axis.tickPadding([padding])

Set or get the padding between ticks and tick labels. If padding is specified, sets the padding to the specified value in pixels and returns the axis. If padding is not specified, returns the current padding which defaults to 3 pixels.

# axis.tickFormat([format])

Set or get the tick value formatter for labels. If format is specified, sets the format to the specified function and returns the axis. If format is not specified, returns the current format function, which defaults to null. A null format indicates that the scale's default formatter should be used, which is generated by calling scale.tickFormat. In this case, the arguments specified by ticks are likewise passed to scale.tickFormat.

See d3.format for help creating formatters. For example, axis.tickFormat(d3.format(",.0f")) will display integers with comma-grouping for thousands.

# axis.remove(selection)

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

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

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