# Scatter chart

> One measure plotted against another, with a point for each row.

## Anatomy

A `<figure class="scatter-chart">` plots one measure against another from a `<table>`, with a point for each row.

The first column labels each row and the second holds its x value. Each further column is a series of y values, named by its header cell. Each row draws one point per series, so a scatter chart shows how two measures move together, such as a car's weight and its fuel economy. To show one measure over time, use a [line chart](line-chart.html).

```
<figure class="scatter-chart axis">
  <figcaption>Ad spend and signups by channel</figcaption>
  <table>
    <thead>
      <tr><th>Channel</th><th>Spend</th><th>Signups</th></tr>
    </thead>
    <tbody>
      <tr><th>Search</th><td>$12,000</td><td>340</td></tr>
      <tr><th>Social</th><td>$8,000</td><td>150</td></tr>
      <!-- One row per channel -->
    </tbody>
  </table>
</figure>
```

## Several series

Each further column is another series, in the next color, with a legend below the chart. Add `toggle` to the figure to make each legend item a button that shows or hides its series, as on the [line chart](line-chart.html#toggle). Both scales refit to the points left.

Series share the x column. A series that needs other x values puts them in rows of their own, with the other series' cells left empty.

```
<figure class="scatter-chart axis toggle">
  <figcaption>Fuel economy by weight (mpg)</figcaption>
  <table>
    <thead>
      <tr><th>Car</th><th>Weight (kg)</th><th>City</th><th>Highway</th></tr>
    </thead>
    <tbody>
      <tr><th>Civic</th><td>1300</td><td>31</td><td>40</td></tr>
      <!-- One row per car -->
    </tbody>
  </table>
</figure>
```

## Bubble sizes

Add `bubble` to the figure to size each point by a third measure. The last column holds the sizes. It is no series: every point in its row becomes a bubble whose area follows the row's size. The largest size drawn is `--md-comp-scatter-chart-bubble-size` across, 48px by default, and the rest scale by area against it. A row whose size is not a positive number draws no points.

The tooltip adds the size column's header and cell, and the marker outlines the highlighted bubble. Bubbles are partly transparent, and smaller ones are drawn over larger ones in each series, so overlaps stay readable. The chart leaves half the largest diameter of room around the plot, so a bubble at the end of a scale stays clear of the axis labels, caption and legend. A `toggle` legend refits the sizes to the bubbles left, and after `update()` each bubble grows or shrinks from its old size.

```
<figure class="scatter-chart axis bubble">
  <figcaption>Ad spend, signups and visits by channel</figcaption>
  <table>
    <thead>
      <tr><th>Channel</th><th>Spend</th><th>Signups</th><th>Visits</th></tr>
    </thead>
    <tbody>
      <tr><th>Search</th><td>$12,000</td><td>340</td><td>9,000</td></tr>
      <!-- One row per channel; the last column sizes its bubble -->
    </tbody>
  </table>
</figure>
```

## Values and scale

Cells read as in a line chart. A cell's number is its `data-value`, or its text without currency signs, percent signs or grouping commas. The tooltip shows the cell's text as written. A row whose x cell is not a number draws no points, and a y cell that is not a number draws no point for its series.

Both scales run from a little below the lowest value to a little above the highest. Set `data-x-min` and `data-x-max` on the figure to fix the x scale, and `data-min` and `data-max` to fix the y scale. x grows toward the inline end, so it runs leftward in a right-to-left page.

Add `axis` to label both scales at round values, with a grid line at each: y beside the plot and x below it. Each scale's labels repeat its cells' currency or percent sign. The labels are hidden from assistive technology. The table still carries the values.

```
<figure class="scatter-chart axis" data-x-min="0" data-min="0">
  <figcaption>Ad spend and signups by channel</figcaption>
  <table><!-- … --></table>
</figure>
```

## Accessibility

The table is the chart's text alternative. Give it a header row and a header cell per row, and name the chart with a `<figcaption>`. The drawn chart, labels and legend are hidden from assistive technology.

The plot is one Tab stop named by the caption. Keyboard focus shows the first point. The arrow keys step through the points in table order: right and down go to the next point, left and up to the one before. Within a row the series go in column order. Home and End jump to the first and last points, and Escape hides the tooltip. The arrows keep this meaning in a right-to-left page, since table order is not a direction on screen. The pointer shows the point nearest to it. The tooltip is a polite live region, so a screen reader hears the row, its x value and the series value as it moves. In forced colors the points keep their colors so the legend still keys them.

## JavaScript

`AutoInit()` starts every `.scatter-chart`. To start one yourself, call `ScatterChart.init`. After changing its table, call `update()` to redraw it in place, or put `data-watch` on the figure and it redraws itself. Points move from their old places to the new ones, or appear at once with reduced motion. It has the line chart's options and methods, plus `xMin` and `xMax` for the x scale.

```
const chart = Expressive.ScatterChart.init(document.querySelector('.scatter-chart'), { xMin: 0 });
chart.show(2);   // highlight the third point in table order; -1 hides the tooltip
chart.update();  // redraw from the table; focus and the highlighted point stay
chart.destroy(); // remove the drawing and show the table again
```

## Tokens

Override these on the `.scatter-chart`.

| Token | Default |
| --- | --- |
| `--md-comp-scatter-chart-height` | 240px |
| `--md-comp-scatter-chart-point-size` | 8px |
| `--md-comp-scatter-chart-bubble-size` | 48px, the largest `bubble` diameter |
| `--md-comp-scatter-chart-grid-color` | `outline-variant` |
| `--md-comp-scatter-chart-axis-width` | 48px, room for the y `axis` labels |
| `--md-comp-scatter-chart-color-1` … `-4` | `primary`, `tertiary`, `secondary`, `on-surface-variant` |

For a selective Sass build, include `"scatter-chart"` in `$components`.