Package smile.plot.vega

Class Axis

java.lang.Object
smile.plot.vega.Axis
public class Axis extends Object
Axes provide axis lines, ticks, and labels to convey how a positional range represents a data range. Simply put, axes visualize scales.

By default, Vega-Lite automatically creates axes with default properties for x and y channels when they encode data fields. User can set the axis property of x- or y-field definition to an object to customize axis properties or set axis to null to remove the axis.

Besides axis property of a field definition, the configuration object (config) also provides axis config for setting default axis properties for all axes.

  • Method Summary

    Modifier and Type
    Method
    Description
    Axis
    aria(boolean flag)
    Sets if ARIA attributes should be included (SVG output only).
    Axis
    bandPosition(double position)
    For band scales, sets the interpolation fraction where axis ticks should be positioned.
    Axis
    description(String description)
    Sets the text description of this axis for ARIA accessibility (SVG output only).
    Axis
    domain(boolean flag)
    Sets if the domain (the axis baseline) should be included as part of the axis.
    Axis
    domainCap(String cap)
    Sets the stroke cap for the domain line's ending style.
    Axis
    domainColor(String color)
    Sets the color of axis domain line.
    Axis
    domainDash(double stroke, double space)
    Sets the alternating [stroke, space] lengths for dashed domain lines.
    Axis
    domainDashOffset(double offset)
    Sets the pixel offset at which to start drawing with the domain dash array.
    Axis
    domainOpacity(double opacity)
    Sets the opacity of the axis domain line.
    Axis
    domainWidth(double width)
    Sets the stroke width of axis domain line.
    Axis
    format(String format)
    Sets the text format.
    Axis
    formatType(String formatType)
    Sets the format type for labels.
    Axis
    grid(boolean flag)
    Sets if gridlines should be included as part of the axis.
    Axis
    gridCap(String cap)
    Sets the stroke cap for gridlines' ending style.
    Axis
    gridColor(String color)
    Sets the color of gridlines.
    Axis
    gridDash(double stroke, double space)
    Sets the alternating [stroke, space] lengths for dashed gridlines.
    Axis
    gridOpacity(double opacity)
    Sets the stroke opacity of grid.
    Axis
    gridWidth(double width)
    Sets the grid width.
    Axis
    labelAlign(String strategy)
    Sets the horizontal text alignment of axis tick labels.
    Axis
    labelAngle(double angle)
    Sets the rotation angle of the axis labels.
    Axis
    labelBaseline(String baseline)
    Sets the vertical text baseline of axis tick labels.
    Axis
    labelBound(boolean flag)
    Sets if labels should be hidden if they exceed the axis range.
    Axis
    labelBound(double tolerance)
    Sets the pixel tolerance of label bounding box.
    Axis
    labelColor(String color)
    Sets the color of the tick label.
    Axis
    labelExpr(String expr)
    Sets the Vega expression for customizing labels.
    Axis
    labelFlush(boolean flag)
    Sets if the first and last axis labels should be aligned flush with the scale range.
    Axis
    labelFlush(double adjustment)
    Sets the number of pixels by which to offset the first and last labels.
    Axis
    labelFlushOffset(double offset)
    Sets the number of pixels by which to offset flush-adjusted labels.
    Axis
    labelFont(String font)
    Sets the font of the tick label.
    Axis
    labelFontSize(double size)
    Sets the font size of the label in pixels.
    Axis
    labelFontStyle(String style)
    Sets the font style of the title.
    Axis
    labelFontWeight(int weight)
    Sets the font weight of axis tick labels.
    Axis
    labelFontWeight(String weight)
    Sets the font weight of axis tick labels.
    Axis
    labelLimit(int limit)
    Sets the maximum allowed pixel width of axis tick labels.
    Axis
    labelLineHeight(int height)
    Sets the line height in pixels for multi-line label text.
    Axis
    labelLineHeight(String height)
    Sets the line height for multi-line label text.
    Axis
    labelOffset(int offset)
    Sets the position offset in pixels to apply to labels, in addition to tickOffset.
    Axis
    labelOpacity(double opacity)
    Sets the opacity of the labels.
    Axis
    labelOverlap(boolean flag)
    Sets the strategy to use for resolving overlap of axis labels.
    Axis
    labelOverlap(String strategy)
    Sets the strategy to use for resolving overlap of axis labels.
    Axis
    labelPadding(double padding)
    Sets the padding in pixels between labels and ticks.
    Axis
    labels(boolean flag)
    Sets if labels should be included as part of the axis.
    Axis
    labelSeparation(double separation)
    Sets the minimum separation that must be between label bounding boxes for them to be considered non-overlapping (default 0).
    Axis
    maxExtent(int extent)
    Sets the maximum extent in pixels that axis ticks and labels should use.
    Axis
    minExtent(int extent)
    Sets the minimum extent in pixels that axis ticks and labels should use.
    Axis
    offset(double offset)
    Sets the offset, in pixels, by which to displace the axis from the edge of the enclosing group or data rectangle.
    Axis
    orient(String orient)
    Sets the orientation of the axis.
    Axis
    position(double position)
    Sets the anchor position of the axis in pixels.
    Axis
    style(String... style)
    Sets the custom styles to apply to the axis.
    Axis
    tickBand(String band)
    For band scales, sets if ticks and grid lines should be placed at the "center" of a band or at the band "extent"s to indicate intervals.
    Axis
    tickCap(String cap)
    Sets the stroke cap for tick lines' ending style.
    Axis
    tickColor(String color)
    Sets the color of the axis's tick.
    Axis
    tickCount(int count)
    Sets a desired number of ticks, for axes visualizing quantitative scales.
    Axis
    ticks(boolean flag)
    Sets whether the axis should include ticks.
    Axis
    title(String title)
    Sets a descriptive title.
    String
    toPrettyString()
    Returns the specification in pretty print.
    String
    toString()
     
    Axis
    translate(double translate)
    Sets the coordinate space translation offset for axis layout.
    Axis
    zindex(int zindex)
    Sets a non-negative integer indicating the z-index of the axis.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Method Details

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toPrettyString

      public String toPrettyString()
      Returns the specification in pretty print.
      Returns:
      the specification in pretty print.

    • title

      public Axis title(String title)
      Sets a descriptive title.
      Parameters:
      title - a descriptive title.
      Returns:
      this object.

    • aria

      public Axis aria(boolean flag)
      Sets if ARIA attributes should be included (SVG output only).
      Parameters:
      flag - A flag indicating if ARIA attributes should be included (SVG output only). If false, the "aria-hidden" attribute will be set on the output SVG group, removing the axis from the ARIA accessibility tree.
      Returns:
      this object.

    • bandPosition

      public Axis bandPosition(double position)
      For band scales, sets the interpolation fraction where axis ticks should be positioned.
      Parameters:
      position - An interpolation fraction indicating where, for band scales, axis ticks should be positioned. A value of 0 places ticks at the left edge of their bands. A value of 0.5 places ticks in the middle of their bands.
      Returns:
      this object.

    • description

      public Axis description(String description)
      Sets the text description of this axis for ARIA accessibility (SVG output only). If the aria property is true, for SVG output the "aria-label" attribute will be set to this description. If the description is unspecified it will be automatically generated.
      Parameters:
      description - the text description of this axis for ARIA accessibility.
      Returns:
      this object.

    • maxExtent

      public Axis maxExtent(int extent)
      Sets the maximum extent in pixels that axis ticks and labels should use. This determines a maximum offset value for axis titles.
      Parameters:
      extent - the maximum extent in pixels that axis ticks and labels should use.
      Returns:
      this object.

    • minExtent

      public Axis minExtent(int extent)
      Sets the minimum extent in pixels that axis ticks and labels should use. This determines a minimum offset value for axis titles.
      Parameters:
      extent - the minimum extent in pixels that axis ticks and labels should use.
      Returns:
      this object.

    • orient

      public Axis orient(String orient)
      Sets the orientation of the axis.
      Parameters:
      orient - "top", "bottom", "left" or "right".
      Returns:
      this object.

    • offset

      public Axis offset(double offset)
      Sets the offset, in pixels, by which to displace the axis from the edge of the enclosing group or data rectangle.
      Parameters:
      offset - the offset in pixels.
      Returns:
      this object.

    • position

      public Axis position(double position)
      Sets the anchor position of the axis in pixels.
      Parameters:
      position - the anchor position of the axis in pixels.
      Returns:
      this object.

    • translate

      public Axis translate(double translate)
      Sets the coordinate space translation offset for axis layout. By default, axes are translated by a 0.5 pixel offset for both the x and y coordinates in order to align stroked lines with the pixel grid. However, for vector graphics output these pixel-specific adjustments may be undesirable, in which case translate can be changed (for example, to zero).
      Parameters:
      translate - the coordinate space translation offset for axis layout.
      Returns:
      this object.

    • zindex

      public Axis zindex(int zindex)
      Sets a non-negative integer indicating the z-index of the axis. If zindex is 0, axes should be drawn behind all chart elements. To put them in front, set zindex to 1 or more.
      Parameters:
      zindex - a non-negative integer indicating the z-index of the axis.
      Returns:
      this object.

    • style

      public Axis style(String... style)
      Sets the custom styles to apply to the axis.
      Parameters:
      style - A string or array of strings indicating the name of custom styles to apply to the axis. A style is a named collection of axis property defaults defined within the style configuration. If style is an array, later styles will override earlier styles.
      Returns:
      this object.

    • domain

      public Axis domain(boolean flag)
      Sets if the domain (the axis baseline) should be included as part of the axis.
      Parameters:
      flag - A flag indicating if the domain (the axis baseline) should be included as part of the axis.
      Returns:
      this object.

    • domainCap

      public Axis domainCap(String cap)
      Sets the stroke cap for the domain line's ending style.
      Parameters:
      cap - "butt", "round" or "square".
      Returns:
      this object.

    • domainColor

      public Axis domainColor(String color)
      Sets the color of axis domain line.
      Parameters:
      color - the color of axis domain line.
      Returns:
      this object.

    • domainOpacity

      public Axis domainOpacity(double opacity)
      Sets the opacity of the axis domain line.
      Parameters:
      opacity - a value between [0, 1].
      Returns:
      this object.

    • domainWidth

      public Axis domainWidth(double width)
      Sets the stroke width of axis domain line.
      Parameters:
      width - the stroke width of axis domain line.
      Returns:
      this object.

    • domainDash

      public Axis domainDash(double stroke, double space)
      Sets the alternating [stroke, space] lengths for dashed domain lines.
      Parameters:
      stroke - the stroke length.
      space - the space length.
      Returns:
      this object.

    • domainDashOffset

      public Axis domainDashOffset(double offset)
      Sets the pixel offset at which to start drawing with the domain dash array.
      Parameters:
      offset - the pixel offset at which to start drawing with the domain dash array.
      Returns:
      this object.

    • format

      public Axis format(String format)
      Sets the text format. When used with the default "number" and "time" format type, the text formatting pattern for labels of guides (axes, legends, headers) and text marks.

      If the format type is "number" (e.g., for quantitative fields), this is D3's number format pattern. If the format type is "time" (e.g., for temporal fields), this is D3's time format pattern.

      Parameters:
      format - the text formatting pattern.
      Returns:
      this object.

    • formatType

      public Axis formatType(String formatType)
      Sets the format type for labels.
      Parameters:
      formatType - "number", "time", or a registered custom format type.
      Returns:
      this object.

    • labels

      public Axis labels(boolean flag)
      Sets if labels should be included as part of the axis.
      Parameters:
      flag - A flag indicating if labels should be included as part of the axis.
      Returns:
      this object.

    • labelAlign

      public Axis labelAlign(String strategy)
      Sets the horizontal text alignment of axis tick labels.
      Parameters:
      strategy - the horizontal text alignment of axis tick labels.
      Returns:
      this object.

    • labelAngle

      public Axis labelAngle(double angle)
      Sets the rotation angle of the axis labels.
      Parameters:
      angle - the rotation angle of the axis labels.
      Returns:
      this object.

    • labelBaseline

      public Axis labelBaseline(String baseline)
      Sets the vertical text baseline of axis tick labels.
      Parameters:
      baseline - "alphabetic", "top", "middle", "bottom", "line-top", or "line-bottom".
      Returns:
      this object.

    • labelBound

      public Axis labelBound(boolean flag)
      Sets if labels should be hidden if they exceed the axis range.
      Parameters:
      flag - If false (the default) no bounds overlap analysis is performed. If true, labels will be hidden if they exceed the axis range by more than 1 pixel.
      Returns:
      this object.

    • labelBound

      public Axis labelBound(double tolerance)
      Sets the pixel tolerance of label bounding box.
      Parameters:
      tolerance - the pixel tolerance: the maximum amount by which a label bounding box may exceed the axis range.
      Returns:
      this object.

    • labelColor

      public Axis labelColor(String color)
      Sets the color of the tick label.
      Parameters:
      color - the color of the tick label.
      Returns:
      this object.

    • labelExpr

      public Axis labelExpr(String expr)
      Sets the Vega expression for customizing labels. The label text and value can be assessed via the label and value properties of the axis's backing datum object.
      Parameters:
      expr - the Vega expression.
      Returns:
      this object.

    • labelFlush

      public Axis labelFlush(boolean flag)
      Sets if the first and last axis labels should be aligned flush with the scale range. Flush alignment for a horizontal axis will left-align the first label and right-align the last label. For vertical axes, bottom and top text baselines are applied instead.
      Parameters:
      flag - A flag if the first and last axis labels should be aligned flush with the scale range.
      Returns:
      this object.

    • labelFlush

      public Axis labelFlush(double adjustment)
      Sets the number of pixels by which to offset the first and last labels. The additional adjustment can sometimes help the labels better visually group with corresponding axis ticks.
      Parameters:
      adjustment - the number of pixels by which to offset the first and last labels.
      Returns:
      this object.

    • labelFlushOffset

      public Axis labelFlushOffset(double offset)
      Sets the number of pixels by which to offset flush-adjusted labels. Offsets can help the labels better visually group with corresponding axis ticks.
      Parameters:
      offset - the number of pixels by which to offset flush-adjusted labels.
      Returns:
      this object.

    • labelFont

      public Axis labelFont(String font)
      Sets the font of the tick label.
      Parameters:
      font - the font of the tick label.
      Returns:
      this object.

    • labelFontSize

      public Axis labelFontSize(double size)
      Sets the font size of the label in pixels.
      Parameters:
      size - the font size in pixels.
      Returns:
      this object.

    • labelFontStyle

      public Axis labelFontStyle(String style)
      Sets the font style of the title.
      Parameters:
      style - the font style of the title.
      Returns:
      this object.

    • labelFontWeight

      public Axis labelFontWeight(String weight)
      Sets the font weight of axis tick labels.
      Parameters:
      weight - the font weight of axis tick labels.
      Returns:
      this object.

    • labelFontWeight

      public Axis labelFontWeight(int weight)
      Sets the font weight of axis tick labels.
      Parameters:
      weight - the font weight of axis tick labels.
      Returns:
      this object.

    • labelLimit

      public Axis labelLimit(int limit)
      Sets the maximum allowed pixel width of axis tick labels.
      Parameters:
      limit - the maximum allowed pixel width of axis tick labels.
      Returns:
      this object.

    • labelLineHeight

      public Axis labelLineHeight(int height)
      Sets the line height in pixels for multi-line label text.
      Parameters:
      height - the line height in pixels for multi-line label text.
      Returns:
      this object.

    • labelLineHeight

      public Axis labelLineHeight(String height)
      Sets the line height for multi-line label text.
      Parameters:
      height - "line-top" or "line-bottom".
      Returns:
      this object.

    • labelOffset

      public Axis labelOffset(int offset)
      Sets the position offset in pixels to apply to labels, in addition to tickOffset.
      Parameters:
      offset - the position offset in pixels to apply to labels.
      Returns:
      this object.

    • labelOpacity

      public Axis labelOpacity(double opacity)
      Sets the opacity of the labels.
      Parameters:
      opacity - a value between [0, 1].
      Returns:
      this object.

    • labelOverlap

      public Axis labelOverlap(boolean flag)
      Sets the strategy to use for resolving overlap of axis labels. If false (the default), no overlap reduction is attempted. If set to true, a strategy of removing every other label is used (this works well for standard linear axes).
      Parameters:
      flag - a value between [0, 1].
      Returns:
      this object.

    • labelOverlap

      public Axis labelOverlap(String strategy)
      Sets the strategy to use for resolving overlap of axis labels. If set to "parity", a strategy of removing every other label is used (this works well for standard linear axes). If set to "greedy", a linear scan of the labels is performed, removing any labels that overlaps with the last visible label (this often works better for log-scaled axes).
      Parameters:
      strategy - "parity" or "greedy".
      Returns:
      this object.

    • labelPadding

      public Axis labelPadding(double padding)
      Sets the padding in pixels between labels and ticks.
      Parameters:
      padding - the padding in pixels between labels and ticks.
      Returns:
      this object.

    • labelSeparation

      public Axis labelSeparation(double separation)
      Sets the minimum separation that must be between label bounding boxes for them to be considered non-overlapping (default 0). This property is ignored if labelOverlap resolution is not enabled.
      Parameters:
      separation - the separation between label bounding boxes.
      Returns:
      this object.

    • grid

      public Axis grid(boolean flag)
      Sets if gridlines should be included as part of the axis.
      Parameters:
      flag - A flag indicating if gridlines should be included as part of the axis.
      Returns:
      this object.

    • gridCap

      public Axis gridCap(String cap)
      Sets the stroke cap for gridlines' ending style.
      Parameters:
      cap - "butt", "round" or "square".
      Returns:
      this object.

    • gridColor

      public Axis gridColor(String color)
      Sets the color of gridlines.
      Parameters:
      color - the color of gridlines.
      Returns:
      this object.

    • gridOpacity

      public Axis gridOpacity(double opacity)
      Sets the stroke opacity of grid.
      Parameters:
      opacity - a value between [0, 1].
      Returns:
      this object.

    • gridWidth

      public Axis gridWidth(double width)
      Sets the grid width.
      Parameters:
      width - the grid width in pixels.
      Returns:
      this object.

    • gridDash

      public Axis gridDash(double stroke, double space)
      Sets the alternating [stroke, space] lengths for dashed gridlines.
      Parameters:
      stroke - the stroke length.
      space - the space length.
      Returns:
      this object.

    • ticks

      public Axis ticks(boolean flag)
      Sets whether the axis should include ticks.
      Parameters:
      flag - A flag indicating if the axis should include ticks.
      Returns:
      this object.

    • tickBand

      public Axis tickBand(String band)
      For band scales, sets if ticks and grid lines should be placed at the "center" of a band or at the band "extent"s to indicate intervals.
      Parameters:
      band - "center" or "extent".
      Returns:
      this object.

    • tickCap

      public Axis tickCap(String cap)
      Sets the stroke cap for tick lines' ending style.
      Parameters:
      cap - "butt", "round" or "square".
      Returns:
      this object.

    • tickColor

      public Axis tickColor(String color)
      Sets the color of the axis's tick.
      Parameters:
      color - the color of the axis's tick.
      Returns:
      this object.

    • tickCount

      public Axis tickCount(int count)
      Sets a desired number of ticks, for axes visualizing quantitative scales.
      Parameters:
      count - A desired number of ticks, for axes visualizing quantitative scales.
      Returns:
      this object.