Using Error Bullets

XY #adapters #bullets #series #xy

Error bullets are special kind of bullets that help illustrate error margin for the particular series value. This tutorial will explain how you can add those to amCharts 4 series.

Adding error bullet

REQUIRED READING If you’re not familiar how bullets are used in amCharts 4, we suggest you run by “Bullets” article first.

To create an Error bullet we have a special class ErrorBullet.

It is added to series just like any other regular bullet: by creating (or pushing into) it in its bullets list.

let errorBullet = series.bullets.create(am4charts.ErrorBullet);
errorBullet.isDynamic = true;

var errorBullet = series.bullets.create(am4charts.ErrorBullet);
errorBullet.isDynamic = true;

{
  // ...
  "series": [{
    // ...
    "bullets": [{
      "type": "ErrorBullet",
      "isDynamic": true
    }]
  }]
}

Binding to axis scale

The purpose of error bullets is to show possible boundaries of value variations. This is why it cannot be just a simple, pixel-sized item.

We need to bind it to an actual scale.

For example, if we have a value 100 with an error margin of 10, we need to show error bullet that spans from 90 to 110.

To do that, we will be using a pixelHeight adapter on a bullet. Our custom function, will modify bullet’s height by accessing relative data points data context and specifically error value.

errorBullet.adapter.add("pixelHeight", function (pixelHeight, target) {
  let dataItem = target.dataItem;

  if(dataItem){
    let value = dataItem.valueY;
    let errorTopValue = value + dataItem.dataContext.error / 2;
    let errorTopY = valueAxis.valueToPoint(errorTopValue).y;

    let errorBottomValue = value - dataItem.dataContext.error / 2;
    let errorBottomY = valueAxis.valueToPoint(errorBottomValue).y;

    return Math.abs(errorTopY - errorBottomY);
   }
   return pixelHeight;
});

errorBullet.adapter.add("pixelHeight", function (pixelHeight, target) {
  var dataItem = target.dataItem;

  if(dataItem){
    var value = dataItem.valueY;
    var errorTopValue = value + dataItem.dataContext.error / 2;
    var errorTopY = valueAxis.valueToPoint(errorTopValue).y;

    var errorBottomValue = value - dataItem.dataContext.error / 2;
    var errorBottomY = valueAxis.valueToPoint(errorBottomValue).y;

    return Math.abs(errorTopY - errorBottomY);
   }
   return pixelHeight;
});

{
  // ...
  "series": [{
    // ...
    "bullets": [{
      "type": "ErrorBullet",
      "adapter": {
        "pixelHeight": function (pixelHeight, target) {
          var dataItem = target.dataItem;

          if(dataItem){
            var value = dataItem.valueY;
            var errorTopValue = value + dataItem.dataContext.error / 2;
            var errorTopY = valueAxis.valueToPoint(errorTopValue).y;

            var errorBottomValue = value - dataItem.dataContext.error / 2;
            var errorBottomY = valueAxis.valueToPoint(errorBottomValue).y;

            return Math.abs(errorTopY - errorBottomY);
           }
           return pixelHeight;
        }
      }
    }]
  }]
}

IMPORTANT It is important to set isDynamic = true for our bullets. It instructs the chart that this particular bullet is dependent on various factors such as scale changes and should be redrawn, instead of kept at constant size.

Configuring bullet

Since ErrorBullet is like any other Sprite-like element. There’s just one special property for Error bullet: errorLine.

It holds the lines elements that comprise the actual bracket - two threshold lines and one connector line.

If, say, we want to set the width of those lines, we can set strokeWidth property for errorLine.

errorBullet.errorLine.strokeWidth = 2;

errorBullet.errorLine.strokeWidth = 2;

{
  // ...
  "series": [{
    // ...
    "bullets": [{
      "type": "ErrorBullet",
      // ...
      "strokeWidth": 2
    }]
  }]
}

Horizontal error bullets

Making a bullet horizontal is easy: just set rotation = 90 and update its adapter function to use horizontal axis’ scale.

Here’s an example.

Asymmetric error bullets

Here’s another example which uses modified data and code for bullet sizing, to display asymmetric bullets.