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