Class pvc.options.axes.DiscreteCartesianAxis
Extends
CartesianAxis.
| Constructor Attributes | Constructor Name and Description |
|---|---|
| <abstract> |
The options documentation class of the cartesian axis panel
for discrete scale type.
|
| Field Attributes | Field Name and Description |
|---|---|
| Discrete > General | |
|
Indicates the type of automatic content generated for the tooltip of axis' labels (applies to discrete axes).
|
|
|
Indicates if the axis' labels show tooltips (applies to discrete axes).
|
|
| Discrete > Layout | |
|
The size, in pixels, of the bands used to represent the discrete domain values (applies to discrete axes).
|
|
|
The maximum size, in pixels, of the bands used to represent the discrete domain values (applies to discrete axes).
|
|
|
The minimum size, in pixels, of the bands used to represent the discrete domain values (applies to discrete axes).
|
|
|
The ratio of the band size over the
total size (band + spacing),
in a discrete axis band (applies to discrete axes).
|
|
|
The space, in pixels, separating/surrounding bands (applies to discrete axes).
|
|
|
The maximum space, in pixels, separating/surrounding bands (applies to discrete axes).
|
|
|
The minimum space, in pixels, separating/surrounding bands (applies to discrete axes).
|
|
|
List of angles to try when overlappedLabelsMode is 'rotate' or 'rotatethenhide' (applies to normal discrete axes).
|
|
|
Controls the rotation direction of the labels (applies to normal discrete axes).
|
|
|
Controls how labels are laid out when they overlap (applies to normal discrete axes).
|
|
| Layout | |
|
The percentage padding,
on each of the sides of the plot panel
that are orthogonal to the axis orientation.
|
|
|
The position of the axis panel.
|
|
|
The fixed size of the panel, in pixel units or as a percentage.
|
|
|
The maximum size of the panel, in pixel units or as a percentage.
|
|
|
Indicates if the axis panel is shown.
|
|
| Style | |
|
The extension points object contains style definitions for
the marks of the panel.
|
|
|
The font used by the panel.
|
|
| <deprecated> |
Indicates if grid rules are drawn.
|
|
Indicates if grid rules are drawn
separating discrete values or
at each major continuous tick.
|
|
|
The axis title and title options.
|
|
| 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.
|
|
For additional information, please see CartesianAxis.
- Default Value:
- 'value'
- Default Value:
- true
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.
-
-
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.
See other band-control options: #bandSpacing, #bandSizeMin, #bandSizeMax, #bandSpacingMin, #bandSpacingMax and, for charts that give it representation, #bandSizeRatio.
A non-negative number.
See #bandSize for information on the band layout algorithm.
A non-negative number.
See #bandSize for information on the band layout algorithm.
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.
A non-negative number.
See #bandSize for information on the band layout algorithm.
A non-negative number.
See #bandSize for information on the band layout algorithm.
A non-negative number.
See #bandSize for information on the band layout algorithm.
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.
- Default Value:
- 'clockwise'
- Default Value:
- 'hide'
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
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
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
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
This property replaces the following (now deprecated) chart properties:
- showXScale
- showYScale
- showSecondScale
- Default Value:
- true
- Borrowed from:
- CartesianAxis
- Borrowed from:
- CartesianAxis
See the supported font format in http://www.w3.org/TR/CSS2/fonts.html#font-shorthand
- Borrowed from:
- CartesianAxis
- Deprecated:
- Use #grid instead.
- Default Value:
- false
- Borrowed from:
- CartesianAxis
- Default Value:
- false
- Borrowed from:
- CartesianAxis
- Borrowed from:
- CartesianAxis
- Context:
- {pvc.visual.Context}
- Arguments:
- {pvc.visual.Scene} scene
- The scene associated with the visual item.
- Returns:
- {undefined}
- Context:
- {pvc.visual.Context}
- Arguments:
- {pvc.visual.Scene} scene
- The scene associated with the visual item.
- Returns:
- {undefined}
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.
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