Framework:Javascript Data GridAngular Data GridReact Data GridVue Data Grid

Angular Charts: Histogram Series

Histograms show the frequency distribution of continuous data. They are a good choice for when the data is larger than could be plotted on a bar chart and can be used to find underlying trends in continuous data.

Simple Histogram

Histograms require at least one numeric attribute in the data to be specified using the xKey property. Data will be distributed into bins according to the xKey values.

The simplest configuration for a Histogram Series is shown below:

series: [{
    type: 'histogram'
    xKey: 'age'
}]

Bin Count

By default the histogram will split the x domain of the data into around ten regular-width bins, although the exact number generated will vary so that the chart can find round values for the bin boundaries. This is similar to how giving a number of ticks to an axis does not guarantee that exact number of ticks. The number of bins to aim for can be overridden by setting the binCount property on a histogram series.

Given enough data, charts with more bins are able to more precisely illustrate underlying trends, but are also more sensitive to random noise.

series: [{
    type: 'histogram'
    xKey: 'age',
    binCount: 20
}]

Irregular Intervals

Rather than specify the number of bins, for cases where you know exactly which bins you wish to split your x-axis values into, it is possible to explicitly give the start and end values for each bin. This is given using the bins property, and the value should be an array of arrays where each inner array contains the start and end value of a bin. In the example below, the data from the race is split into irregular age categories.

For histogram charts with irregular bins it is usual for the area of the bar, rather than its height, to visually represent the value of each bin. In this way the shape of the underlying curve is maintained over irregular intervals. The areaPlot property should be set to true to enable this mode.

series: [{
    type: 'histogram'
    xKey: 'age',
    areaPlot: true,
    bins: [[16, 18], [18, 21], [21, 25], [25, 40]]
}]

Note that if you give the bins property you should not also give binCount, but if both are present bins takes precedence.

XY Histogram

The histograms shown above all contain a single xKey with its frequency plotted on the y axis. However it is sometimes useful to visualise an xKey and yKey using a Histogram.

When using XY Histograms it is also useful to control how bins are aggregated using the aggregation series property. The following sections compare the sum and mean aggregation functions.

Summing Bins

This is used to show the summing of one column or attribute for each of the bins. When a yKey is given, the default behaviour is to plot a total of the yKey values. The kind of aggregation to use is controlled by the series.aggregation property.

series: [{
    type: 'histogram'
    xKey: 'age',
    yKey: 'winnings',
    aggregation: 'sum'
}]

Mean Bins

Showing frequencies or summing up the y-values isn't always the best way to show your data. For data that is not evenly distributed in x, but is relatively uniform in y, a sum plot xy histogram will tend to be dominated by the populations of the x-bins. In the above example you may notice that the prize money distribution very closely follows the age distribution, so that while potentially useful, the chart does not reveal any new trends in the data. In many cases, plotting the mean of a bin on the y-axis better illustrates an underlying trend in the data:

series: [{
    type: 'histogram'
    xKey: 'age',
    yKey: 'time',
    yName: 'Average Time',
    aggregation: 'total'
}]

API Reference

data *
object[]
The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
visible
boolean
Whether or not to display the series.
Default: true
showInLegend
boolean
Whether or not to include the series in the legend.
Default: true
cursor
string
The cursor to use for hovered histogram bars. This config is identical to the CSS cursor property.
Default: 'default'
tooltip
Series-specific tooltip configuration.
See tooltip for more details.
xKey *
string
The key to use to retrieve x-values from the data.
xName
string
A human-readable description of the x-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
yKey
string
The key to use to retrieve y-values from the data.
yName
string
A human-readable description of the y-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
binCount
number
The number of bins to try to split the x axis into. Clashes with the bins setting.
Default: 10
bins
number[][]
Set the bins explicitly. The bins need not be of equal width. Clashes with the binCount setting.
aggregation
string
Dictates how the bins are aggregated. If set to 'sum', the value shown for the bins will be the total of the yKey values. If set to 'mean', it will display the average yKey value of the bin
Default: 'sum'
Options: 'sum', 'mean'
areaPlot
boolean
For variable width bins, if true the histogram will represent the aggregated yKey values using the area of the bar. Otherwise, the height of the var represents the value as per a normal bar chart. This is useful for keeping an undistorted curve displayed when using variable-width bins
Default: 'false'
lineDash
number[]
Defines how the column strokes are rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, [6, 3] means dashes with a length of 6 pixels with gaps between of 3 pixels.
Default: []
lineDashOffset
number
The initial offset of the dashed line in pixels.
Default: 0
highlightStyle
Configuration for series item and whole series highlighting when columns or legend items are hovered over.
See highlightStyle for more details.
fill
string
The colour of the fill for the histogram bars.
Default: '#f3622d'
fillOpacity
number
The opacity of the fill for the histogram bars.
Default: 1
stroke
string
The colour of the stroke for the histogram bars.
Default: '#aa4520'
strokeOpacity
number
The opacity of the stroke for the histogram bars.
Default: 1
strokeWidth
number
The width in pixels of the stroke for the histogram bars.
Default: 1
listeners
A map of event names to event listeners.
See listeners for more details.

tooltip

histogram > tooltip

Series-specific tooltip configuration.

histogram: {
  ...
  tooltip: {
    enabled?: boolean; // default: true
    renderer?: Function;
  }
}
enabled
boolean
Whether or not to show tooltips when the series are hovered over.
Default: true
renderer
Function
Function used to create the content for tooltips.
renderer = (params: RendererParams) => string;

interface RendererParams {
  datum: any;
  title?: string;
  color?: string;
  xKey: string;
  xValue: any;
  xName?: string;
  yKey: string;
  yValue: any;
  yName?: string;
  sizeKey?: string;
  sizeName?: string;
  labelKey?: string;
  labelName?: string;
}

highlightStyle

histogram > highlightStyle

Configuration for series item and whole series highlighting when columns or legend items are hovered over.

histogram: {
  ...
  highlightStyle: {
    item?: Item;
    series?: Series;
  }
}
item
Highlight style used for an individual column when tapped or hovered over.
See item for more details.
series
Highlight style used for the whole series when a single column is tapped or hovered over.
See series for more details.

item

Highlight style used for an individual column when tapped or hovered over.

histogram: {
  ...
  highlightStyle: {
    ...
    item: {
      fill?: string; // default: 'yellow'
      stroke?: string;
      strokeWidth?: number;
    }
  }
}
fill
string
The fill colour of a column when hovered over. Use undefined for no highlight.
Default: 'yellow'
stroke
string
The stroke colour of a column when hovered over. Use undefined for no highlight.
strokeWidth
number
The stroke width of a column when hovered over. Use undefined for no highlight.

series

Highlight style used for the whole series when a single column is tapped or hovered over.

histogram: {
  ...
  highlightStyle: {
    ...
    series: {
      strokeWidth?: number;
      dimOpacity?: number;
    }
  }
}
strokeWidth
number
The stroke width of the rest of the columns when an individual column is tapped or hovered over, or when a legend item is hovered over. Use undefined for no highlight.
dimOpacity
number
The opacity of the series when another chart series is highlighted by hovering a series item or a legend item. Use undefined or 1 for no dimming.

listeners

histogram > listeners

A map of event names to event listeners.

histogram: {
  ...
  listeners: {
    nodeClick?: Function;
  }
}
nodeClick
Function
The listener to call when a histogram bar is clicked.
nodeClick = (
    params: NodeClickParams
) => any;

interface NodeClickParams {
  type: 'nodeClick';
  series: HistogramSeries;
  datum: any;
  xKey: string;
}

Next Up

Continue to the next section to learn about area series.