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.

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

Property	Type	Required?
data	object []	✅
xKey	string	✅
yKey	string	✅
xAxisLabel	string	❌
yAxisLabel	string	❌
height	number	✅
width	number	✅
thresholds	number	❌
barPadding	number	❌