Histogram

Basic usage

Pass an array of numeric observations toDatum.histogram(). Datum automatically divides the values into bins and counts the observations in each one.

import {
    Datum,
    Color
} from '@psdpainter/datum-js';

const values = [
    12, 14, 15, 16, 17,
    18, 18, 19, 19, 20,
    20, 20, 21, 21, 21,
    22, 22, 22, 23, 23,
    23, 24, 24, 24, 25,
    25, 26, 26, 27, 28,
    29, 30, 31, 33, 35
];

Datum.chart({
    target: '#histogram-example',
    height: 300,

    datum: [
        Datum.histogram(values, {
            bins: 6,
            fill: Color.Blue,
            rx: 2,
            opacity: 0.9
        })
    ]
});

Syntax

Datum.histogram(data, {
    bins,
    fill,
    stroke,
    strokeWidth,
    rx,
    opacity
});

Unlike a standard bar layer, the height of each histogram bar does not come directly from an individual input value. Datum groups the observations into bins and calculates the frequency of each interval.

Data

The simplest histogram dataset is an array of numbers.

const values = [
    12, 14, 15, 18, 18,
    19, 20, 20, 21, 22,
    22, 23, 24, 26, 30
];

Datum.histogram(values);

Each number represents an individual observation rather than the height of a bar.

Bins

Use bins to control how many intervals Datum uses when grouping the observations. The default is6.

Datum.histogram(values, {
    bins: 8
});

Increasing the number of bins provides more detail, while fewer bins provide a broader view of the distribution.

Fill

Use fill to set the color of the histogram bars.

Datum.histogram(values, {
    fill: Color.Blue
});

Stroke

Use stroke and strokeWidth to control the outline around each histogram bar.

Datum.histogram(values, {
    fill: Color.Blue,
    stroke: '#ffffff',
    strokeWidth: 1
});

Rounded corners

Use rx to control the corner radius of each histogram bar. The default is 2.

Datum.histogram(values, {
    fill: Color.Blue,
    rx: 4
});

Opacity

Use opacity to control the transparency of the histogram bars. The default is 1.

Datum.histogram(values, {
    fill: Color.Blue,
    opacity: 0.7
});

Object data

Histograms can also extract numeric observations from objects. Datum looks for a value property, followed by y.

const observations = [
    { value: 12 },
    { value: 18 },
    { value: 22 },
    { value: 24 },
    { value: 30 }
];

Datum.histogram(observations);

Options

{
    bins: 6,
    fill: null,
    stroke: '#ffffff',
    strokeWidth: 1,
    rx: 2,
    opacity: 1
}

Histogram vs. bar

Although histograms and bar charts have a similar visual appearance, they represent different kinds of data.

Use Datum.bar() when each bar represents a discrete category and its associated value. UseDatum.histogram() when you have a collection of numeric observations and want to visualize their distribution.