Scatter and Bubble Series

Scatter charts use two axes to plot (x,y) pairs of numeric variables as points at the intersection of x and y.

Scatter series configuration is largely the same as line series configuration (please refer to the line series documentation to learn more), so here we'll just give some examples and cover only the differences.

Scatter Plot

Scatter plots are great for identifying the relationship between plotted values, as well as outliers and gaps in the data.

Here's a simple scatter chart that plots the mean sea level measured over a few years. The measurements may have a certain degree of variability and error to them, but the overall trend is clear — the sea level is rising.

Bubble Chart

A bubble chart is simply a scatter plot where each point has another associated variable that determines the size of a bubble. Instead of having pairs of variables, we now have triples.

To turn a scatter plot into a bubble chart you must provide the sizeKey that will be used to fetch the value that will determine the size of each bubble. For the example below we are using the following key configs:

xKey: 'height', yKey: 'weight', sizeKey: 'age'

Another config we should provide is the size of the marker. When the sizeKey is specified, the value of marker.size config takes on a different meaning — instead of determining the actual marker size, the size config now determines the maximum marker size. The marker also has the minSize config, which only applies when the sizeKey is set.

marker: { minSize: 8, // defaults to 8 size: 30 // defaults to 8 }

So for example, if the sizeKey data ranges from -100 to 200, the above config means that -100 will correspond to marker of size 8 (the minSize), 200 to a marker of size 30 (the size), and any value between -100 and 200 will be interpolated to a value between 8 and 30.

Finally, the bubble chart is so called because the circle is the most common marker type used for this kind of scatter plot, but with ag-Charts any other marker shape can be used as well.

The example below uses both 'circle' and 'square' markers to represent the age of females and males respectively. We provide the names of all keys to get nice looking tooltips and the title of the series to have it reflected in the legend. The series title is shown in the tooltips as well.

API Reference

xKey
Required
The key to use to retrieve x-values from the data.
xNameA human-readable description of the x-values.
yKey
Required
The key to use to retrieve y-values from the data.
yNameA human-readable description of the y-values.
sizeKeyThe key to use to retrieve size values from the data, used to control the size of the markers in bubble charts.
sizeNameA human-readable description of the size values.
labelKeyThe key to use to retrieve values from the data to use as labels for the markers.
labelNameA human-readable description of the label values.
data
Required
The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
visibleWhether or not to display the series.
Default: true
showInLegendWhether or not to include the series in the legend.
Default: true
tooltipEnabledWhether or not to show tooltips when the series are hovered over.
Default: true
tooltipRendererFunction used to create the content for tooltips.function (params: IParams): string; interface IParams { datum: any; title?: string; color?: string; xKey: string; xName?: string; yKey: string; yName?: string; sizeKey?: string; sizeName?: string; labelKey?: string; labelName?: string; }
titleThe title to use for the series. Defaults to yName if it exists, or yKey if not.
fillThe colour of the fill for the markers.
Default: '#f3622d'
fillOpacityThe opacity of the fill for the markers.
Default: 1
strokeThe colour of the stroke for the markers.
Default: '#aa4520'
strokeOpacityThe opacity of the stroke for the markers.
Default: 1
strokeWidthThe width in pixels of the stroke for the markers.
Default: 1
markerConfiguration for the markers used in the series. See marker for more details about this configuration object.
highlightStyleConfiguration for the highlighting used when the markers are hovered over. See highlightStyle for more details about this configuration object.
listenersA map of event names to event listeners. See listeners for more details about this configuration object.

marker

Configuration for the markers used in the series.

enabledWhether or not to show markers.
Default: true
shapeThe shape to use for the markers. You can also supply a custom marker by providing a Marker subclass.
Default: 'circle'
Options: 'circle', 'cross', 'diamond', 'plus', 'square', 'triangle'
sizeThe size in pixels of the markers.
Default: 8
minSizeFor series where the size of the marker is determined by the data, this determines the smallest size a marker can be in pixels.
Default: 12
fillThe colour to use for marker fills. If this is not specified, the markers will take their fill from the series.
strokeThe colour to use for marker strokes. If this is not specified, the markers will take their stroke from the series.
strokeWidthThe width in pixels of the marker stroke. If this is not specified, the markers will take their stroke width from the series.
formatterFunction used to return formatting for individual markers, based on the supplied information. If the current marker is highlighted, the highlighted property will be set to true; make sure to check this if you want to differentiate between the highlighted and un-highlighted states.function (params: IParams): IReturn; interface IParams { datum: any; fill: string; stroke: string; strokeWidth: number; size: number; highlighted: boolean; xKey: string; yKey: string; } interface IReturn { fill: string; stroke: string; strokeWidth: number; size: number; }

highlightStyle

Configuration for the highlighting used when the markers are hovered over.

fillThe fill colour of the markers when hovered over.
Default: 'yellow'
strokeThe colour of the stroke around the markers when hovered over.

listeners

A map of event names to event listeners.

nodeClickThe listener to call when a scatter series node (marker) is clicked.function (params: IParams): any; interface IParams { type: 'nodeClick'; series: ScatterSeries; datum: any; xKey: string; yKey: string; sizeKey?: string; }

Next Up

Continue to the next section to learn about pie and doughnut series.