Framework:Javascript Data GridAngular Data GridReact Data GridVue Data Grid

JavaScript 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 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 of bins generated will vary so that the chart can find round values for the bin boundaries.

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

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.

In the example below, the data from the race is split into irregular age categories and the areaPlot property has been set to true.

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 binCount takes precedence.

XY Histogram

The histograms shown above all contain a single xKey with its frequency plotted on the Y axis. However, it is also possible to provide Y values corresponding to the X values, by specifying both xKey and yKey properties.

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

Summing Bins

The sum aggregation function is used to sum the values of a column or attribute for each of the bins.

When a yKey is specified, 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 visualize 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. In such 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: 'Race time',
    aggregation: 'mean'
}]

API Reference

Properties available on the AgHistogramSeriesOptions<DatumType = any> interface.

xKey *
string
The key to use to retrieve x-values from the data.
type
'histogram'
'histogram'
fill
CssColor
The colour of the fill for the histogram bars.
Default: '#f3622d'
fill: CssColor;

type CssColor = string
stroke
CssColor
The colour of the stroke for the histogram bars.
Default: '#aa4520'
stroke: CssColor;

type CssColor = string
fillOpacity
Opacity
The opacity of the fill for the histogram bars.
Default: 1
fillOpacity: Opacity;

type Opacity = number
strokeOpacity
Opacity
The opacity of the stroke for the histogram bars.
Default: 1
strokeOpacity: Opacity;

type Opacity = number
strokeWidth
PixelSize
The width in pixels of the stroke for the histogram bars.
Default: 1
strokeWidth: PixelSize;

type PixelSize = number
lineDash
PixelSize[]
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.
lineDash: PixelSize[];

type PixelSize = number
lineDashOffset
PixelSize
The initial offset of the dashed line in pixels.
Default: 0
lineDashOffset: PixelSize;

type PixelSize = number
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.
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.
bins
[number, number][]
Set the bins explicitly. The bins need not be of equal width. Note that bins is ignored if binCount is also supplied.
binCount
number
The number of bins to try to split the x axis into. Clashes with the bins setting.
Default: 10
aggregation
'count' | 'sum' | 'mean'
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'
shadow
AgDropShadowOptions
Configuration for the shadow used behind the chart series.
shadow: AgDropShadowOptions;

interface AgDropShadowOptions {
  // Whether or not the shadow is visible. 
  enabled?: boolean;
  // The colour of the shadow. 
  color?: CssColor;
  // The horizontal offset in pixels for the shadow. 
  xOffset?: PixelSize;
  // The vertical offset in pixels for the shadow. 
  yOffset?: PixelSize;
  // The radius of the shadow's blur, given in pixels. 
  blur?: PixelSize;
}

type CssColor = string

type PixelSize = number
label
AgHistogramSeriesLabelOptions
Configuration for the labels shown on bars.
label: AgHistogramSeriesLabelOptions;

interface AgHistogramSeriesLabelOptions {
  // Function used to turn 'yKey' values into text to be displayed by a label. By default the values are simply stringified. 
  formatter?: (params: { value: number; seriesId: string; }) => string;
  // Whether or not the labels should be shown. 
  enabled?: boolean;
  // The font style to use for the labels. 
  fontStyle?: FontStyle;
  // The font weight to use for the labels. 
  fontWeight?: FontWeight;
  // The font size in pixels to use for the labels. 
  fontSize?: FontSize;
  // The font family to use for the labels. 
  fontFamily?: FontFamily;
  // The colour to use for the labels. 
  color?: CssColor;
}

type FontStyle = 
      'normal' 
    | 'italic' 
    | 'oblique'


type FontWeight = 
      'normal' 
    | 'bold' 
    | 'bolder' 
    | 'lighter' 
    | '100' 
    | '200' 
    | '300' 
    | '400' 
    | '500' 
    | '600' 
    | '700' 
    | '800' 
    | '900'


type FontSize = number

type FontFamily = string

type CssColor = string
tooltip
AgHistogramSeriesTooltip
Series-specific tooltip configuration.
tooltip: AgHistogramSeriesTooltip;

interface AgHistogramSeriesTooltip {
  // Function used to create the content for tooltips. 
  renderer?: (params: AgCartesianSeriesTooltipRendererParams) => string | AgTooltipRendererResult;
  // Whether or not to show tooltips when the series are hovered over. 
  enabled?: boolean;
}

interface AgCartesianSeriesTooltipRendererParams {
  // xKey as specified on series options. 
  xKey: string;
  // xValue as read from series data via the xKey property. 
  xValue?: any;
  // xName as specified on series options. 
  xName?: string;
  // yKey as specified on series options. 
  yKey: string;
  // yValue as read from series data via the yKey property. 
  yValue?: any;
  // yName as specified on series options. 
  yName?: string;
  // Datum from the series data array that the tooltip is being rendered for. 
  datum: any;
  // Series title or yName depending on series configuration. 
  title?: string;
  // Series primary colour, as selected from the active theme, series options or formatter. 
  color?: CssColor;
  // The ID of the series. 
  seriesId: string;
}

type CssColor = string

interface AgTooltipRendererResult {
  // Title text for the tooltip header. 
  title?: string;
  // Content text for the tooltip body. 
  content?: string;
}
listeners
AgSeriesListeners<DatumType>
A map of event names to event listeners.
listeners: AgSeriesListeners<DatumType>;

interface AgSeriesListeners<DatumType> {
  // The listener to call when a node (marker, column, bar, tile or a pie sector) in the series is clicked. 
  nodeClick: (params: AgSeriesNodeClickParams<DatumType>) => void;
}

interface AgSeriesNodeClickParams<DatumType> {
  // Event type. 
  type: 'nodeClick';
  // Series ID, as specified in series.id (or generated if not specified) 
  seriesId: string;
  // Datum from the series data array. 
  datum: DatumType;
  // xKey as specified on series options 
  xKey?: string;
  // yKey as specified on series options 
  yKey?: string;
  // sizeKey as specified on series options 
  sizeKey?: string;
  // labelKey as specified on series options 
  labelKey?: string;
  // colorKey as specified on series options 
  colorKey?: string;
  // angleKey as specified on series options 
  angleKey?: string;
  // calloutLabelKey as specified on series options 
  calloutLabelKey?: string;
  // sectorLabelKey as specified on series options 
  sectorLabelKey?: string;
  // radiusKey as specified on series options 
  radiusKey?: string;
}
id
string
Primary identifier for the series. This is provided as seriesId in user callbacks to differentiate multiple series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour by series please supply your own unique id value.
Default: auto-generated value
data
DatumType[]
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.
showInLegend
boolean
Whether or not to include the series in the legend.
cursor
string
The cursor to use for hovered area markers. This config is identical to the CSS cursor property.
highlightStyle
AgSeriesHighlightStyle
Configuration for series markers and series line highlighting when a marker / data point or a legend item is hovered over.
highlightStyle: AgSeriesHighlightStyle;

interface AgSeriesHighlightStyle {
  // Highlight style used for an individual marker when tapped or hovered over. 
  item?: AgSeriesHighlightMarkerStyle;
  // Highlight style used for whole series when one of its markers is tapped or hovered over. 
  series?: AgSeriesHighlightSeriesStyle;
}

interface AgSeriesHighlightMarkerStyle {
  // The fill colour of a marker when tapped or hovered over. Use `undefined` for no highlight. 
  fill?: CssColor;
  // The opacity of the fill for the highlighted item. 
  fillOpacity?: Opacity;
  // The stroke colour of a marker when tapped or hovered over. Use `undefined` for no highlight. 
  stroke?: CssColor;
  // The stroke width of a marker when tapped or hovered over. Use `undefined` for no highlight. 
  strokeWidth?: PixelSize;
}

type CssColor = string

type Opacity = number

type PixelSize = number

interface AgSeriesHighlightSeriesStyle {
  enabled?: boolean;
  // The opacity of the whole series (area line, area fill, labels and markers, if any) when another chart series or another stack level in the same area series is highlighted by hovering a data point or a legend item. Use `undefined` or `1` for no dimming. 
  dimOpacity?: Opacity;
  // The stroke width of the area line when one of the markers is tapped or hovered over, or when a tooltip is shown for a data point, even when series markers are disabled. Use `undefined` for no highlight. 
  strokeWidth?: PixelSize;
}

Next Up

Continue to the next section to learn about area series.