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.

'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

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]
      }
    ]
https://app.zingsoft.com/demos/embed/B7ANBOBB
https://app.zingsoft.com/demos/embed/B7ANBOBB

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

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
      }
    ]
https://app.zingsoft.com/demos/embed/B7ANBOBB
https://app.zingsoft.com/demos/embed/B7ANBOBB

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
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
    }
}
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.