Results:
Loading...
Javascript Data GridJavascriptReact Data GridReactAngular Data GridAngularVue Data GridVue

JavaScript ChartsScatter 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.

To create a simple scatter chart we need to use series type 'scatter'. We also have to provide the xKey and yKey properties. A minimal 'scatter' series config would therefore look like this:

series: [{
    type: 'scatter',
    xKey: 'time',
    yKey: 'mm',
}]

Using this simple series config, we can produce the following chart which 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 minimum marker size. The marker also has the maxSize config, which only applies when the sizeKey is set.

marker: {
    size: 8,       // defaults to 8
    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 size), 200 to a marker of size 30 (the maxSize), 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 shape 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 (xName, yName and sizeName) to get nice looking tooltips.
  • The series title is also provided which is reflected in the legend and displayed as the title in the tooltips.

Bubble Chart with Labels

Scatter series can be configured to use labels. Unlike 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 set the label.enabled config of a series to true and 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 opening 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 affects label placement.

API Reference

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

xKey *
string
The key to use to retrieve x-values from the data.
yKey *
string
The key to use to retrieve y-values from the data.
type
'scatter'
Configuration for the scatter series.
marker
AgScatterSeriesMarker<DatumType>
Configuration for the markers used in the series. 
marker: AgScatterSeriesMarker<DatumType>;

interface AgScatterSeriesMarker<DatumType> {
  // If sizeKey is used, explicitly specifies the extent of the domain of it's values. 
  domain?: [ number, number ];
  // 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?: AgCartesianSeriesMarkerFormatter<DatumType>;
  // Whether or not to show markers. 
  enabled?: boolean;
  // The shape to use for the markers. You can also supply a custom marker by providing a `Marker` subclass. 
  shape?: MarkerShape;
  // The size in pixels of the markers. 
  size?: PixelSize;
  // For series where the size of the marker is determined by the data, this determines the largest size a marker can be in pixels. 
  maxSize?: PixelSize;
  // The colour to use for marker fills. If this is not specified, the markers will take their fill from the series. 
  fill?: CssColor;
  // Opacity of the marker fills. 
  fillOpacity?: Opacity;
  // The colour to use for marker strokes. If this is not specified, the markers will take their stroke from the series. 
  stroke?: CssColor;
  // The width in pixels of the marker stroke. If this is not specified, the markers will take their stroke width from the series. 
  strokeWidth?: PixelSize;
  // Opacity of the marker strokes. 
  strokeOpacity?: Opacity;
}

type AgCartesianSeriesMarkerFormatter = 
      (params: AgCartesianSeriesMarkerFormatterParams<DatumType>) => AgCartesianSeriesMarkerFormat 
    | undefined


interface AgCartesianSeriesMarkerFormatterParams<DatumType> {
  xKey: string;
  yKey: string;
  datum: DatumType;
  fill?: CssColor;
  stroke?: CssColor;
  strokeWidth: PixelSize;
  size: number;
  highlighted: boolean;
  seriesId: string;
}

type CssColor = string

type PixelSize = number

interface AgCartesianSeriesMarkerFormat {
  fill?: CssColor;
  stroke?: CssColor;
  strokeWidth?: PixelSize;
  size?: PixelSize;
}

type MarkerShape = 
      'circle' 
    | 'cross' 
    | 'diamond' 
    | 'heart' 
    | 'plus' 
    | 'triangle' 
    | any


type Opacity = number
label
AgScatterSeriesLabelOptions
Configuration for the labels shown on top of data points. 
label: AgScatterSeriesLabelOptions;

interface AgScatterSeriesLabelOptions {
  // 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
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.
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.
title
string
The title to use for the series. Defaults to yName if it exists, or yKey if not.
tooltip
AgScatterSeriesTooltip
Series-specific tooltip configuration. 
tooltip: AgScatterSeriesTooltip;

interface AgScatterSeriesTooltip {
  // Function used to create the content for tooltips. 
  renderer?: (params: AgScatterSeriesTooltipRendererParams) => string | AgTooltipRendererResult;
  // Whether or not to show tooltips when the series are hovered over. 
  enabled?: boolean;
  // The position of the tooltip. By default the tooltip follows the mouse pointer. 
  position?: AgTooltipPositionOptions;
  // Configuration for tooltip interaction. 
  interaction?: AgSeriesTooltipInteraction;
}

interface AgScatterSeriesTooltipRendererParams {
  // sizeKey as specified on series options. 
  sizeKey?: string;
  // sizeName as specified on series options. 
  sizeName?: string;
  // labelKey as specified on series options. 
  labelKey?: string;
  // labelName as specified on series options. 
  labelName?: string;
  // 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;
  // Tooltip title text color. 
  color?: string;
  // Tooltip title background color. 
  backgroundColor?: string;
}

type AgTooltipPositionOptions = 
      AgMovingTooltipPositionOptions


interface AgMovingTooltipPositionOptions {
  // The type of positioning for the tooltip. By default, the tooltip follows the pointer. 
  type: AgTooltipPositionType;
  // The horizontal offset in pixels for the position of the tooltip. 
  xOffset?: PixelSize;
  // The vertical offset in pixels for the position of the tooltip. 
  yOffset?: PixelSize;
}

type AgTooltipPositionType = 'pointer' | 'node'

type PixelSize = number

interface AgSeriesTooltipInteraction {
  // Set to true to keep the tooltip open when the mouse is hovering over it, and enable clicking tooltip text 
  enabled: boolean;
}
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;
  // The listener to call when a node (marker, column, bar, tile or a pie sector) in the series is double clicked. 
  nodeDoubleClick?: (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;
}
nodeClickRange
AgChartInteractionRange
Range from a node a click triggers the listener. 
nodeClickRange: AgChartInteractionRange;

type AgChartInteractionRange = 
      PixelSize 
    | 'exact' 
    | 'nearest'


type PixelSize = number