Class pvc.options.axes.AnyDiscreteCartesianAxis

Extends DiscreteCartesianAxis.

Class Summary
Constructor Attributes	Constructor Name and Description
	AnyDiscreteCartesianAxis The options documentation class of the cartesian axis panel for any discrete scale type.

Field Summary
Field Attributes	Field Name and Description
Discrete > General
	composite Indicates if the axis should show discrete multi-dimensional data in a hierarchical form, when `true`, or a flattened form, when `false` (applies to discrete axes).
	tooltipAutoContent Indicates the type of automatic content generated for the tooltip of axis' labels (applies to discrete axes).
	tooltipEnabled Indicates if the axis' labels show tooltips (applies to discrete axes).
Discrete > Layout
	bandSize The size, in pixels, of the bands used to represent the discrete domain values (applies to discrete axes).
	bandSizeMax The maximum size, in pixels, of the bands used to represent the discrete domain values (applies to discrete axes).
	bandSizeMin The minimum size, in pixels, of the bands used to represent the discrete domain values (applies to discrete axes).
	bandSizeRatio The ratio of the band size over the total size (band + spacing), in a discrete axis band (applies to discrete axes).
	bandSpacing The space, in pixels, separating/surrounding bands (applies to discrete axes).
	bandSpacingMax The maximum space, in pixels, separating/surrounding bands (applies to discrete axes).
	bandSpacingMin The minimum space, in pixels, separating/surrounding bands (applies to discrete axes).
	labelDesiredAngles List of angles to try when overlappedLabelsMode is 'rotate' or 'rotatethenhide' (applies to normal discrete axes).
	labelRotationDirection Controls the rotation direction of the labels (applies to normal discrete axes).
	overlappedLabelsMode Controls how labels are laid out when they overlap (applies to normal discrete axes).
Layout
	offset The percentage padding, on each of the sides of the plot panel that are orthogonal to the axis orientation.
	position The position of the axis panel.
	size The fixed size of the panel, in pixel units or as a percentage.
	sizeMax The maximum size of the panel, in pixel units or as a percentage.
	visible Indicates if the axis panel is shown.
Non-Hierarchical > Layout
	labelSpacingMin The minimum spacing between tick labels, in em units (does not apply to discrete-hierarchical axes).
Non-Hierarchical > Style
	ticks Indicates if ticks are shown for each tick value (does not apply to discrete-hierarchical axes).
Style
	extensionPoints The extension points object contains style definitions for the marks of the panel.
	font The font used by the panel.
<deprecated>	fullGrid Indicates if grid rules are drawn.
	grid Indicates if grid rules are drawn separating discrete values or at each major continuous tick.
	title The axis title and title options.

Method Summary
Method Attributes	Method Name and Description
Discrete > Actions
	clickAction(scene) A callback function that is called when the user clicks on a tick label (applies to discrete axes).
	doubleClickAction(scene) A callback function that is called when the user double-clicks on a tick label (applies to discrete axes).
Discrete > General
	tooltipFormat(scene) A callback function that is called to build the tooltip of an axis' labels (applies to discrete axes).
Style
	tickFormatter(value, precision, index, label) A tick formatter function.

Class Detail

pvc.options.axes.AnyDiscreteCartesianAxis

The options documentation class of the cartesian axis panel for any discrete scale type.

For additional information, please see CartesianAxis.

Field Detail

{boolean} composite

Indicates if the axis should show discrete multi-dimensional data in a hierarchical form, when true, or a flattened form, when false (applies to discrete axes).

Flattened axes, present multi-dimensional roles by joining the multiple values' labels with the separator character: pvc.options.charts.BasicChart#groupedLabelSep.

Default Value:: false

{pvc.options.varia.TooltipAutoContent} tooltipAutoContent

Indicates the type of automatic content generated for the tooltip of axis' labels (applies to discrete axes).

Default Value:: 'value'

Borrowed from:: DiscreteCartesianAxis

{boolean} tooltipEnabled

Indicates if the axis' labels show tooltips (applies to discrete axes).

Default Value:: true

Borrowed from:: DiscreteCartesianAxis

{number} bandSize

The size, in pixels, of the bands used to represent the discrete domain values (applies to discrete axes).

A non-negative number.

In multi-charts

The current layout algorithm used by multi-charts does not support minimum, fixed or maximum sizes in small charts. As such, the simples band size ratio model always needs to be used.

The minimum, fixed and maximum sizes and spacings are used to determine an equivalent or best-possible band size ratio.

Band Size, Spacing, Ratio and Step

The band layout arranges bands and space in the following way. Taking B to represent bandSize, E to represent #bandSpacing and e to be E/2, bands and space will follow the pattern: eBe, eBEBe, eBEBEBe, ...

For a given pair of B and E, each discrete category will occupy a space given by the step, S:

S = B + E.

Given the number of discrete categories, a cartesian panel (axis or plot) will have corresponding fixed or minimum and maximum sizes.

The option #bandSizeRatio, R, is used, in under-constrained cases, to relate B and E:

B = R * S

Impact on chart size

If the chart size along the axis' dimension is such that the available space is less than the determined fixed or minimum size, then the chart will grow as much as needed to accommodate the fixed or minimum size, along that dimension.

If, on the contrary, the chart size along the axis' dimension is greater than the determined fixed or maximum size, the plot and axis content will be centered in the available space.

Option values harmonization

When both #bandSizeMax and #bandSizeMin are specified, and #bandSizeMax is less than or equal to bandSizeMin, then #bandSize is set to the the minimum value.

When both bandSize and #bandSizeMin are specified, and bandSize is less than bandSizeMin, then the minimum value is used instead.

When both bandSpacing and #bandSpacingMin are specified, and bandSpacing is less than bandSpacingMin, then the minimum value is used instead.

When both #bandSpacingMax and #bandSpacingMin are specified, and #bandSpacingMax is less than or equal to bandSpacingMin, then #bandSpacing is set to the the minimum value.

The algorithm

The options you specify should just behave as you'd expected them to. At least, after thinking about them for a while.

If doubts remain on which options and values should be specified, or on why the specified options are behaving in a certain way, you can follow this explanation of the band layout algorithm.

When both bandSize and #bandSpacing are specified, the layout is fixed.
When they both have the value 0, then the layout is reevaluated as if they had not been specified.
The option #bandSizeRatio is ignored.
When one and only one of bandSize or #bandSpacing is specified, the layout is partially fixed.
For the variable option, size or spacing, any specified minimum and/or maximum options are still considered.
This configuration does not define a fixed step size, but instead constrains the range of step size values.
The option #bandSizeRatio is ignored.
When neither bandSize nor #bandSpacing are specified, the layout is strictly variable.
There are several cases:
- When none of the minimum and maximum values, of both size and spacing, are specified, the size and spacing are governed solely by the #bandSizeRatio, R.
  This is the way the band layout used to behave, before the existence of the fixed, minimum and maximum options.
  Small-charts continue to behave this way, although with a band size ratio that is determined from the the other specified options.
  The half-line (E,B) departs from (0,0) and goes on indefinitely with a slope given by R: E = (1/R - 1) * B.
- When minimum and maximum values, of both size and spacing, are specified, the size and spacing are constrained to belong to the line segment (E,B), that goes from point (Emin,Bmin) to point (Emax,Bmax).
- When only the minimum size and spacing values are specified, the size and spacing are constrained to belong to the line segment (E,B), that goes from point (0,0) to point (Emin,Bmin).
- When only the maximum size and spacing values are specified, the size and spacing are constrained to belong to the line segment (E,B), that goes from point (0,0) to point (Emax,Bmax).
- In all the following mixed and under-constrained cases, option #bandSizeRatio, R, is taken into account.
  The size and spacing are constrained to belong to the the line (E,B) that passes through (0,0) and has a slope given by R: E = (1/R - 1) * B.
  Again, a few more cases:
  - When only the minimum and maximum size values are specified, the corresponding spacing values are implied.
  - When only the minimum and maximum spacing values are specified, the corresponding size values are implied.
  - When only the minimum size and the maximum spacing values are specified, the specified minimum size implies a minimum spacing and the specified maximum spacing implies a maximum size.
    If the implied minimum spacing is greater than or equal to the specified maximum spacing, the algorithm is reevaluated using a fixed spacing equal to the implied minimum spacing.
  - When only the maximum size and the minimum spacing values are specified, the specified maximum size implies a maximum spacing and the specified minimum spacing implies a minimum size.
    If the implied minimum size is greater than or equal to the specified maximum size, the algorithm is reevaluated using a fixed size equal to the implied minimum size.

See other band-control options: #bandSpacing, #bandSizeMin, #bandSizeMax, #bandSpacingMin, #bandSpacingMax and, for charts that give it representation, #bandSizeRatio.

Borrowed from:: DiscreteCartesianAxis

{number} bandSizeMax

The maximum size, in pixels, of the bands used to represent the discrete domain values (applies to discrete axes).

A non-negative number.

See #bandSize for information on the band layout algorithm.

Borrowed from:: DiscreteCartesianAxis

{number} bandSizeMin

The minimum size, in pixels, of the bands used to represent the discrete domain values (applies to discrete axes).

A non-negative number.

See #bandSize for information on the band layout algorithm.

Borrowed from:: DiscreteCartesianAxis

{number} bandSizeRatio

The ratio of the band size over the total size (band + spacing), in a discrete axis band (applies to discrete axes).

A number between 0 and 1.

The default value of this property is that of the legacy option panelSizeRatio, defined for the Bar-family, Box-Plot and the Heat-Grid charts.

This option is only used when the band model is under-constrained by the fixed, minimum, and maximum size and spacing options.

See #bandSize for information on the band layout algorithm.

Borrowed from:: DiscreteCartesianAxis

{number} bandSpacing

The space, in pixels, separating/surrounding bands (applies to discrete axes).

A non-negative number.

See #bandSize for information on the band layout algorithm.

Borrowed from:: DiscreteCartesianAxis

{number} bandSpacingMax

The maximum space, in pixels, separating/surrounding bands (applies to discrete axes).

A non-negative number.

See #bandSize for information on the band layout algorithm.

Borrowed from:: DiscreteCartesianAxis

{number} bandSpacingMin

The minimum space, in pixels, separating/surrounding bands (applies to discrete axes).

A non-negative number.

See #bandSize for information on the band layout algorithm.

Borrowed from:: DiscreteCartesianAxis

{number|string|list(number|string)} labelDesiredAngles

List of angles to try when overlappedLabelsMode is 'rotate' or 'rotatethenhide' (applies to normal discrete axes).

The nearest above the minimum non-overlapping angle is chosen, or just the nearest if none is bigger. If no desired angle is provided, it defaults to the minimum non-overlapping angle.

{pvc.options.varia.AxisLabelRotationDirection} labelRotationDirection

Controls the rotation direction of the labels (applies to normal discrete axes).

Default Value:: 'clockwise'

{pvc.options.varia.AxisOverlappedLabelsMode} overlappedLabelsMode

Controls how labels are laid out when they overlap (applies to normal discrete axes).

Default Value:: 'hide'

{number} offset

The percentage padding, on each of the sides of the plot panel that are orthogonal to the axis orientation.

The percentage is a number greater than or equal to 0 and less than 1. It is relative to length of the plot's side that has the same direction as the axis.

The padded area is useful to leave enough free space between the plot's visual elements and the axes panels.

If an axis is horizontal, the padding affects the left and right sides, and if it is vertical, affects the top and bottom sides.

If more than one axis of a given orientation specifies an offset, the maximum specified offset is used.

Default Value:: 0

Borrowed from:: CartesianAxis

{pvc.options.varia.PanelPosition} position

The position of the axis panel.

The default value depends on the orientation and index of the axis. For an horizontal axis, it is bottom. For an vertical axis, it is left. For axes other than the first, the default side is the opposite of that of the first axis: top for the horizontal axes and right for the vertical axes.

Borrowed from:: CartesianAxis

{number|string|pvc.options.varia.Size} size

The fixed size of the panel, in pixel units or as a percentage.

If a size object is specified, only the component orthogonal to the axis orientation is considered.

See pvc.options.varia.Size for information about the different supported data types.

Borrowed from:: CartesianAxis

{number|string|pvc.options.varia.Size} sizeMax

The maximum size of the panel, in pixel units or as a percentage.

If a size object is specified, only the component orthogonal to the axis orientation is considered.

See pvc.options.varia.Size for information about the different supported data types.

Borrowed from:: CartesianAxis

{boolean} visible

Indicates if the axis panel is shown.

This property replaces the following (now deprecated) chart properties:

showXScale
showYScale
showSecondScale

Default Value:: true

Borrowed from:: CartesianAxis

{number} labelSpacingMin

The minimum spacing between tick labels, in em units (does not apply to discrete-hierarchical axes).

Attention: In continuous axes, this option is ignored when AnyContinuousCartesianAxis#tickUnit is specified, or when only two or three ticks are used!

See AnyContinuousCartesianAxis#tickUnit for more information.

{boolean} ticks

Indicates if ticks are shown for each tick value (does not apply to discrete-hierarchical axes).

Default Value:: true

{pvc.options.ext.AnyDiscreteCartesianAxisExtensionPoints} extensionPoints

The extension points object contains style definitions for the marks of the panel.

{string} font

The font used by the panel.

See the supported font format in http://www.w3.org/TR/CSS2/fonts.html#font-shorthand

Borrowed from:: CartesianAxis

<deprecated> {boolean} fullGrid

Indicates if grid rules are drawn.

Deprecated:
Use #grid instead.

Default Value:: false

Borrowed from:: CartesianAxis

{boolean} grid

Indicates if grid rules are drawn separating discrete values or at each major continuous tick.

Default Value:: false

Borrowed from:: CartesianAxis

{string|pvc.options.panels.CartesianAxisTitlePanel} title

The axis title and title options.

Borrowed from:: CartesianAxis

Method Detail

{undefined} clickAction(scene)

A callback function that is called when the user clicks on a tick label (applies to discrete axes).

Context:: {pvc.visual.Context}

Arguments:
{pvc.visual.Scene} scene: The scene associated with the visual item.

Returns:: {undefined}

Borrowed from:: DiscreteCartesianAxis

{undefined} doubleClickAction(scene)

A callback function that is called when the user double-clicks on a tick label (applies to discrete axes).

Context:: {pvc.visual.Context}

Arguments:
{pvc.visual.Scene} scene: The scene associated with the visual item.

Returns:: {undefined}

Borrowed from:: DiscreteCartesianAxis

{string} tooltipFormat(scene)

A callback function that is called to build the tooltip of an axis' labels (applies to discrete axes).

If the chart's pvc.options.Tooltip#html is true, the resulting text must be valid HTML, otherwise, it is considered plain text.

When unspecified and #tooltipEnabled is true a tooltip is automatically generated according to the value of #tooltipAutoContent.

Context:: {pvc.visual.Context}

Arguments:
{pvc.visual.Scene} scene: The scene whose tooltip is to be built.
Use the data contained in the scene object to build the tooltip.

Returns:: {string} The tooltip text.

Borrowed from:: DiscreteCartesianAxis

{string} tickFormatter(value, precision, index, label)

A tick formatter function.

This function has two arguments variants:

continuous: tickFormatter(value, precision, index)
discrete: tickFormatter(value, label)

Generally, a continuous axis uses the continuous variant and a discrete axis uses the discrete variant.

But, there is one exception to this rule: a discrete axis having a single date dimension, uses the continuous variant. This makes it easier to format date categories, by automatically choosing an adequate precision, that takes the actual data range into account. It's also legacy, version 1, behavior. Use the compatibility flag pvc.options.varia.CompatibilityFlags#discreteTimeSeriesTickFormat to disable this formatting mode.

Summing up:

a continuous axis uses the continuous arguments variant,
a discrete axis can use both arguments variant,
an axis with a single date dimension, uses the continuous arguments variant (if pvc.options.varia.CompatibilityFlags#discreteTimeSeriesTickFormat is true).

Context object

The function is called having as this the ticks array, whose tick values are being formatted.

Together with the index argument, it is possible to use the value of the previous and/or following ticks to format the current tick.

The ticks array provides the following useful properties:

step — the used precision
base — the base precision from which step is derived
mult — the multiple of base precision that yields step (step = base * mult)
format(v) - the default formatting function
length — the number of ticks

Context:: {Array}

Arguments:

{string|number|Date} value

The value to format.

continuous arguments variant

The type of argument value can be number or Date.

discrete arguments variant

The type of argument value can be string or number.

When the axis has a single dimension, argument value is the value of that dimension.

When the axis has more than one dimension, and is flattened, argument value is the junction of the key values of all dimensions, separated by pvc.options.charts.BasicChart#dataSeparator.

When the axis is hierarchical (composite), argument value is the key value of the dimension at a certain level.

{number} precision Optional

The precision in which the value argument should be formatted.

ATTENTION: only present in the continuous arguments variant!

When the axis has a date scale type, the argument is the chosen number of milliseconds between tick values.

The standard time precisions are defined in: pvc.options.varia.TimeInterval.

In general, the given precision is an integer multiple of one the standard precisions. It is many times more useful to use the base standard precision on which the final precision is based on (the value of the context property this.base).

When the axis has a numeric scale type, the argument is the number of decimal places of the chosen step value.

{number} index Optional

The index of the tick being formatted.

ATTENTION: only present in the continuous arguments variant!

You may use the index to access neighbouring ticks from the this ticks array (e..g. this[index + 1]).

{string} label Optional

The default label.

ATTENTION: only present in the discrete arguments variant!

The default label is the label that would be displayed if the tick formatter had not been specified.

When the axis has a single dimension, argument label is the label as formatted by that dimension.

When the axis has more than one dimension, and is flattened, argument label is the junction of the label values of all dimensions, separated by pvc.options.charts.BasicChart#groupedLabelSep.

When the axis is hierarchical (composite), argument label is the label as formatted by the dimension at a certain level.

Returns:: {string} The string that is the formatted value.

Borrowed from:: CartesianAxis

Types By Namespace

cdo

def

pvc

pvc.data

pvc.options

pvc.options.axes

pvc.options.charts

pvc.options.ext

pvc.options.format

pvc.options.marks

pvc.options.panels

pvc.options.plots

pvc.options.varia

pvc.options.visualRoles

pvc.visual

Class pvc.options.axes.AnyDiscreteCartesianAxis