Histogram

Bar chart's loosely related cousin, a histogram is used to display the shape of frequency distribution across a continuous dataset, where ranges of values are sorted into series of intervals known as "bins." Similar to a bar chart, a histogram uses bars where each rectangle's height is proportional to the frequency of cases in the bin.

Read more on: Histogram.

Inputs

data

Type: object [] required

Data must be provided as an array of objects in JSON format. Because the histogram plots the distribution of numerical data, the data used along the x-axis must be numerical to be sorted into bins.

A sample dataset could look something like this:

penguins.json

[
{
"species": "Adelie",
"body_mass_g": 4675
},
{
"species": "Gentoo",
"body_mass_g": 3475
},
{
"species": "Emperor",
"body_mass_g": 4250
},
{
"species": "Fairy",
"body_mass_g": 3400
},
{
"species": "Rock",
"body_mass_g": 3700
}
]

xKey

Type: string required

The xKey is the string as the accessor for the data series in the X-domain. This string must match the corresponding property in each data object used for plotting on the x-axis. By default, the data xKey specifies will be scaled linearly.


Hey, where's yKey?

💡

A yKey is not needed, as the y-axis data will always represent the frequency of the dataset. Under the hood, yKey is set to length.

const yAccessor = useMemo(() => (data) => data.length);

xAxisLabel

Type: string

An optional label for the x-axis. Defaults to an empty string "".


yAxisLabel

Type: string

An optional label for the y-axis. Defaults to an empty string "".


height

Type: number required

Chart height in pixels, used within the bounding box of the Chart wrapper component. If a value < 100 is provided, this value will default back to 500.


width

Type: number required

Chart width in pixels, used within the bounding box of the Chart wrapper component. If a value < 100 is provided, this value will default back to 500.


thresholds

Type: number

Thresholds specify how values are divided into bins, where the number of bins is the number of thresholds + 1. If no value is provided, this value will default back to 9.

Under the Hood

Still confused on the relationship between bins and thresholds? Here's what it looks like under the hood:

const binsGenerator = d3
.histogram()
.domain(xScale.domain())
.value(xAccessor)
.thresholds(xScale.ticks(numberOfThresholds))
const bins = binsGenerator(data)

Thresholds are used as an input to calculate our # of bins.


barPadding

Type: number

Padding between each bar. If no value is provided, this value will default back to 2.

💡
Giving some space can help distinguish individual bars!


Children

The Histogram contains the following children components:

  • Chart
  • Axis
  • Bars

Component Structure and Use

The finished Histogram is structured like so:

import { data } from 'MyHistogramData.js'
import { Histogram } from 'ad3lie'
const MyHistogram = ({
data /* see data from your Javascript data file */,
}) => (
<Histogram
data={data}
xKey="body_mass_g"
xAxisLabel="X-axis: Species"
yAxisLabel="Y-axis: Body Mass"
height={500}
width={500}
thresholds={9}
barPadding={2}
/>
)

Simply import your custom MyHistogram along with MyHistogramData.js for easy use. Or, pull Histogram and provide the required props yourself.

Props Summary

PropertyTypeRequired?
dataobject []
xKeystring
yKeystring
xAxisLabelstring
yAxisLabelstring
heightnumber
widthnumber
thresholdsnumber
barPaddingnumber