@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

``js
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
},
});
`

$3

- 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.

$3

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

`js
// 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,
},
},
});
`

$3

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.

`js
// 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,
},
},
});
`

$3

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

`js
// 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.

`js
// 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.

`js
// 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.

$3

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.

`js
// 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;
},
};
`

$3

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)

`js
// 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;
},
};
``

$3

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