@nebula.js/sn-bullet-chart

The bullet chart displays a gauge with extended options. Bullet charts can be used to visualize and compare performance of a measure to a target value and to a qualitative scale, such as poor, average, and good.

Requirements

Requires @nebula.js/stardust version 1.7.0 or later.

Installing

If you use npm: npm install @nebula.js/sn-bullet-chart. You can also load through the script tag directly from https://unpkg.com.

Usage

In the example below, the sales in different quarters are compared using a bullet chart.

import { embed } from '@nebula.js/stardust';
import bulletChart from '@nebula.js/sn-bullet-chart';

// 'app' is an enigma app model
const nuked = embed(app, {
  types: [
    {
      // register bullet chart
      name: 'bullet-chart',
      load: () => Promise.resolve(bulletChart),
    },
  ],
});

// Rendering a simple bullet chart
nuked.render({
  element: document.querySelector('.bullet'),
  type: 'bullet-chart',
  fields: ['Quarter', '=Sum(Sales)'],
  properties: {
    title: 'Sales by Quarters',
  },
});

You can create a bullet chart with one dimension and one measure, or no dimension and multiple measures.

| Dimensions | Measures | Results | | ---------- | -------- | ---------------------------------------------------------------------------------------- | | 1 | 1 | A bullet chart with columns corresponding to different values in the dimension | | 0 | n | A bullet chart with columns corresponding to the measures, aggreated over the dimension. |

More examples

Horizontal bullet chart with common range

Sometime it is easier for the eyes to perceive the information from a bullet chart if it is horizontal and its measure has a common range.

// Render a bullet chart horizontally, and with common range
nuked.render({
  element: document.querySelector('.bullet'),
  type: 'bullet-chart',
  fields: ['Quarter', '=Sum(Sales)'],
  properties: {
    title: 'Sales by Quarters',
    orientation: 'horizontal',
    measureAxis: {
      commonRange: true,
      dock: 'near',
    },
  },
});

Adding target

By adding targets, you can compare not only the sales between different quarters but also the sale of each quarter to its sale target.

// Rendering a bullet chart with targets
nuked.render({
  element: document.querySelector('.bullet'),
  type: 'bullet-chart',
  fields: ['Quarter'],

  // Define `qMeasures` in `properties` instead of in `fields`
  properties: {
    title: 'Sales by Quarters',
    qHyperCubeDef: {
      qMeasures: [
        {
          qDef: {
            qDef: 'Sum(Sales)',
            target: 'Sum([Sale targets])',
          },
          qSortBy: {
            qSortByNumeric: -1,
          },
          qAttributeExpressions: [
            {
              qExpression: 'Sum([Sale targets])',
              id: 'bullet-target',
            },
          ],
        },
      ],
      qInitialDataFetch: [
        {
          qLeft: 0,
          qTop: 0,
          qWidth: 15,
          qHeight: 500,
        },
      ],
    },

    // Horizontal, with common range
    orientation: 'horizontal',
    measureAxis: {
      commonRange: true,
      dock: 'near',
    },
  },
});

Add color segments

You can also add color segments to the chart to show poor/normal/good performance. Here two limits are added, splitting the range into three segments: red (lower than 90% of the target), yellow (within 90-110% of the target), and green (higher than 110% of the target).

// Rendering a bullet chart with segments
nuked.render({
  element: document.querySelector('.bullet'),
  type: 'bullet-chart',

  // Define all `fields` in `properties`
  properties: {
    title: 'Sales by Quarters',

    qHyperCubeDef: {
      qDimensions: [
        {
          qDef: {
            qFieldDefs: ['Quarter'],
            qSortCriterias: [{ qSortByAscii: 1 }],
          },
        },
      ],
      qMeasures: [
        {
          qDef: {
            qDef: 'Sum(Sales)',
            target: 'Sum([Sale targets])',
            conditionalColoring: {
              segments: {
                limits: [
                  {
                    value: {
                      qValueExpression: {
                        qExpr: 'Sum([Sale targets])*0.9',
                      },
                    },
                  },
                  {
                    value: {
                      qValueExpression: {
                        qExpr: 'Sum([Sale targets])*1.1',
                      },
                    },
                  },
                ],
                paletteColors: [
                  {
                    color: '#7c4345',
                  },
                  {
                    color: '#e0db4d',
                  },
                  {
                    color: '#53ad55',
                  },
                ],
              },
            },
          },
          qSortBy: {
            qSortByNumeric: -1,
          },
          qAttributeExpressions: [
            {
              id: 'bullet-target',
              qExpression: 'Sum([Sale targets])',
            },

            {
              id: 'bullet-segment',
              qExpression: 'Sum([Sale targets])*0.9',
            },
            {
              id: 'bullet-segment',
              qExpression: 'Sum([Sale targets])*1.1',
            },
          ],
        },
      ],
      qInitialDataFetch: [
        {
          qLeft: 0,
          qTop: 0,
          qWidth: 15,
          qHeight: 500,
        },
      ],
      qInterColumnSortOrder: [0, 1],
    },

    // Horizontal, with common range
    orientation: 'horizontal',
    measureAxis: {
      commonRange: true,
      dock: 'near',
    },
  },
});

Multiple measures, no dimension

The bullet chart can also be defined with no dimension and multiple measures. Each bar represents corresponding measure aggregate over the dimension.

// Rendering a bullet chart with three measures and no dimension
nuked.render({
  element: document.querySelector('.bullet'),
  type: 'bullet-chart',
  fields: ['=Sum(Coffee)', '=Sum(Tea)', '=Sum(Sales)'],
  properties: {
    title: 'Sales of Coffe, Tea, and Total',
  },
});

Bullet chart plugins

A plugin can be passed into a bullet chart to add or modify its capability or visual appearance. A plugin needs to be defined before it can be rendered together with the chart.

// Step 1: define the plugin

// Modifying the look and the position of the major axis
const majorAxisPlugin = {
  info: {
    name: 'major-axis-plugin',
    type: 'component-definition',
  },
  fn: ({ keys, layout }) => {
    const componentDefinition = {
      type: 'axis',

      // Provide the same name as the exisiting component to override it
      key: keys.COMPONENT.MAJOR_AXIS,
      settings: {
        labels: {
          fontFamily: 'Tahoma, san-serif',
          fontSize: '15px',
          fill: 'darkred',
        },
      },
    };
    return componentDefinition;
  },
};

// Step 2: passing the plugin definition into the render function

// Rendering a bullet chart with plugins
    nuked.render({
      element: document.getElementById('object'),
      type: 'sn-bullet-chart',
      plugins: [majorAxisPlugin],
      properties,
    });
});

The plugin definition is an object, with two properties info and fn. The fn returns a picasso.js component. To build this component, some important chart internals are passed into the argument object of fn.

// Structure of the argument object of fn
const pluginArgs = {
  layout,
  keys: {
    SCALE: {
      MAIN: {
        MAJOR: KEYS.SCALE.MAIN.MAJOR,
        MINOR: KEYS.SCALE.MAIN.MINOR,
      },
    },
    COMPONENT: {
      BAR: KEYS.COMPONENT.BAR,
      MAJOR_AXIS: KEYS.COMPONENT.MAJOR_AXIS,
      MAJOR_AXIS_TITLE: KEYS.COMPONENT.MAJOR_AXIS_TITLE,
      BULLET_AXIS: KEYS.COMPONENT.BULLET_AXIS,
    },
    COLLECTION: {
      MAIN,
    },
  },
};

With plugins, you can either add new components or modify existing components of the bullet chart.

Add new components

The new component can be a standard Picasso component or a custom Picasso component. Here we demo a standard reference line component.

// Adding reference line at the mean of the targets
const meanReferenceLinePlugin = {
  info: {
    name: 'mean-reference-line-plugin',
    type: 'component-definition',
  },
  fn: ({ keys, layout }) => {
    const targets = layout.qHyperCube.qDataPages[0].qMatrix.map((item) => item[1].qAttrExps.qValues[0].qNum);
    const averageOfTargets = targets.reduce((accumulator, currentValue) => accumulator + currentValue) / targets.length;
    const componentDefinition = {
      key: 'mean-reference-line',
      type: 'ref-line',
      layout: { displayOrder: 2 },
      lines: {
        x: [
          {
            line: {
              stroke: 'darkgray',
              strokeWidth: 5,
            },
            scale: keys.SCALE.MINOR,
            value: averageOfTargets,
          },
        ],
      },
    };
    return componentDefinition;
  },
};

Modify existing components

As an example, the positions and the appearance of the axes can be modified completely by plugins.

To overide an existing component, fn should returns a picasso.js component that has the same key as the existing component (keys.COMPONENT.BULLET_AXIS in this example)

// Modifying the look and the position of the bullet axis
const bulletAxisPlugin = {
  info: {
    name: 'bullet-axis-plugin',
    type: 'component-definition',
  },
  fn: ({ keys, layout }) => {
    const componentDefinition = {
      type: 'box-axis',

      // Provide the same name as the exisiting component to override it
      key: keys.COMPONENT.BULLET_AXIS,
      settings: {
        labels: {
          fontFamily: 'Tahoma, san-serif',
          fontSize: '15px',
          fill: 'darkblue',
        },
        line: { stroke: 'gray' },
      },
    };
    return componentDefinition;
  },
};

Plugins disclaimer

• The plugins API is still experimental.
• We can not guarantee our charts to be compatible with all different settings, especially when modifying existing components.