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

// Loading...

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.

// Loading...

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 everlap any markers
• labels don't overlap other labels

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

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.

// Loading...

API Reference

scatter: {
  ...
  tooltip: {
    enabled?: boolean; // default: true
    renderer?: Function;
  }
}

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;
}

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;
  }
}

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;
}

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'
  }
}

scatter: {
  ...
  highlightStyle: {
    fill?: string; // default: 'yellow'
    stroke?: string;
  }
}

scatter: {
  ...
  listeners: {
    nodeClick?: Function;
  }
}

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.