@nebula.js/sn-bar-chart

@nebula.js/sn-bar-chart

The bar chart is suitable for comparing multiple values. The dimension axis shows the category items that are compared, and the measure axis shows the value for each category item.

Requirements

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

Installing

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

Usage

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

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

// Rendering a bar chart on the fly
nuked.render({
  type: 'barchart',
  element: document.querySelector('.bars'),
  fields: ['Dim1', '=Sum(Expression1)'],
  options: {
    direction: 'ltr',
    freeResize: true,
    viewState: {
      scrollPosition: 25,
    },
  },
  properties: {
    color: { mode: 'byDimension' }, // overrides default properties
  },
});

Options

• direction - ltr/rtl
• freeResize - in conjunction with snapshotData on layout, lets the chart ignore size set on snapshotData
• viewState - settings for the initial rendering of the table
  • viewState.scrollPosition - pixel position of the scroll

More examples

You can make more complex comparisons of data by using grouped or stacked bars. This requires using two dimensions and one measure. The Grouped bar chart and Stacked bar chart use the same two dimensions and the same measure.

You can change the orientation of a bar chart by following this Horizontal bar chart example.

Grouped bar chart

Grouped bars: with grouped bars, you can easily compare two or more items in the same categorical group.

// Rendering a bar chart on the fly
nuked.render({
  type: 'barchart',
  element: document.querySelector('.bars'),
  fields: ['Product Group', '=Sum(Sales)', '=Sum(Margin)'],
  // overrides default properties
  properties: {
    barGrouping: {
      grouping: 'grouped',
    },
    dataPoint: {
      showLabels: true,
      showSegmentLabels: false,
      showTotalLabels: true,
    },
  },
});

Stacked bar chart

Stacked bars: with stacked bars it is easier to compare the total quantity between different months. Stacked bars combine bars of different groups on top of each other and the total height of the resulting bar represents the combined result.

// Rendering a bar chart on the fly
nuked.render({
  type: 'barchart',
  element: document.querySelector('.bars'),
  fields: ['Product Group', '=Sum(Sales)', '=Sum(Margin)'],
  // overrides default properties
  properties: {
    barGrouping: {
      grouping: 'stacked',
    },
    dataPoint: {
      showLabels: true,
      showSegmentLabels: true,
      showTotalLabels: true,
    },
  },
});

Horizontal bar chart

The bar chart can be displayed horizontally or vertically by setting orientation property to horizontal or vertical, as a horizontal bar chart example below:

// Rendering a bar chart on the fly
nuked.render({
  type: 'barchart',
  element: document.querySelector('.bars'),
  fields: ['Product Group', '=Sum(Sales)', '=Sum(Margin)'],
  // overrides default properties
  properties: {
    barGrouping: {
      grouping: 'grouped',
    },
    dataPoint: {
      showLabels: true,
      showSegmentLabels: false,
      showTotalLabels: true,
    },
    orientation: 'horizontal',
  },
});

Bar chart plugins

A plugin can be passed into a bar 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

// Adding a line plugin that goes through the ends of the bars
const linePlugin = {
  info: {
    name: 'line-plugin',
    type: 'component-definition',
  },
  fn: ({ keys, layout }) => {
    const componentDefinition = {
      key: 'sum-line',
      type: 'line',
      layout: { displayOrder: 10 },
      data: { collection: keys.COLLECTION.MAIN },
      settings: {
        coordinates: {
          minor: { scale: keys.SCALE.MAIN.MINOR, fn: (d) => d.scale(d.datum.end.value) },
          major: { scale: keys.SCALE.MAIN.MAJOR },
        },
        layers: { line: { stroke: 'red', strokeWidth: 2, opacity: 0.5, strokeDasharray: '5 10' } },
      },
    };
    return componentDefinition;
  },
};

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

// Render a bar chart with plugins
nuked.render({
  element: document.querySelector('#object'),
  type: 'sn-bar-chart',
  plugins: [linePlugin],
  fields: ['Letter', '=Sum(Frequency)*100'],
  // eslint-disable-next-line no-undef
  properties: {
    title: 'Frequencies of Letters in English (%)',
  },
});

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: {
        MINOR,
        MAJOR,
      },
    },
    COMPONENT: {
      BAR,
      BAR_AXIS,
      Y_AXIS,
      MEASURE_TITLE,
      DIMENSION_TITLE,
    },
    COLLECTION: {
      MAIN,
    },
  },
};

With plugins, you can either add new components or modify existing components of the bar 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 at the median of the frequency values.

// Adding reference line at the median of the frequency
const medianReferenceLinePlugin = {
  info: {
    name: 'median-reference-line-plugin',
    type: 'component-definition',
  },
  fn: ({ keys, layout }) => {
    const frequencies = layout.qHyperCube.qDataPages[0].qMatrix.map((item) => item[1].qNum);
    const value = getMedian(frequencies);
    const componentDefinition = {
      key: 'median-reference-line',
      type: 'ref-line',
      layout: { displayOrder: 4 },
      lines: {
        y: [
          {
            line: {
              stroke: 'black',
              strokeWidth: 2,
              strokeDasharray: '5 10',
            },
            scale: keys.SCALE.MAIN.MINOR,
            value,
            label: {
              text: `Median frequency:`,
              fontSize: '15px',
              // opacity: 1,
            },
          },
        ],
      },
    };
    return componentDefinition;
  },
};

Modify existing components

As an example, the bar component can be modified with plugin.

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

// Modifying the look of the existing bar component
const barPlugin = {
  info: {
    name: 'bar-plugin',
    type: 'component-definition',
  },
  fn: ({ layout, keys }) => {
    const componentDefinition = {
      type: 'box',

      // Provide the same name as the exisiting line component to override it
      key: keys.COMPONENT.BAR,
      settings: {
        box: { width: 0.8, stroke: 'dimgray', strokeWidth: 2 },
      },
    };
    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.