Number Formatting
Overview
ZingChart gives you the tools you need to properly format unwieldy numbers, allowing you to manage values that may be too big or too small through the use of scientific notation, short units, and more. Note that the examples are not exhaustive, and these attributes can be used in more than one place. Refer to our JSON configuration for a full list of attributes available on each ZIngChart element.
Formatting Data
Larger numbers can be formatted in a way that increases readability. ZingChart allows you to format large numbers using scientific notation and short units.
Scientific Notation
Scientific notation is great for formatting very large, and incredibly small numbers. Using scientific notation, you can turn 602,200,000,000,000,000,000,000 into 6.02e+23. It’s also worth noting that ZingChart uses e-notation as opposed to using superscripted exponents to display scientific notation. This is why scientific notation in ZingChart appears in the form of 6.02e+23 instead of 6.02x1023.
Setting the scale to use scientific notation is simple. Just set the exponent attribute to true within your scale object.
scaleY: {
minValue: 0,
maxValue: 1000000000000,
exponent: true
},
To format the value boxes in a similar fashion, we can include the same line in the value-box object.
plot: {
valueBox: {
exponent: true
}
},
Due to the nature of our data, we still don’t have the nicest looking numbers in our chart. We can change the number of digits that appear after the decimal, and while this may reduce the precision of our value boxes, it makes for a much nicer looking chart. To set the decimals, include the 'exponent-decimals' attribute within the value-box object (or any object that you’re trying to format).
plot: {
valueBox: {
exponent: true,
exponentDecimals: 2
}
},
Decimal Places and Rounding
Setting the number of decimal places is useful if your data is highly precise and you do not want chart real estate taken up with long numerical values. Use the decimals attribute to set the number of decimal places you would like your chart to display. ZingChart will automatically round values accordingly.
To set the number of decimal places on your data, add the decimals attribute within your series object. Note that this attribute will be inherited. In the demo below, see that the decimals attribute is set globally to 5, but reset to 4 in the tooltip and 2 for the first series of data. The second series of data inherits the decimals value from the plot object.
plot: {
decimals: 5,
tooltip: {
// set decimal place to 4 for hover
decimals: 4,
// ...
},
},
// plot values
series: [
{
// Set decimal place to 2 for displaying data on bars
decimals: 2,
values: [23.16373, 20.53461, 27.3670, 29.25498, 25.35467, 17.56438, 15.59788]
},
{
values: [23.16373, 20.53461, 27.3670, 29.25498, 25.35467, 17.56438, 15.59788]
}
]
Short Units
Implementing short units is another way of handling unwieldy values. By setting the short attribute to true within the object that you would like to format, ZingChart will automatically determine the short unit to use based on the values.
scaleY: {
minValue: 0,
maxValue: 1000000000000,
short: true
},
plot: {
valueBox: {
short: true
}
},
The short-unit attribute allows you to manually set which short unit to use when the short attribute is set to true. ZingChart will automatically adjust the displayed value based upon the short unit used. Available short units include k, K, m, M, b, and B.
scaleY: {
minValue: '0',
maxValue: '1000000000000',
short: true,
shortUnit: 'M'
},
Decimal Places
Setting the number of decimal places is useful if your data is highly precise and you do not want chart real estate taken up with long numerical values. Use the "decimals" attribute to set the number of decimal places you would like your chart to display. ZingChart will automatically round values accordingly.
To set the number of decimal places on your data, add the "decimals" attribute within your series object.
series: [
{
decimals: 2,
values: // data
}
]
Thousands Separators
By default, ZingChart does not include thousands separators in larger numbers. The thousands-separator attribute allows you to change that. This attribute accepts a string value that will be used as the separator.
scaleY: {
minValue: 0,
maxValue: 1000000000000,
short: true,
shortUnit: 'M',
thousandsSeparator: ', '
},
plot: {
valueBox: {
thousandsSeparator: ', '
}
},
Currency
If you ever find yourself using currency values on your scales, there are a few things that you can do to properly format them.
As you may have noticed, values don’t look quite right when using a dollar sign as part of the scale and value box values. When the values are negative, the negative symbol appears inside the currency symbol, which is not ideal. To remedy this, set the negation attribute to currency. Doing this will move the negative symbol to the outside of the currency symbol.
scaleY: {
minValue: '-100',
maxValue: '100',
format: '$%v',
negation: 'currency'
},
plot: {
valueBox: {
text: '$%v',
negation: 'currency'
}
},
Date/Time
ZingChart uses Unix time, or the number of milliseconds that have elapsed since January 1, 1970 GMT, for date and timestamps. Formatting time series data into a traditional date/time format makes use of the transform object to manipulate Unix time into a more readable form. Using this helpful tool, we were able to find that the Unix time for 1 second after July 5th, 2013 looks like this: 1372982401000. Even if you were familiar with Unix time, it would still be difficult to determine what that timestamp represents.
Including the transform object within the scale object allows us to set the type to date so that ZingChart knows to transform the Unix time into a date.
scaleX: {
minValue: 1372982401000,
step: 2629743000,
transform: {
type: 'date'
}
},
It is also possible to manipulate the format of the date using the all attribute along with the available tokens.
scaleX: {
minValue: 1372982401000,
step: 2629743000,
transform: {
type: 'date',
all: '%m.%d.%Y'
}
},
| Token | Description |
|---|---|
| %q | Displays milliseconds. |
| %s | Displays seconds. |
| %i | Displays minutes. |
| %H | Displays the hour in 24-hour format with a leading 0 if the hour is single digit. |
| %h | Displays the hour in 12-hour format with a leading 0 if the hour is single digit. |
| %G | Displays the hour in 24-hour format without a leading 0. |
| %g | Displays the hour in 12-hour format without a leading 0. |
| %D | Displays the day of the week in abbreviated form. |
| %d | Displays the day's date without a leading 0 if the date is single digit. |
| %dd | Displays the day's date with a leading 0 if the date is single digit. |
| %M | Displays the month in abbreviated form. |
| %m | Displays the month numerically without a leading 0 if the month is single digit. |
| %mm | Displays the month numerically with a leading 0 if the month is single digit. |
| %Y | Displays the year in 4 digit format. |
| %y | Displays the year in 2 digit format. |
Floating items can be styled using many of the same styling attributes used by other objects. For more details, please visit our JSON Syntax page.
To disable the floating items, include the item object within transform and set visible to false.
transform: {
type: 'date',
all: '%m.%d.%Y',
item: {
visible: false
}
}
Summary
ZingChart makes it easy to manage numbers that would otherwise be difficult to handle and display.
Don't forget, a comprehensive list of available attributes and objects can be found on our JSON Syntax page.