Formatting Numbers

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.


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.

'scale-y': {
    'min-value': "0",
    'max-value': "1000000000000",
    exponent: true
},

To format the value boxes in a similar fashion, we can include the same line in the "value-box" object.

plot: {
    'value-box': {
        exponent: true
    }
},
https://app.zingsoft.com/demos/embed/5U845B4W
https://app.zingsoft.com/demos/embed/5U845B4W

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: {
    'value-box': {
        exponent: true,
        'exponent-decimals':2
    }
},
https://app.zingsoft.com/demos/embed/KNM63LSN
https://app.zingsoft.com/demos/embed/KNM63LSN

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.

'scale-y': {
    'min-value': "0",
    'max-value': "1000000000000",
    short: true
},
plot: {
    'value-box': {
        short: true
    }
},
https://app.zingsoft.com/demos/embed/OCN9LQLF
https://app.zingsoft.com/demos/embed/OCN9LQLF

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.

'scale-y': {
    'min-value': "0",
    'max-value': "1000000000000",
    short: true,
    'short-unit': "M"
},
https://app.zingsoft.com/demos/embed/T0N5KD0M
https://app.zingsoft.com/demos/embed/T0N5KD0M

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.

'scale-y': {
    'min-value': "0",
    'max-value': "1000000000000",
    short: true,
    'short-unit': "M",
    'thousands-separator': ", "
},
plot: {
    'value-box': {
        'thousands-separator': ", "
    }
},
https://app.zingsoft.com/demos/embed/06EKAP77
https://app.zingsoft.com/demos/embed/06EKAP77

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.

'scale-y': {
    'min-value': "-100",
    'max-value': "100",
    format: "$%v",
    negation: "currency"
},
plot: {
    'value-box': {
        text: "$%v",
        negation: "currency"
    }
},
https://app.zingsoft.com/demos/embed/9BP7AGYX
https://app.zingsoft.com/demos/embed/9BP7AGYX

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.

https://app.zingsoft.com/demos/embed/XLI3FIC3
https://app.zingsoft.com/demos/embed/XLI3FIC3

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.

'scale-x': {
    'min-value':1372982401000,
    step:2629743000,
    transform: {
        type: "date"
    }
},
https://app.zingsoft.com/demos/embed/YSZ48X6Q
https://app.zingsoft.com/demos/embed/YSZ48X6Q

It is also possible to manipulate the format of the date using the "all" attribute along with the available tokens.

'scale-x': {
    'min-value':1372982401000,
    step:2629743000,
    transform: {
        type: "date",
        all: "%m.%d.%Y"
    }
},
https://app.zingsoft.com/demos/embed/8PFUY24Z
https://app.zingsoft.com/demos/embed/8PFUY24Z
TokenDescription
%qDisplays milliseconds.
%sDisplays seconds.
%iDisplays minutes.
%HDisplays the hour in 24-hour format with a leading 0 if the hour is single digit.
%hDisplays the hour in 12-hour format with a leading 0 if the hour is single digit.
%GDisplays the hour in 24-hour format without a leading 0.
%gDisplays the hour in 12-hour format without a leading 0.
%DDisplays the day of the week in abbreviated form.
%dDisplays the day's date without a leading 0 if the date is single digit.
%ddDisplays the day's date with a leading 0 if the date is single digit.
%MDisplays the month in abbreviated form.
%mDisplays the month numerically without a leading 0 if the month is single digit.
%mmDisplays the month numerically with a leading 0 if the month is single digit.
%YDisplays the year in 4 digit format.
%yDisplays 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
    }
}
https://app.zingsoft.com/demos/embed/65BSVLCK
https://app.zingsoft.com/demos/embed/65BSVLCK

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.