Cookbook — Homerun Map — 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/homerun-map

Homerun Map

Sometimes your scatter plot data lives in a spatial context — a baseball field, a floor plan, or a geographic region. This recipe shows how to overlay point data on a custom background graphic, creating a spatial data visualization of Giancarlo Stanton's home runs plotted on a baseball diamond.

The Visualization

Giancarlo Stanton's home runs shown with a baseball park outline based on Daren Willman's data and sports visualization work.

import { StreamXYFrame } from "semiotic" import { scaleLinear } from 'd3-scale' const velocityScale = scaleLinear() .domain([95.1, 118.2]) .range(["#9fd0cb", "#E0488B"]) const frameProps = { /* --- Data --- */ data: [{ game_date: "2017-05-08", bx: -16.29, by: 419.09, distance: 419, exit_velocity: 111.2 }, { game_date: "2017-08-25", bx: 118.41, by: 377.24, distance: 395, exit_velocity: 104.8 }, ... ], chartType: "scatter", /* --- Size --- */ size: [500,500], margin: { left: 25, right: 25, top: 25, bottom: 25 }, /* --- Process --- */ xAccessor: "bx", yAccessor: "by", yExtent: [-50], /* --- Customize --- */ pointStyle: (d12) => ({ fill: velocityScale(d12.exit_velocity), r: 6 }), showAxes: false, backgroundGraphics: ( <g transform={"translate(50,50) scale(1.85)"}> <g id="_KC_-_7"> <g id="Compass_copy_5" /> <path className="st3" d="M126.2,229.4c-18.1,0-28.1-10.7-28.1-10.7l-0.2-3.9l-16.3-19.5h-4.2l-21.6-36.7L27,108.6l-1.5-4.2 c0,0-2-13.3,4.4-21.9c8.4-11.3,60.8-49,83.7-52.2c0,0,12-3.9,25.6-0.5c13.6,3.4,71.5,41.2,77.5,47.6c5.5,5.8,10.8,21.2,4.9,36 s-19.7,32-21,37.4c-1.3,5.4-24.1,43.2-26.9,44.3c-2.8,1.1-3.9,0-3.9,0L153.5,214l0.2,4.4C153.6,218.5,144.3,229.4,126.2,229.4z" /> ... </g> </g> ), /* --- Interact --- */ enableHover: true, /* --- Annotate --- */ tooltipContent: d => { const datum = d.data || {} return ( <div className="tooltip-content"> <p>Date: {datum.game_date}</p> <p>Distance: {datum.distance}</p> <p>Velocity: {datum.exit_velocity}</p> </div> ) }, /* --- Realtime --- */ pulse: { duration: 600, color: "rgba(255,255,255,0.5)", glowRadius: 5 } } export default () => { return <StreamXYFrame {...frameProps} /> }

How It Works

The backgroundGraphics prop accepts any React node and renders it behind the data layer. Here it is an SVG group containing the baseball field outline. Points are then positioned using their spatial coordinates (bx and by):

JSX

<StreamXYFrame chartType="scatter" data={data} xAccessor="bx" yAccessor="by" yExtent={[-50]} backgroundGraphics={fieldGraphic} enableHover pointStyle={d => ({ fill: velocityScale(d.exit_velocity), r: 6 })} />

Streaming: Replaying Events Over Time

Not all streaming data comes from a live feed. Sometimes you have a small, bounded dataset — like 51 home runs over a season — but want to replay it chronologically to reveal patterns that a static scatter plot hides: when the hot streaks happened, how exit velocity changed through the season, or whether late-season homers clustered to a particular field zone.

The push API makes this trivial. Sort your data by date, then feed it to the chart with setInterval. Each push() adds one point to the canvas and the chart updates instantly. BecausewindowSize is set larger than the dataset, nothing gets evicted — every home run accumulates on the field.

JSX

// Sort chronologically, then push one at a time const sorted = [...data].sort((a, b) => new Date(a.game_date) - new Date(b.game_date) ) useEffect(() => { const id = setInterval(() => { if (chartRef.current && i < sorted.length) { chartRef.current.push(sorted[i++]) } }, 400) return () => clearInterval(id) }, [])

This pattern works for any event dataset: pitch locations over a game, customer orders over a day, sensor alerts on a floor plan. The key ingredients are:

Fixed extents — set xExtent andyExtent to the full spatial range so the scale doesn't jump as points arrive.
windowSize ≥ dataset length — ensures no points are evicted from the ring buffer.
runtimeMode="streaming" — tells StreamXYFrame to use the push API path.
A status line — show which event just arrived (date, details) so the viewer understands the timeline.

Key Takeaways

Use backgroundGraphics to place any SVG or HTML content behind your data layer, enabling spatial visualizations.
Continuous color scales (via d3-scale) can encode a quantitative dimension on each point beyond x and y position.
The push API isn't only for live data — replaying a small dataset chronologically can reveal temporal patterns that a static chart obscures.

Scatterplot — simpler point-based XY visualization
RealtimeLineChart — streaming time-series data
Canvas Interaction — large dataset scatter plot with progressive rendering