@data-ui/histogram

A React + d3 library for creating histograms. Vertical or horizontal, raw data or binned data, numeric or categorical bins, counts or densities, cumulative or not.

npm install --save @data-ui/histogram

Demo it live at williaster.github.io/data-ui.

Example usage

Similar to the @data-ui/xy-chart package, this @data-ui/histogram package exports a parent <Histogram /> container component that renders an svg and coordinates scales across its children. You can pass the parent container optionally-animated <BarSeries /> and/or <DensitySeries /> as well as <XAxis /> and <YAxis />.

import { Histogram, DensitySeries, BarSeries, withParentSize, XAxis, YAxis } from '@data-ui/histogram';

const ResponsiveHistogram = withParentSize(({ parentWidth, parentHeight, ...rest}) => (
  <Histogram
    width={parentWidth}
    height={parentHeight}
    {...rest}
  />
);

const rawData = Array(100).fill().map(Math.random);

...
  render () {
    return (
      <ResponsiveHistogram
        ariaLabel="My histogram of ..."
        orientation="vertical"
        cumulative={false}
        normalized={true}
        binCount={25}
        valueAccessor={datum => datum}
        binType="numeric"
        renderTooltip={({ event, datum, data, color }) => (
          <div>
            <strong style={{ color }}>{datum.bin0} to {datum.bin1}</strong>
            <div><strong>count </strong>{datum.count}</div>
            <div><strong>cumulative </strong>{datum.cumulative}</div>
            <div><strong>density </strong>{datum.density}</div>
          </div>
        )}
      >
        <BarSeries
          animated
          rawData={rawData /* or binnedData={...} */}
        />
        <XAxis />
        <YAxis />
      </ResponsiveHistogram>
    );
  }

Demo with the Histogram playground.

Components

Check out the example source code and PropTable tabs in the Storybook williaster.github.io/data-ui.

<Histogram />

<*Series />

<BarSeries /> and <DensitySeries /> components accept either rawData or binnnedData. Raw data can be in any format as long as the value of each datum can be accessed with the Histogram valueAccessor function. Binned data should have the following shapes:

export const numericBinnedDatumShape = PropTypes.shape({
  id: PropTypes.string.isRequired,
  bin0: PropTypes.number.isRequired,
  bin1: PropTypes.number.isRequired,
  count: PropTypes.number.isRequired,
});

export const categoricalBinnedDatumShape = PropTypes.shape({
  id: PropTypes.string.isRequired,
  bin: PropTypes.string.isRequired,
  count: PropTypes.number.isRequired,
});

If both rawData and binnnedData are provided, rawData is ignored.

<BarSeries />

<DensitySeries />

For raw data that is numeric, the <DensitySeries /> plots an estimates of the probability density function, i.e., a kernel density estimate. If pre-aggregated and/or categorical data is passed to the Series, it plots an Area graph of values based on the data counts.

<XAxis /> and <YAxis />

Tooltips

Tooltips are supported for histogram BarSeries. The easiest way to use tooltips out of the box is by passing a renderTooltip function to <Histogram /> as shown in the above example. This function takes an object with the shape { event, datum, data, color } as input and should return the inner contents of the tooltip (not the tooltip container!) as shown above. datum corresponds to the binned data point, see the above-specified shapes which depend on whether your bins are categorical or numeric. color represents the bar fill. If this function returns a falsy value, a tooltip will not be rendered.

Under the covers this will wrap the <Histogram /> component in the exported <WithTooltip /> HOC, which wraps the svg in a <div /> and handles the positioning and rendering of an HTML-based tooltip with the contents returned by renderTooltip(). This tooltip is aware of the bounds of its container and should position itself "smartly".

If you'd like more customizability over tooltip rendering you can do either of the following:

1. Roll your own tooltip positioning logic and pass onMouseMove and onMouseLeave functions to Histogram. These functions are passed to the <BarSeries /> children and are called with the signature onMouseMove({ data, datum, event, color }) and onMouseLeave() upon appropriate trigger.

2. Wrap <Histogram /> in <WithTooltip /> yourself, which accepts props for additional customization:

Theme

A theme object with the following shape can be passed to <Histogram /> to style the chart, axes, and series. Alternatively, keys (eg xAxisStyles) can be passed directly to the axes components.

See @data-ui/theme for an example.

export const themeShape = PropTypes.shape({
  gridStyles: PropTypes.shape({
    stroke: PropTypes.string,
    strokeWidth: PropTypes.number,
  }),
  xAxisStyles: PropTypes.shape({
    stroke: PropTypes.string,
    strokeWidth: PropTypes.number,
    label: PropTypes.shape({
      bottom: PropTypes.object,
      top: PropTypes.object,
    }),
  }),
  yAxisStyles: PropTypes.shape({
    stroke: PropTypes.string,
    strokeWidth: PropTypes.number,
    label: PropTypes.shape({
      left: PropTypes.object,
      right: PropTypes.object,
    }),
  })
  xTickStyles: PropTypes.shape({
    stroke: PropTypes.string,
    tickLength: PropTypes.number,
    label: PropTypes.shape({
      bottom: PropTypes.object,
      top: PropTypes.object,
    }),
  }),
  yTickStyles: PropTypes.shape({
    stroke: PropTypes.string,
    tickLength: PropTypes.number,
    label: PropTypes.shape({
      left: PropTypes.object,
      right: PropTypes.object,
    }),
  }),
});

Development

npm install
yarn run dev # or 'build'