Class pvc.options.axes.NumericCartesianAxis

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.

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

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