Framework:Javascript Data GridAngular Data GridReact Data GridVue Data Grid

JavaScript Charts: Scatter 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: {
    size: 6,       // defaults to 6
    maxSize: 30    // defaults to 30
}

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.

Bubble Chart with Labels

Scatter series can be configured to use labels. Unlike with other series types where a label is placed for every data point, scatter series label placement is constrained so that:

  • labels don't overlap any markers
  • labels don't overlap other labels

If these constraints are not satisfied, a label is not placed.

Satisfying these constraints is computationally intensive and the complexity rises exponentially with increasing number of data points. Given that label placement might have to happen in real time, for example, when resizing a chart window, it is advised not to enable scatter series labels for data sets with more than a few hundred points.

To enable scatter series labels we have to both set the label.enabled config of a series to true and to specify which key should be used to fetch the label values.

labelKey: 'name',
label: {
    enabled: true
}

The example below has the above config applied to both series. The label placement algorithm is aware of all the scatter series in a chart, so labels don't overlap markers and other labels within a single series nor between different series.

Try openening this example in a larger window to see that more labels are placed as the chart gets bigger. You can also try changing the size of the markers and the font size of the labels to see how that effects label placement.

API Reference

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.
sizeKey
string
The key to use to retrieve size values from the data, used to control the size of the markers in bubble charts.
sizeName
string
A human-readable description of the size values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
labelKey
string
The key to use to retrieve values from the data to use as labels for the markers.
labelName
string
A human-readable description of the label values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
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 scatter markers. This config is identical to the CSS cursor property.
Default: 'default'
tooltip
Series-specific tooltip configuration.
See tooltip for more details.
title
string
The title to use for the series. Defaults to yName if it exists, or yKey if not.
fill
string
The colour of the fill for the markers.
Default: '#f3622d'
fillOpacity
number
The opacity of the fill for the markers.
Default: 1
stroke
string
The colour of the stroke for the markers.
Default: '#aa4520'
strokeOpacity
number
The opacity of the stroke for the markers.
Default: 1
strokeWidth
number
The width in pixels of the stroke for the markers.
Default: 1
marker
Configuration for the markers used in the series.
See marker for more details.
label
Configuration for the labels shown on top of data points.
See label for more details.
highlightStyle
Configuration for scatter series marker highlighting when a marker or a legend item is hovered over.
See highlightStyle for more details.
listeners
A map of event names to event listeners.
See listeners for more details.

tooltip

scatter > tooltip

Series-specific tooltip configuration.

scatter: {
  ...
  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;
}

marker

scatter > marker

Configuration for the markers used in the series.

scatter: {
  ...
  marker: {
    enabled?: boolean; // default: true
    shape?: string | Marker; // default: 'circle'
    size?: number; // default: 8
    maxSize?: number; // default: 30
    fill?: string;
    stroke?: string;
    strokeWidth?: number;
    formatter?: Function;
  }
}
enabled
boolean
Whether or not to show markers.
Default: true
shape
string | Marker
The 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'
size
number
The size in pixels of the markers.
Default: 8
maxSize
number
For series where the size of the marker is determined by the data, this determines the largest size a marker can be in pixels.
Default: 30
fill
string
The colour to use for marker fills. If this is not specified, the markers will take their fill from the series.
stroke
string
The colour to use for marker strokes. If this is not specified, the markers will take their stroke from the series.
strokeWidth
number
The width in pixels of the marker stroke. If this is not specified, the markers will take their stroke width from the series.
formatter
Function
Function 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.
formatter = (
    params: FormatterParams
) => Formatter;

interface FormatterParams {
  datum: any;
  fill: string;
  stroke: string;
  strokeWidth: number;
  size: number;
  highlighted: boolean;
  xKey: string;
  yKey: string;
}

interface Formatter {
  fill: string;
  stroke: string;
  strokeWidth: number;
  size: number;
}

label

scatter > label

Configuration for the labels shown on top of data points.

scatter: {
  ...
  label: {
    enabled?: boolean; // default: true
    color?: string; // default: 'rgba(70, 70, 70, 1)'
    fontStyle?: 'normal' | 'italic' | 'oblique'; // default: 'normal'
    fontWeight?: 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'; // default: 'normal'
    fontSize?: number; // default: 12
    fontFamily?: string; // default: 'Verdana, sans-serif'
  }
}
enabled
boolean
Whether or not the labels should be shown. Note: unlike other series where a label is shown for every data point, a scatter series label is only shown if it satisfies the following constraints: it doesn't overlap any markers, it doesn't overlap other labels.
Default: true
color
string
The colour to use for the labels.
Default: 'rgba(70, 70, 70, 1)'
fontStyle
string
The font style to use for the labels.
Default: 'normal'
Options: 'normal', 'italic', 'oblique'
fontWeight
string
The font weight to use for the labels.
Default: 'normal'
Options: 'normal', 'bold', 'bolder', 'lighter', '100', '200', '300', '400', '500', '600', '700', '800', '900'
fontSize
number
The font size in pixels to use for the labels.
Default: 12
fontFamily
string
The font family to use for the labels.
Default: 'Verdana, sans-serif'

highlightStyle

scatter > highlightStyle

Configuration for scatter series marker highlighting when a marker or a legend item is hovered over.

scatter: {
  ...
  highlightStyle: {
    item?: Item;
    series?: Series;
  }
}
item
Highlight style used for an individual markers when tapped or hovered over.
See item for more details.
series
Highlight style used for whole series when one of its markers is tapped or hovered over.
See series for more details.

item

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

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

series

Highlight style used for whole series when one of its markers is tapped or hovered over.

scatter: {
  ...
  highlightStyle: {
    ...
    series: {
      strokeWidth?: number;
      dimOpacity?: number;
    }
  }
}
strokeWidth
number
The stroke width of the rest of the markers when one of the markers in this series is tapped or hovered over. Use undefined for no highlight.
dimOpacity
number
The opacity of the whole series (including labels, if any) when another chart series is highlighted by hovering a series item or a legend item. Use undefined or 1 for no dimming.

listeners

scatter > listeners

A map of event names to event listeners.

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

interface NodeClickParams {
  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.