Using percent values in series

XY #data #formatters #labels #legend #series

In our everyday charting we mainly use absolute values. However, sometimes we might need to show how specific value relates to other elements. In this case relative percent value is much more representative than absolute one. This tutorial will explain ways we can use such relative values.

Intro

Let’s start with a fairly simple stacked column chart:

Right now, it operates using absolute values:

Value labels over columns.
Rollover tooltips.
Legend values: both when chart is static and when hovered over specific category.

Let’s see how we can use percent values instead.

Enabling percent calculation

Percent calculation is a costly operation in terms of CPU resources. Since in most cases it is not needed, it is disabled by default.

We’ll need to enable it for each series individually. For that we have calculatePercent - a property of Series.

Simply set it to true.

series.calculatePercent = true;

series.calculatePercent = true;

{
  // …
  "series": [{
    // …
    "calculatePercent": true
  }, {
    // …
    "calculatePercent": true
  }, {
    // …
    "calculatePercent": true
  }]
}

Now that we’ve enabled percent calculation, let’s see what we can do with it.

Data placeholders

As you probably are aware, we are using “data placeholders” (references in curly brackets) to insert dynamic data values in labels.

When we are referring to absolute values, we can just reference directly to a “data field” by its name, e.g.: {valueY}.

To show its percent representation, we need to use calculated value, which is referenced like this: {valueY.percent}.

Data labels

Data labels on columns are implemented by utilizing “label bullets”.

To make them show percent instead of absolute value, we will need to update text value of their label accordingly:

labelBullet.label.text = "{valueY.percent}%";

labelBullet.label.text = "{valueY.percent}%";

{  // ...  "series": [{    // ...    "bullets": [{      // ...      "label": {        // ...        "text": "{valueY.percent}%"      }    }]  }, {    // ...  }, {    // ...  }]}

Tooltips

It works for tooltips identically:

series.columns.template.tooltipText = "[bold]{name}[/]\n[font-size:14px]{categoryX}: [bold]{valueY.percent}%[/] ({valueY}M)";

series.columns.template.tooltipText = "[bold]{name}[/]\n[font-size:14px]{categoryX}: [bold]{valueY.percent}%[/] ({valueY}M)";

{  // ...  "series": [{    // ...    "columns": {      // ...      "tooltipText": "[bold]{name}[/]\n[font-size:14px]{categoryX}: [bold]{valueY.percent}% ({valueY}M)"    }  }, {    // ...  }, {    // ...  }]}

Legend

Same placeholder syntax can be used for legend as well:

series.legendSettings.itemValueText = "{valueY.percent}%";

series.legendSettings.itemValueText = "{valueY.percent}%";

{  // ...  "series": [{    // ...    "legendSettings": {      "itemValueText": "{valueY.percent}%"    }  }, {    // ...  }, {    // ...  }]}