Number Format

FusionCharts Suite XT offers multiple options to format numbers on the chart. You can configure number prefixes & suffixes, decimal places, and scale numbers based on a pre-defined scale.

This section talks about:

  • Number formatting basics

    • Configuring decimal places (rounding off)

    • Configuring decimal places (rounding off with trailing zeroes)

    • Automatic number formatting

    • Setting custom thousand and decimal separator character

    • Configuring thousand separator position

    • Adding number prefix and suffix

  • Number Scaling

    • Basic example

    • Adding billions to default scaling

    • Putting time in scale

    • Storage size example

    • Recursive number scaling

Number formatting basics

Configuring decimal places (rounding off)

A column 2D chart with values rounded off to two decimal places looks as below:

FusionCharts should load here..

Given below are the attributes used to configure decimal places:

Attribute Name Description
decimals Number of decimal places to which all numbers on the chart will be rounded off to. Valid range is from 0 to 10.
yAxisValueDecimals If you've disabled automatic adjustment of div lines, you can specify the div line values decimal precision using this attribute. Valid range is from 0 to 10.
xAxisValueDecimals If you've opted not to adjust vertical div lines, you can specify the decimal precision of the div line values using this attribute. Valid range is from 0 to 10.

The data structure used, in the chart above, to configure decimal places is given below:

...

Configuring decimal places (rounding off with trailing zeroes)

A column 2D chart with trailing zeroes will look as below:

FusionCharts should load here..

Given below are the attribute needed to force trailing zeroes:

Attribute Name Description
forceDecimals Set this to 1, to add/retain trailing zeroes so that all figures on the chart have the same number of digits after the decimal point. And 0, to keep the numbers as is.
forceYAxisValueDecimals Set this to 1, to add/retain trailing zeroes so that y-axis values have the same number of digits after the decimal point. And 0, to keep the numbers as is.
forceXAxisValueDecimals Set this to 1, to add/retain trailing zeroes so that x-axis values have the same number of digits after the decimal point. And 0, to keep the numbers as is.

The data structure used, in the chart above, to force trailing zeroes is given below:

...

Automatic number formatting

FusionCharts Suite XT automatically formats your numbers by adding K, M (Kilo, Million) and proper commas to the numbers. A column 2D chart with automatic number formatting will look as below:

FusionCharts should load here..

In the above example, the data for chart is 12523, 14570.230, 17375 and 18235.79. FusionCharts Suite XT automatically formats the number scaling to convert to K (Thousands) & M (Millions).

Given below are the attributes needed for removing automatic number formatting :

Attribute Name Description
formatNumber Set this to 0 , to remove the commas in all the numbers on the chart. Or 1(default) to add commas. The value of this attribute works only if yFormatNumber and xFormatNumber attributes are not specifically mentioned.
yFormatNumber Set this to 0 , to remove the commas in the numbers displayed on the y-axis. Or 1(default) to add commas. If this attribute is not specifically mentioned, the chart inherits the default value from formatNumber attribute.
xFormatNumber Set this to 0 , to remove the commas in the numbers displayed on the x-axis. Or 1(default) to add commas. If this attribute is not specifically mentioned, the chart inherits the default value from formatNumber attribute.
formatNumberScale Decides whether to add K (thousands) and M (millions) to a number after truncating and rounding it. Set this to 0, to disallow automatic formatting or 1 to allow it. The value of this attribute works only if yFormatNumberScale and xFormatNumberScale attributes are not specifically mentioned.
yFormatNumberScale Decides whether to add K (thousands) and M (millions) to y-axis values after truncating and rounding them. Set this to 0, to disallow automatic formatting or 1 to allow it. If this attribute is not specifically mentioned, the chart inherits the default value from formatNumberScale attribute.
xFormatNumberScale Decides whether to add K (thousands) and M (millions) to x-axis values after truncating and rounding them. Set this to 0, to disallow automatic formatting or 1 to allow it. If this attribute is not specifically mentioned, the chart inherits the default value from formatNumberScale attribute.

The data structure used, in the chart above, for automatic number formatting is given below:

...

Setting custom thousand and decimal separator character

By default, a '.' (dot) is used as decimal separator and a ',' (comma) is used as thousand separator character. A column 2D chart with the thousand and decimal separator characters swapped will look as below:

FusionCharts should load here..

Given below are the attributes used to customize the thousand and decimal separator characters:

Attribute Name Description
decimalSeparator Specifies the character to be used as the decimal separator in a number.
thousandSeparator Specifies the character to be used as the thousand separator in a number.
inDecimalSeparator In some countries, commas are used as decimal separators and dots as thousand separators. In data, if you specify such values, it will give an error while converting to number. So, FusionCharts XT accepts the input decimal and thousand separator for just display purposes, and converts it into the required format. This attribute lets you input the decimal separator.
inThousandSeparator In some countries, commas are used as decimal separators and dots as thousand separators. In data, if you specify such values, it will give an error while converting to number. So, FusionCharts XT accepts the input decimal and thousand separator from user, so that it can convert it accordingly into the required format. This attribute lets you input the thousand separator.

The data structure used, in the chart above, to swap/customize both the separator characters is given below:

...

Configuring thousand separator position

By default, a thousand separator character is placed in numbers greater than 999 after every third digit from the right. A column 2D chart with the thousand separator configured for multiple values will look as below:

FusionCharts should load here..

Given below is the attribute used to configure the thousand position value:

Attribute Name Description
thousandSeparatorPosition It specifies the number of digits after which the separator character should be placed. This attribute can take multiple values. In this case, the first thousand separator is placed after the number of digits specified by the second value. Thereafter, the separators are placed after the number of digits specified by the first value. When this attribute is set to 0, it takes the default value, which is 3, and places the separator after every three digits starting from right.

The data structure used, in the chart above, to configure the thousand position value is given below:

...

Adding number prefix and suffix

A column 2D chart with customized number prefix(set to $) and suffix(set to /day )looks as below:

FusionCharts should load here..

Given below are the attributes used to customize the number prefix and suffix:

Attribute Name Description
numberPrefix Specifies the prefix for all the numbers on the chart. The value of this attribute works only if yNumberPrefix and xNumberPrefix attributes are not specifically mentioned.
yNumberPrefix Specifies the prefix for all y-axis values on the chart. If this attribute is not specifically mentioned, the chart inherits the default value from numberPrefix attribute.
xNumberPrefix Specifies the prefix for all x-axis values on the chart. If this attribute is not specifically mentioned, the chart inherits the default value from numberPrefix attribute.
numberSuffix Specifies the suffix for all the numbers on the chart. The value of this attribute works only if yNumberSuffix and xNumberSuffix attributes are not specifically mentioned.
yNumberSuffix Specifies the suffix for all y-axis values on the chart. If this attribute is not specifically mentioned, the chart inherits the default value from numberSuffix attribute.
xNumberSuffix Specifies the suffix for all x-axis values on the chart. If this attribute is not specifically mentioned, the chart inherits the default value from numberSuffix attribute.

The data structure used, in the chart above, to customize the number prefix and suffix is given below:

...

[info]For dual y-axis charts, the primary axis performs number formatting and scaling by default. However, formatting and scaling have to be explicitly defined for the secondary axis. To define the formatting and scaling properties for the secondary axis, prefix 's' to the attribute name. So, numberPrefix becomes sNumberPrefix, forceYAxisValueDecimals becomes forceSYAxisValueDecimals, and so on.[/info]

Number Scaling

Number scaling lets you shorten the numbers on charts using commonly used scales (like K, M etc.). You can define your own scales for numbers and then apply it to all numbers on the chart.

Basic example

Let's start with the most basic example which is already defined in FusionCharts Suite XT- thousands (K) and millions (M) scale.

If you plot a chart with data as 1252322, 857023, 903753 and 1082357, the rendered chart looks as shown in the image below:

FusionCharts should load here..

Notice that FusionCharts Suite XT has scaled the numbers down to K. By default, FusionCharts Suite XT has the K, M (1000, 1000) scaling defined for each chart. Given below is the attribute used to allow automatic scaling:

Attribute Description
formatNumberScale Decides whether to add K (thousands) and M (millions) to a number after truncating and rounding it. Set this to 0, to disallow automatic formatting or 1 to allow it. The value of this attribute works only if yFormatNumberScale and xFormatNumberScale attributes are not specifically mentioned.

The data structure used, in the chart above, to format numbers is as follows:

...

The following sub-sections will demonstrate how you can define the scaling to suit your requirements:

Adding billions to default scaling

FusionCharts Suite XT does not have the scaling for billions defined. You will have to explicitly modify the number scaling to add billion.

This scale, in human terms, will look something as under:

1000 = 1 K, 1000 K = 1 M, 1000 M = 1 B

If you now plot a chart containing data in billions, the rendered chart looks as shown in the image below:

FusionCharts should load here..

Given below are the attributes used to add a billion scale:

Attribute Description
numberScaleValue This defines the conversion ratio from one unit to the next unit. This attribute along with the numberScaleUnit attribute defines the scale used for display. This is a comma separated list of numbers, e.g. "60, 60, 24, 7" for a minutes to hour to days conversion.
numberScaleUnit This defines the units of conversion from a lower unit to a higher unit. This has to be used along with the numberScaleValue attribute. Specified as a comma separated list, e.g. “Min, Hr, Day, Wk”.

Putting time in scale

Suppose we're plotting a chart which indicates the time taken by a list of automated processes. Each process in the list can take time ranging from a few seconds to few days. And we've the data for each process in seconds. Now, if we were to show all the data on the chart in seconds, it will become illegible.

What we can instead do is build a scale indicating time and then specify it to the chart. This scale, in human terms, will look something as under. A chart with the time scaled to minutes, hours or days looks as below:

FusionCharts should load here..

The data structure used, in the chart above, to configure time based scales for data values is as follows:

...

Storage size example

Let’s see another example. Suppose you're plotting a chart indicating free storage volume of a backup server over a span of 24 hours. The free storage volume can be from few bits to a few gigabytes. Again, you have all your data in bits - so we can render the range as under:

FusionCharts should load here..

Recursive number scaling

Recursive number scaling comes into the picture when you have number scales defined for your chart. It helps you display the chart data better by breaking-up the predefined number scale into smaller sections. For example, in a chart where time is being plotted, you can display 3.87 days as 3 days, 20 hours, 52 minutes and 25 seconds.

Let us build a chart which indicates the power back up used by a grocery store in a week. The power back up used for each day of the week can vary widely based on store operations. We have the data for each day in seconds. Now, if we were to show all the data on the chart in seconds, it will become illegible. What we can do is build a scale indicating time and then specify it to the chart.

The chart with recursive number scaling looks as below:

FusionCharts should load here..

Given below is the list of attributes used to enable recursive scaling:

Attribute Description
scaleRecursively Set this to 1 to enable recursive scaling such that data values are broken down into lower level units. Set this to 0 (default) to show value at the topmost unit level.
maxScaleRecursion Defines the number of steps of recursion allowed using an integer value. Set it to -1 to enable recursion to the lowest possible unit level.

The data structure used, in the chart above to recursively scale data values is as follows:

...

For Scatter and Bubble charts, xScaleRecursively, xMaxScaleRecursion, and xScaleSeparator attributes are used to scale the numbers recursively on the x-axis. These attributes will work only when the xAxisLabelMode attribute is set to AUTO or MIXED. To scale the numbers recursively on the secondary y-axis in a Dual Y-Axis chart, the attributes sScaleRecursively, sMaxScaleRecursion, and sScaleSeparator are used.