Cookbook — Swarm Plot — Semiotic

Home · Getting Started · Charts · Features · Playground

This page requires JavaScript for interactive chart demos.

AI / Machine-readable docs: llms.txt · llms-full.txt · CLAUDE.md · schema.json · API Reference · Examples

View on GitHub · npx semiotic-ai for CLI access

Machine-readable page content

Canonical: https://semiotic.nteract.io/cookbook/swarm-plot

Swarm Plot

When you have many data points along a single quantitative axis, plotting them as a strip results in severe overplotting. A beeswarm (or swarm) plot applies a collision force to spread points vertically while preserving their quantitative position. This recipe uses StreamOrdinalFrame's swarm type with custom marks to create a labeled beeswarm of weekly box office totals.

The Visualization

Swarm plots allow you to position your data based on a numerical value but apply a collision force to prevent overlapping.

This page uses box office data from Box Office Mojo.

import { StreamOrdinalFrame } from "semiotic" const frameProps = { /* --- Data --- */ data: [{ date: "2016-1", total: 288653430 }, { date: "2016-2", total: 213602441 }, ... ], chartType: "swarm", /* --- Size --- */ size: [700,450], margin: { left: 20, top: 50, bottom: 75, right: 20 }, /* --- Layout --- */ projection: "horizontal", /* --- Process --- */ oAccessor: "none", rAccessor: "total", rExtent: [0,], /* --- Customize --- */ title: "Weekly(1-52) Box Office Totals from 2016 - mid 2017", showAxes: true, /* --- Interact --- */ enableHover: true, /* --- Annotate --- */ tooltipContent: d => ( <div className="tooltip-content"> {d.date} - {Math.round(d.total / 1000000)}m </div> ) } export default () => { return <StreamOrdinalFrame {...frameProps} /> }

How It Works

The swarm type applies a force-directed collision layout to position pieces without overlap. A customMark renders each point as a colored circle with the week number as a label inside:

JSX

type: { type: "swarm", r: 14, customMark: d => { const [year, week] = d.date.split("-") return ( <g> <circle r={11} stroke={year === "2016" ? theme[0] : theme[2]} fill={year === "2016" ? theme[0] : theme[2]} /> <text fill={year === "2016" ? "white" : "black"} fontWeight="bold" textAnchor="middle" y=".4em" > {week} </text> </g> ) } }

The r parameter controls the collision radius, ensuring circles do not overlap. The horizontal projection andoAccessor: "none" place all points in a single row, spread along the quantitative axis:

JSX

projection: "horizontal", oAccessor: "none", rAccessor: "total", rExtent: [0]

Key Takeaways

The swarm type applies collision detection to prevent overlapping while preserving quantitative positioning.
The r parameter on the swarm type controls the spacing between pieces.
customMark gives full control over each piece's appearance, enabling labeled circles or any other glyph.
Using oAccessor: "none" with a horizontal projection collapses all data into a single row for a pure swarm layout.

StreamOrdinalFrame — the underlying frame with swarm type support
Ridgeline Plot — another way to show distributions across categories