Recipes — Streaming Migration 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/recipes/streaming-migration-map

Streaming Migration Map

Recipe

semioticsemiotic/georeact

A seasonal particle flow map inspired by earth.nullschool.net and hint.fm/wind. Six animal migration routes cycle through the year on a rolling 2-quarter window. As seasons change, particles reverse direction — Arctic Terns stream south while Humpback Whales head to the tropics, then everything flips. The underlying data distribution shifts continuously, demonstrating how streaming visualizations can reveal temporal patterns.

Preview

Year 1 · 24 segments · 6 species

Jan – Mar

Winter–Spring

Apr – Jun

Spring–Summer

Jul – Sep

Summer–Fall

Oct – Dec

Fall–Winter

Arctic TernNorthbound (5/10 legs)

Monarch ButterflyNorthbound (3/6 legs)

Humpback WhaleTo tropics + To Antarctic (3/6 legs)

Barn SwallowNorthbound (4/8 legs)

Amur FalconSouthbound + Northbound (5/8 legs)

White StorkNorthbound (4/8 legs)

Winter → Summer

Equal Earth projection

Anatomy

Seasonal rolling window — a 2-quarter window advances every 3 seconds through Q1+Q2 → Q2+Q3 → Q3+Q4 → Q4+Q1, then cycles back. The quarter timeline bar highlights the active window. Each flow is tagged with its peak migration quarter; only flows matching the current window are rendered.
Bidirectional migration — each species has southbound and northbound flows with reversed source/target. The Arctic Tern heads south in Q3 and north in Q1. When the window shifts, particles literally reverse direction on the map.
FlowMap + particles — showParticles with high maxPerLine (30) and spawnRate (0.18) creates dense wind-map-like streams along great-circle arcs. Per-species particle color via a function on the flow datum.
Live legend — all six species are always shown in the legend. Active species display their current migration direction (Southbound, Northbound, To tropics, To Antarctic). Inactive species dim to 35% opacity.
CategoryColorProvider — ensures stable species → color mapping as the flow set changes each window step.

Customization

What	Where	How
Window duration	`setInterval` timing	Change from 3000ms for faster/slower seasonal cycling
Window size	`getWindowQuarters`	Return 3 quarters for a wider window, or 1 for a narrower one
Particle density	`particleStyle.maxPerLine`	Increase for denser wind-map look (default 30)
Particle speed	`particleStyle.speedMultiplier`	Higher = faster flow (default 0.7)
Line style	`lineType`	`"geo"` for great circles, `"line"` for straight projected lines
Background map	`areas`	Pass GeoJSON features, or `"world-50m"` for higher resolution
Projection	`projection`	Try `"orthographic"` with `dragRotate` for a globe
Dark theme	`frameProps.background` + `areaStyle`	Change fill/stroke colors, or remove for light mode
Species colors	`CategoryColorProvider colors`	Swap the color map for a different palette

How It Works

Each species' migration is split into two legs — southbound and northbound — each tagged with a peak quarter (1–4). The Humpback Whale, a southern-hemisphere animal, reverses the pattern: it heads to the tropics in Q2 and returns to Antarctic waters in Q4.

A windowPos state (0–3) advances on a 3-second interval, cycling back to 0 after reaching 3. The getWindowQuarters helper maps each position to two adjacent quarters: position 0 → [Q1, Q2], position 1 → [Q2, Q3], etc. Position 3 wraps around to [Q4, Q1].

Visible flows are filtered with useMemo: only flows whose tagged quarter falls within the current window are passed to FlowMap. When the window shifts and a flow's quarter drops out, it disappears; when a flow's quarter enters, it appears with fresh particles. The net effect is that particles reverse direction as seasons change — a visual representation of how the character of the data stream changes over time.

Under the hood, FlowMap converts each flow edge into a projected line on StreamGeoFrame's canvas. The GeoParticlePool spawns particles along each polyline path, recycling them when they reach t=1. Because FlowMap is a bounded HOC, swapping the flows prop is all that's needed — no imperative push API required.

Connecting to Real Data

Replace the timer with a real seasonal data source — for example, a WebSocket that pushes migration sightings as they're reported:

// Live sighting feed — each message is a flow segment const [flows, setFlows] = useState([]) useEffect(() => { const ws = new WebSocket("wss://your-api/migrations") ws.onmessage = (e) => { const sighting = JSON.parse(e.data) // { source: "iceland", target: "azores", species: "Arctic Tern", ... } setFlows(prev => [...prev, sighting]) } return () => ws.close() }, []) <FlowMap flows={flows} nodes={nodes} showParticles ... />

For high-frequency GPS tracks, use StreamGeoFrame with the push API for better performance:

const geoRef = useRef() ws.onmessage = (e) => { geoRef.current.push(JSON.parse(e.data)) } <StreamGeoFrame ref={geoRef} projection="equalEarth" xAccessor="lon" yAccessor="lat" decay={{ type: "linear", minOpacity: 0.1 }} showParticles ... />

Flow Map — geographic flow visualization
Minard's Map — another flow map recipe with cross-linked charts
Geo Particles — particle system reference
Realtime Charts — push API and streaming patterns

Source Code

Abbreviated for readability — data arrays and steps are truncated. See the full runnable source in docs/src/examples/recipes/.

JSX

1 import React, { useState, useEffect, useCallback, useMemo } from "react"
2 import { CategoryColorProvider } from "semiotic"
3 import { FlowMap } from "semiotic/geo"
4 
5 // Each species has southbound + northbound flows tagged with a peak quarter.
6 // A rolling 2-quarter window filters which flows are visible.
7 
8 const migrationNodes = [
9  { id: "iceland", lon: -20, lat: 64 },
10  { id: "azores", lon: -28, lat: 38 },
11  // ... 30 nodes total (see full source)
12 ]
13 
14 function makeFlows(segments, species, quarter, direction) {
15  return segments.map(([source, target, value]) => ({
16  source, target, value, species, quarter, direction,
17  }))
18 }
19 
20 const speciesConfig = [
21  {
22  name: "Arctic Tern", color: "#00e5ff",
23  migrations: [
24  ...makeFlows([
25  ["iceland", "azores", 7], ["azores", "westAfrica", 6], ...
26  ], "Arctic Tern", 3, "Southbound"),
27  ...makeFlows([
28  ["weddellSea", "namibiaCoast", 5], ["namibiaCoast", "gulfOfGuinea", 5], ...
29  ], "Arctic Tern", 1, "Northbound"),
30  ]
31  },
32  // ... 6 species total, each with southbound + northbound legs
33 ]
34 
35 const allFlows = speciesConfig.flatMap(s => s.migrations)
36 const speciesColorMap = Object.fromEntries(speciesConfig.map(s => [s.name, s.color]))
37 
38 // Window positions: Q1+Q2, Q2+Q3, Q3+Q4, Q4+Q1
39 function getWindowQuarters(pos) {
40  return [(pos % 4) + 1, (pos + 1) % 4 + 1]
41 }
42 
43 export default function StreamingMigrationMap({ width = 900 }) {
44  const height = Math.round(width * 0.55)
45  const [windowPos, setWindowPos] = useState(0)
46  const [playing, setPlaying] = useState(true)
47 
48  // Advance window every 3 seconds, cycling back to Q1+Q2
49  useEffect(() => {
50  if (!playing) return
51  const timer = setInterval(() => {
52  setWindowPos(prev => (prev + 1) % 4)
53  }, 3000)
54  return () => clearInterval(timer)
55  }, [playing])
56 
57  const windowQ = useMemo(() => getWindowQuarters(windowPos), [windowPos])
58  const visibleFlows = useMemo(
59  () => allFlows.filter(f => windowQ.includes(f.quarter)),
60  [windowQ]
61  )
62 
63  return (
64  <CategoryColorProvider categories={speciesNames} colors={speciesColorMap}>
65  {/* Quarter timeline bar showing active window */}
66  <div style={{ display: "flex", gap: 2 }}>
67  {quarters.map((q, i) => (
68  <div key={i} style={{
69  flex: 1,
70  background: windowQ.includes(i + 1) ? "#1b3a5c" : "#0f1a2a",
71  border: \`1px solid \${windowQ.includes(i+1) ? "#2a5a8a" : "#1a2535"}\`,
72  borderRadius: 4, padding: "6px 8px", textAlign: "center",
73  transition: "all 0.4s ease",
74  }}>
75  <div style={{ fontWeight: 600, fontSize: 12 }}>{q.label}</div>
76  <div style={{ fontSize: 10 }}>{q.months}</div>
77  </div>
78  ))}
79  </div>
80 
81  <FlowMap
82  flows={visibleFlows}
83  nodes={migrationNodes}
84  areas="world-110m"
85  projection="equalEarth"
86  lineType="geo"
87  edgeColorBy="species"
88  showParticles
89  particleStyle={{
90  radius: 2,
91  color: (d) => speciesColorMap[d?.species] || "#fff",
92  opacity: 0.9, speedMultiplier: 0.7,
93  maxPerLine: 30, spawnRate: 0.18
94  }}
95  frameProps={{
96  areaStyle: () => ({ fill: "#1b2838", stroke: "#2a3f55" }),
97  background: "#0d1b2a"
98  }}
99  />
100  </CategoryColorProvider>
101  )
102 }