Class pvc.options.axes.AnyNonHierarchicalCartesianAxis

For more information, see #fixedLength.

The value pvc.options.varia.AxisDomainScope#Row can only be specified if the axis has vertical orientation. Conversely, the value pvc.options.varia.AxisDomainScope#Column can only be specified if the axis has horizontal orientation.

A string value is converted to a number.

The value may be bigger or smaller than the actual length of the data.

By default, the domain of the axis is determined from the actual domain of the data. This and other options allow modifying the axis domain.

When the axis domain gets smaller than the data domain, and pvc.options.charts.CartesianChart#leafContentOverflow is set to auto, the default value, clipping is activated in the related plot panels and any overflown content is hidden.

Phase I

The phase I axis domain is determined by the following procedure:

1. If fixedLength is not specified:
   1. If neither fixedMin and fixedMax are specified, the axis domain is the data domain; option originIsZero may augment the axis domain, on one of its sides;
   2. If both fixedMin and fixedMax are specified, the axis domain is fully determined; it's length is implied; option originIsZero is ignored;
   3. If fixedMin is specified (and fixedMax is not) the axis domain minimum is fixedMin and the axis domain maximum is the data domain maximum, possibly corrected by option originIsZero;
   4. Else, (if fixedMax is specified and fixedMin is not,) the axis domain maximum is fixedMax and the axis domain minimum is the data domain minimum, possibly corrected by option originIsZero;
2. If fixedLength is specified, option originIsZero is ignored.

   The limits of the axis domain are determined as follows:

   1. If fixedMin is specified, the axis domain maximum is implied:
      
      max = fixedMin + fixedLength;
      
      options originIsZero, fixedMax are ignored; option domainAlign is ignored in this phase;
   2. If fixedMax is specified, the axis domain minimum is implied:
      
      min = fixedMax - fixedLength;
      
      option originIsZero is ignored; option domainAlign is ignored in this phase;
   3. Else, domainAlign is either specified or defaults to center. The axis domain is aligned to either the minimum, maximum or center of the data domain and then taken to have the specified fixed length.

      It is determined as follows:

      • If domainAlign is min, the axis domain minimum is that of the actual data and the axis domain maximum is implied:
        
        max = min(data) + fixedLength;
      • If domainAlign is max, the axis domain maximum is that of the actual data and the axis domain minimum is implied:
        
        min = max(data) - fixedLength;
      • Else, domainAlign is center, or defaults to it, and both axis domain limits are determined from the actual data domain, as follows:
        • min = center(data) - fixedLength / 2
        • max = center(data) + fixedLength / 2
        where center(data) is determined as:
        
        center(data) = (max(data) - min(data)) / 2.

Phase II

In phase II, additional options may modify the phase I axis domain.

If #domainRoundMode is nice, the axis domain is made "nice", by making sure that its ends are "nice" numbers.

If #ratio is specified (or a ratio is imposed due to #preserveRatio), the length of the axis domain is imposed by the length of the axis' range (a number of pixels). The axis domain is aligned relative to the phase I axis domain, according to the value of #domainAlign.

If #domainRoundMode is tick, the phase I axis domain is extended to include the calculated ticks and only then are the ratio and domainAlign options processed, so that the domain aligns to the calculated ticks.

Default

If a sliding window exists, it is its length pvc.options.SlidingWindow#length, otherwise, null.

For more information, see: #fixedMin, #fixedMax, #domainAlign, #ratio and #originIsZero.

The value is converted using the pvc.options.DimensionType#converter of the first dimension of the first role bound to the axis.

For example, if the base axis shows the category dimension, and the dimension is configured as type Date, and it uses the default converter, then it accepts:

• values of type number, representing milliseconds as returned by the JavaScript's Date.getTime() method;
• values of type Date, which are accepted as is;
• values of type string, in a format defined by the dimension's pvc.options.DimensionType#rawFormat.

The value may be bigger or smaller than the maximum value of the data domain.

For more information, see #fixedLength.

The value is converted using the pvc.options.DimensionType#converter of the first dimension of the first role bound to the axis.

For example, if the base axis shows the category dimension, and the dimension is configured as type Date, and it uses the default converter, then it accepts:

• values of type number, representing milliseconds as returned by the JavaScript's Date.getTime() method
• values of type Date, which are accepted as is
• values of type string, in a format defined by the dimension's pvc.options.DimensionType#rawFormat.

The value may be bigger or smaller than the minimum value of the data domain.

For more information, see #fixedLength.

The properties fixedMin and fixedMax have precedence over this one.

If this property is true and respecting it would require changing the minimum value, but the option fixedMin is also specified, then this property is ignored. The same would apply if it were required to change the maximum value, but the property fixedMax was also specified.

For more information, see: #fixedLength.

When using a sliding window for real time applications, the ratio preservation allows for a stable visualization, regardless of the data values provided.

When preserveRatio is specified, following renders will use the effective ratio of the first render, whether the ratio was initially fixed using ratio or not.

See pvc.options.SlidingWindow.

Default

See #ratio.

This option works best with a pvc.options.varia.AxisDomainRoundingMode#None value of none:

When true, it is ensured that the ticks of each new render are aligned with the ticks of the previous render, sharing values if possible.

When false, the ticks will be rendered following the domain of the data and not taking in account previous tick values.

Default

This property can be defined as a number or a string.

For example, if the desired correspondence is that 100 pixels (range) represent 25 days (domain), the option can be specified with any of the following equivalent forms:

• ratio = "100/25d"; or
• ratio = "100/216e7" ( "25d" = 216e7 milliseconds); or
• ratio = 4.63e-8.

For more information, see #fixedLength and #preserveRatio.

A positive integer, possibly infinite.

Attention: This option is ignored when #tickUnit is specified!

Depending on the domain values extent, the labels' font size, the available space, the axis' orientation, and the minimum label spacing (given by AnyNonHierarchicalCartesianAxis#labelSpacingMin), a maximum number of ticks is implied.

The value of desiredTickCount is clamped to this layout imposed maximum.

When specified and finite, the tick calculation algorithm chooses, amongst possible tick units, the one that results in a number of ticks that is closest to the specified desired value.

When specified and infinite ( Infinity), the layout imposed maximum is used instead.

The minimum tick count

This actually depends on the value of #domainRoundMode.

• domainRoundMode is pvc.options.varia.AxisDomainRoundingMode#Tick

  For tick counts greater than two or three, the algorithm strives to satisfy the user's desire!

  However, the algorithm always generates at least two or three ticks, ignoring both desiredTickCount and labelSpacingMin, if needed.

  At least three ticks are generated for numeric domains having both negative and positive data. There are also temporal domain cases where a minimum of three ticks are generated.

  When the labels of these ticks really overlap, one of the labels is kept visible and the other(s) is hidden.

  This behavior ensures that, unless it is really impossible to do so, the axis serves one of its main purposes - allowing to translate visual lengths.

  When three tick labels overlap, the middle label is kept visible and the end labels are hidden.

  When two tick labels overlap, one of the labels — the one with tick value 0, if any, or the first one, if none — is kept visible and the other is hidden.

• domainRoundMode is pvc.options.varia.AxisDomainRoundingMode#None or pvc.options.varia.AxisDomainRoundingMode#Nice

  The algorithm always generates at least one tick.

Specifying a value of 1 results in the minimum possible tick count.

Domain type specifics

• Numeric

  When unspecified, the default value is Infinity.

• Temporal

  The value must be less than or equal to 10.

  When unspecified, the default value is 5.

See #tickUnit for more information.

When a number, it must be a non-negative, finite, integer.

• Numeric axis

  Specified values are rounded down to one of the standard precisions: a number that is an integer power of 10, multiplied by 1, 2 or 5 (e.g. 0.1, 0.2, 0.5, 1, 2, 5, 10, 20, 50, ...).

• Temporal axis

  When a number or numeric string is specified, it is a the number of milliseconds of a duration.

  It is rounded down to an integer and used directly. By default, the corresponding tick format will be the one of the greatest standard unit that is below the specified value.

  When a (non-numeric) string is specified, it should be the code of a standard precision, optionally immediately preceded by an integer multiple (e.g. '25d' means twenty five days).

  The standard time precision codes are defined in pvc.options.varia.TimeInterval

  This option should be used instead of the now deprecated pvc.options.marks.QuantitativeScaleExtensionPoint#dateTickPrecision extension point, via #extensionPoints and then scale.

When both #tickUnitMin and #tickUnitMax are specified, and the former is greater than or equal to the later, then it is as if tickUnit had been specified with the value of tickUnitMin.

When both tickUnit and #tickUnitMin are specified, and tickUnit is less than tickUnitMin, then the value of tickUnitMin is used instead.

When both tickUnit and #tickUnitMax are specified, and tickUnit is greater than tickUnitMax, then the value of tickUnitMax is used instead.

When specified or implied, both #desiredTickCount and labelSpacingMin are ignored.

See related axis options: #tickUnitMin, #tickUnitMax, #domainRoundMode, #desiredTickCount and AnyNonHierarchicalCartesianAxis#labelSpacingMin.

For numeric axes, see also NumericCartesianAxis#tickExponentMin and NumericCartesianAxis#tickExponentMax.

Use this option to ensure that ticks are separated by at most a certain value. For example, a value of 100 ensures that the unit 200 will not be used, and of '3m' that a year or semester unit will not be used.

As another example, to ensure that the tick unit is less than 1000, either specify a tickUnitMax of 900, or, maybe better, specify a NumericCartesianAxis#tickExponentMax of 2.

When a number, it must be a positive integer.

The same value parsing rules of #tickUnit apply to this option.

For numeric axes, the value of this option is combined with that of NumericCartesianAxis#tickExponentMax, resulting in the most restrictive one being used.

See #tickUnit for more information.

Use this option to ensure that ticks are separated by a minimum value. For example, a value of 1 ensures ticks are integers, and of 'd', that hour ticks are not used.

When a number, it must be a non-negative finite integer.

The same value parsing rules of #tickUnit apply to this option, with the exception that rounding to a standard precision is performed up.

For numeric axes, the value of this option is combined with that of NumericCartesianAxis#tickExponentMin, resulting in the most restrictive one being used.

See #tickUnit for more information.

The value of this option is combined with that of #tickUnitMax, resulting in the most restrictive one being used.

The generated ticks are separated by a step value. A step value is a certain power of 10, possibly multiplied by 2 or 5.

For example, for a chosen exponent of 4, the corresponding power of 10 is 10^4=10000 and the generated ticks could be: 0, 10000, 20000, ...

If the multiplier 5 was chosen, those ticks would instead be: 0, 50000, 100000, ...

Setting this property allows imposing a limit on the size of numbers chosen to separate ticks, which may be seen as imposing a minimum granularity on the generated tick values.

See #tickUnit for more information.

The value of this option is combined with that of #tickUnitMax, resulting in the most restrictive one being used.

The generated ticks are separated by a step value. A step value is a certain power of 10, possibly multiplied by 2 or 5.

For example, for a chosen exponent of 2, the corresponding power of 10 is 10^2=100 and the generated ticks could be: 0, 100, 200, ...

If the multiplier 2 was chosen, those ticks would instead be: 0, 200, 400, ...

Setting this property to 2 would ensure that generated ticks would be separated by the step values 100, 200 or 500, or by steps whose corresponding exponent is bigger than 2, like: 1000, 2000 or 5000.

A more typical use case is ensuring that generated ticks are integers. A value of tickExponentMin of 0 would accomplish that.

Generally, to impose a maximum number of decimal places on the generated ticks, a negative number can be specified. For example, the value -1 could generate the ticks: 0.1, 0.2, 0.3, ... If the multiplier 5 was chosen, those ticks would instead be: 0.5, 1.0, 1.5, ... It could not generate ticks with more that one decimal place.

See #tickUnit for more information.

An horizontal axis has a vertical zero line rule, while a a vertical axis has an horizontal zero line rule.

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.

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.

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.

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.

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.

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.

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

• showXScale
• showYScale
• showSecondScale

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.

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

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.

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