StyleCode - Number Pipeline

This pipeline controls the pretty-printing of numbers. The main behaviour is determined by the numbers property.

• auto: collects all numbers within the same scope (a table column, a linechart series or axis, etc.) and picks a scale and precision. This is currently the default behaviour, unless overridden by the unit.
• simple: numbers are displayed as floating-point values with a certain number of trailing digits.
• thousands, millions and percent: like fixed, but values are divided by 1000, 1000000 and 100 respectively, and use a k, m or % suffix, respectively.
• scientific: numbers are displayed in scientific format X.FeY where Y is chosen so that X has exactly one digit.
• minutes and seconds use the separate “time value” pipeline

Selecting the scale and suffix

The common point between auto, simple, thousands, millions, percent and scientific is that they choose a scale and a suffix according to this table:

When numbers is auto, an algorithm examines a set of numbers and determines a scale among 10^9, 10^6, 10^3, 1, 10^-3, 10^-6 and 10^-9 (and associated prefixes b, m, k, ``, 10⁻³, 10⁻⁶ and 10⁻⁹), and a precision, by trying to get the most visually appealing reasult when this scale, prefix and precision are applied to all numbers in the set.

The details of this optimization are implementation-defined (outside the scope of this specification) but the general idea is that the algorithm attempts to minimize noise digits (displaying 1 as 1.00 creates two digits of noise) as well as lost digits (displaying 1.23 as 1 loses two digits of data).

Each number on an Envision dashboard belongs to exactly one set of numbers, which will be considered together for the purpose of this optimization. These sets are:

• All the numbers on a given axis of a plot or linechart tile.
• All the numbers on a given series.
• All the numbers in a given value of a table.

All other numbers are considered alone.

Selecting the precision

The number will be displayed in format "X.Y", and the precision determines the number of digits in Y (a value between 0 and 16). This is a form of rounding, so 10.996 displayed with a precision of 2 becomes "11.00".

If numbers is auto, this precision has already been selected in the previous step.

The algorithm computes the number of significant digits D by looking for a sequence 000 or 999 in the decimal expansion of the number. For example:

This number of significant digits D is then clamped between minPrecision and precision according to the following formula:

D = max(minPrecision, min(precision, D))

In other words: D should be between minPrecision and precision, and minPrecision wins.

Rendering the number

The rendering format is [unit-left][integer][decimal-sep][fraction][suffix][unit-right], where:

• [unit-left] is the value of unit, but only if unitPosition is left.
• [integer] is the integer portion of Number / Scale.
• [decimal-sep] is the value of fractionSeparator. It only appears if the number of significant digits D is non-zero.
• [fraction] is the fractional portion of Number / Scale, rounded to the number of significant digits D.
• [suffix] is the suffix determined along with the scale.
• [unit-right] is the value of unit, but only if unitPosition is right.

Digits in [integer] and [fraction] are combined in groups of three and separated by thousandSeparator.

Examples

Time Value pipeline

When the numbers property is minutes and seconds, a distinct pipeline is used that ignores all the other properties (except units). The rules are:

• For minutes, the value is interpreted as a number of minutes, rounded to the nearest integer, and displayed with a hh:mm format (d.hh:mm if it represented more than 24 hours).
• For seconds, the value is interpreted as a number of seconds and displayed with a mm:ss.f format (hh:mm:ss.f if it represented more than 60 minutes, d.hh:mm:ss.f if it represented more than 24 hours). The fractional portion is only included if necessary.

If provided, the unit is displayed according to unit and unitPosition rules.