Dumbbell

A dumbbell compares values within each category: a dot per value on the value axis, joined by a connector from the smallest to the largest. It reads the gap between groups, such as pay by sex across roles or life expectancy across two years.

The dumbbell ships as its own package, @graphysdk/geom-dumbbell, on a 0.x version line. While it is on 0.x, a minor release may change its aesthetics, style parts or look; pin a caret range (^0.1.0) to take only patches. Tell us what works and what doesn’t on Discord.

Install

npm install @graphysdk/geom-dumbbell

It peer-depends on @graphysdk/react and nothing else. Register the plugin once with createGraphyKit, which adds kit.geom.dumbbell() and binds kit.GraphProvider to the same plugin:

import {
  createGraphyKit,
  GraphRenderer,
  highlight,
  styles,
} from '@graphysdk/react';
import { dumbbell } from '@graphysdk/geom-dumbbell';

const kit = createGraphyKit({ plugins: [dumbbell] });

Long data: one row per dot

Map the category to x, the value to y and the group to color. The geom groups the dots of each category itself, so the legend, palette, tooltip order and highlights all come from the color scale:

const data = {
  columns: [{ key: 'role' }, { key: 'sex' }, { key: 'salary' }],
  rows: [
    { role: 'Product', sex: 'Women', salary: 125 },
    { role: 'Product', sex: 'Men', salary: 140 },
    { role: 'Eng', sex: 'Women', salary: 118 },
    { role: 'Eng', sex: 'Men', salary: 132 },
    // …
  ],
};

const spec = kit.pipe(
  kit.createSpec({ x: 'role', y: 'salary', color: 'sex' }),
  kit.geom.dumbbell(),
  kit.scale.x.discrete(),
  kit.scale.y.continuous(),
  kit.scale.color.palette()
);

export function PayGap() {
  return (
    <kit.GraphProvider spec={spec} data={data}>
      <GraphRenderer />
    </kit.GraphProvider>
  );
}

A dumbbell encodes position, not length, so the value axis fits the data rather than holding zero the way a bar axis does, and the gaps read at full width. A category with one dot draws the dot and no connector. With three or more dots, the connector spans the smallest to the largest and the others sit on it. Leave color unmapped and every dot takes the default geom colour, with no legend.

Wide data

When each group is its own column, reshape it to long in the spec:

const data = {
  columns: [{ key: 'region' }, { key: '1970' }, { key: '2020' }],
  rows: [
    { region: 'Europe', 1970: 71, 2020: 81 },
    { region: 'Africa', 1970: 45, 2020: 61 },
    // …
  ],
};

const spec = kit.pipe(
  kit.createSpec({ x: 'region', y: 'years', color: 'year' }),
  kit.transform.reshape({
    keep: ['region'],
    reshape: ['1970', '2020'],
    keyName: 'year',
    valueName: 'years',
  }),
  kit.geom.dumbbell(),
  kit.scale.x.discrete(),
  kit.scale.y.continuous(),
  kit.scale.color.palette(),
  kit.coord.flip()
);

Horizontal

Add kit.coord.flip(), as for a horizontal bar. The categories move to the vertical axis and the connectors lie across.

Styling

The dots are the layer’s observations and style through the kind’s own builder. The connector is a part beside them, with a builder of its own:

Builder	Properties	Default
`kit.style.geom.dumbbell()`	`fill`, `stroke`, `alpha`, `fillAlpha`, `strokeAlpha`, `saturation`, `size`, `strokeWidth`	Fill from the scale, 10px, white border
`kit.style.geom.dumbbell.connector()`	`stroke`, `alpha`, `strokeWidth`, `dashArray`	A neutral grey, 2px, solid

const spec = kit.pipe(
  // …
  styles({
    defaults: [
      kit.style.geom.dumbbell({ size: 14, strokeWidth: 2 }),
      kit.style.geom.dumbbell.connector({ strokeWidth: 6, stroke: '#d9d4c7' }),
    ],
  })
);

An entry that names no part, such as style.geom({ fill: 'navy' }), styles the dots like any other geom’s observations and never the connector. The connector takes no colour from the scale: it joins dots of different groups, so a scale colour would be arbitrary. A connector entry’s where is tested against the category’s first dot, so write it against what every dot of the category shares, such as its x.

Hover and highlight

Hovering a category emphasises its whole dumbbell. The tooltip lists every dot in legend order, with the dot nearest the cursor marked in place. A highlight matches dots. A connector is raised only when every dot it joins is: highlighting one group raises that group’s dots and no connector, and highlighting one category raises its whole dumbbell.

const spec = kit.pipe(
  // …
  highlight({ variable: 'role', eq: 'Eng' })
);

Data labels

dataLabels.showDataLabels prints every dot’s value beside it. Under the default position: 'auto' each label sits outward from the connector — the low dot’s away from the high one and the high one’s away from it — so the gap the chart is read from stays clear. An explicit position puts every label on the side justify names, for a chart that wants them in a row.

const spec = kit.pipe(
  // …
  kit.geom.dumbbell({ dataLabels: { showDataLabels: true } })
);

The label prints the dot’s y, formatted as the value axis formats it; map label to print another column instead. showStackTotals and showCategoryLabels are bar settings and a dumbbell places neither.

Not yet supported

The editor’s chart-type picker and the chart agent. In editable mode the dumbbell renders, hovers, selects and takes annotations on its dots, but it is authored in code.
Aggregation. Duplicate rows for one category and group all draw; aggregate them first with transform.aggregate().

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Install

Long data: one row per dot

Wide data

Horizontal

Styling

Hover and highlight

Data labels

Not yet supported

​Install

​Long data: one row per dot

​Wide data

​Horizontal

​Styling

​Hover and highlight

​Data labels

​Not yet supported

Install

Long data: one row per dot

Wide data

Horizontal

Styling

Hover and highlight

Data labels

Not yet supported