@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 container component that renders an svg and coordinates scales across its children. You can pass the parent container optionally-animated and/or as well as and .

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

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

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

... render () { return ( ariaLabel="My histogram of ..." orientation="vertical" cumulative={false} normalized={true} binCount={25} valueAccessor={datum => datum} binType="numeric" renderTooltip={({ event, datum, data, color }) => (


            {datum.bin0} to {datum.bin1}
            count {datum.count}

            cumulative {datum.cumulative}

            density {datum.density}


        )}
      >
                  animated
          rawData={rawData / or binnedData={...} /}
        />
        
        
      
    );
  }


Demo with the Histogram playground.
Components
Check out the example source code and PropTable tabs in the Storybook williaster.github.io/data-ui.
$3
Name | Type | Default | Description
------------ | ------------- | ------- | ----
ariaLabel | PropTypes.string.isRequired | - | Accessibility label
binValues | PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.number, PropTypes.string])) | null | Bin thresholds, overrides binCount
binCount | PropTypes.number | 10 | an approximate number of bins to use (if data is not already binned)
binType | PropTypes.oneOf(['numeric', 'categorical']) | 'numeric' | Specify whether to bins are categorical or numeric
children | PropTypes.node.isRequired | - | Child Series, Axis, or other
cumulative | PropTypes.bool | false | whether to show a cumulative histogram
height | PropTypes.number.isRequired | - | height of the visualization
horizontal | PropTypes.bool | false | whether the histograms is oriented vertically or horizontally
limits | PropTypes.array | null | values outside the limits are ignored
margin | PropTypes.shape({ top: PropTypes.number, right: PropTypes.number, bottom: PropTypes.number, left: PropTypes.number }) | { top: 32, right: 32, bottom: 64, left: 64 } | chart margin, leave room for axes and labels!
normalized | PropTypes.bool | false | whether the value axis is normalized as fraction of total
theme | PropTypes.object | {} | chart theme object, see theme below.
width | PropTypes.number.isRequired | - | width of the svg
valueAccessor | PropTypes.func | d => d | for raw data, how to access the bin value
$3

and 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:

`javascript 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.

`$3`

For _raw data_ that is _numeric_, the 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.

Name | Type | Default | Description ------------ | ------------- | ------- | ---- animated | PropTypes.bool | true | whether to animate updates to the data in the series rawData | PropTypes.array | [] | raw datum binnedData | binnedDataShape | [] | binned data fill | PropTypes.oneOfType([PropTypes.func, PropTypes.string]) | @data-ui/theme.color.default | determines bar fill color kernel | PropTypes.oneOf(['gaussian', 'parabolic']) | 'gaussian' | kernel function type, parabolic = epanechnikov kernel showArea | PropTypes.bool | true | whether to show density area fill showLine | PropTypes.bool | true | whether to show density line path smoothing | PropTypes.number | 1 | smoothing constant for parabolic / epanechinikov kernel function fillOpacity | PropTypes.oneOfType([PropTypes.func, PropTypes.number]) | 0.7 | opacity of area fill if shown stroke | PropTypes.oneOfType([PropTypes.func, PropTypes.string]) | 'white' | determines line color if shown strokeWidth | PropTypes.oneOfType([PropTypes.func, PropTypes.number]) | 2 | determines width of line path if shown strokeDasharray | PropTypes.oneOfType([PropTypes.func, PropTypes.string]) | '' | determines dash pattern of line if shown strokeLinecap | PropTypes.oneOf(['butt', 'square', 'round', 'inherit']) | 'round' | style of line path stroke useEntireScale | PropTypes.bool | false | if true, density plots will scale to fill the entire y-range of the plot. if false, the maximum value is scaled to the count of the series

`$3`

Name | Type | Default | Description ------------ | ------------- | ------- | ---- axisStyles | axisStylesShape | {} | config object for axis and axis label styles, see theme below label | PropTypes.oneOfType([PropTypes.string, PropTypes.element]) | | string or component for axis labels numTicks | PropTypes.number | null | approximate number of ticks orientation | XAxis PropTypes.oneOf(['bottom', 'top']) or YAxis PropTypes.oneOf(['left', 'right']) | bottom, left | orientation of axis tickStyles | tickStylesShape | {} | config object for styling ticks and tick labels, see theme below tickLabelComponent | PropTypes.element | | component to use for tick labels tickFormat | PropTypes.func | null | (tick, tickIndex) => formatted tick tickValues | PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.number, PropTypes.string])) | null | custom tick values

`$3`


Tooltips are supported for histogram

BarSeries. The _easiest_ way to use tooltips out of the box is by passing a renderTooltip function to 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 component in the exported HOC, which wraps the svg in a

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 children and are called with the signature onMouseMove({ data, datum, event, color }) and onMouseLeave() upon appropriate trigger.

2) Wrap in yourself, which accepts props for additional customization:

Name | Type | Default | Description ------------ | ------------- | ------- | ---- children | PropTypes.func or PropTypes.object | - | Child function (to call) or element (to clone) with onMouseMove, onMouseLeave, and tooltipData props/keys className | PropTypes.string | - | Class name to add to the

 container wrapper
renderTooltip | PropTypes.func.isRequired | - | Renders the _contents_ of the tooltip, signature of

({ event, data, datum, color, index }) => node. If this function returns a falsy

 value, a tooltip will not be rendered.
styles | PropTypes.object | {} | Styles to add to the

 container wrapper
TooltipComponent | PropTypes.func or PropTypes.object |

@vx's TooltipWithBounds | Component (not instance) to use as the tooltip container component. It is passed top and left

 numbers for positioning
tooltipProps | PropTypes.object | - | Props that are passed to

TooltipComponent


tooltipTimeout | PropTypes.number | 200 | Timeout in ms for the tooltip to hide upon calling

onMouseLeave


$3

A theme object with the following shape can be passed to

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'