Skip to content

Map — Flows

MapFlow draws flows between places over a map: capital, goods, influence. Each flow is an arc from one point to another; its width is the value it carries, its color the type, an arrowhead marks where it goes. It is built on Map — the same geometry, projections and theme — and takes the same { nodes, links } shape as Graph and Sankey.

Experimental. MapFlow is not covered by the 1.0 stability guarantee — its rendering and options may change without a major-version bump.

The smallest case: three places, three flows, two types. Hover an arc for its details; click it to pin the tooltip.

Data

Nodes are places, links are flows between them. A node is placed by its own coordinates or by a country on the map.

new RareCharts.MapFlow('#chart', {
  topoUrl: '/assets/charts/data/maps/world/level-0/world-atlas/countries-110m.json',
  topoObject: 'countries',
  fitTo: 'links',                                  // frame the flows, not the whole world
  linkWidth: { by: 'weight' },                     // width from a relative weight, not an amount
  linkTypes: {
    goods:  { color: '#8a5a2b', label: 'goods' },
    silver: { color: '#5b6b7d', label: 'silver', dash: '6 4' },
  },
}).setData({
  nodes: [
    { id: 'LDN', label: 'London', coords: [-0.13, 51.51] },   // [longitude, latitude]
    { id: 'CN',  label: 'China',  country: '156' },           // the country's centroid
  ],
  links: [
    { from: 'CN', to: 'LDN', type: 'silver', weight: 2, label: 'silver and tea', start: 1800, end: 1860 },
  ],
});
  • coords — [longitude, latitude], exact.
  • country — a feature id of the map (with world-atlas, the ISO 3166-1 numeric code). The node sits at the centroid of the country's largest polygon, so overseas territories don't pull it into the ocean.
  • color — the dot's color (default: the theme's text color).
  • Flows — source / target (or from / to; a flows array is accepted for links), plus type, value, label, start / end and any fields of your own. One flow per type: a types: [...] array is not read, so a pair that carries two types is two flows. A flow to an unknown node is dropped with a console warning.

Drawing

  • Each arc follows the great circle between its ends and bows slightly to one side, so the flows A → B and B → A never sit on top of each other. Several flows in one direction fan out. An arc too short to show a line between two close places is drawn as its arrowhead alone, pointing at the target.
  • The arc is cut where the projection cuts the map. A flow that crosses the edge of a flat map — Tokyo → San Francisco across the Pacific — leaves at one side and comes back at the other, each part bowed on its own. On 'orthographic' only the near side of the globe is drawn: a place behind it has no dot, a flow toward it runs to the horizon without an arrowhead, and a flow between two hidden places is not drawn (nor in the Tab order).
  • Width is value through a square-root scale (linkWidth); a flow without a value is drawn at the minimum width. The tooltip prints the value; linkWidth: { by: 'weight' } takes the width from another field instead, for a relative size with no amount to print — as in the demos, whose data is illustrative.
  • Color and dash come from the flow's type through linkTypes. The legend lists the types in use; click one to hide or show its flows, double-click one to keep it alone, and Show all brings every flow back. A flow's tooltip lists its sources ([{ url, title }] or URLs) as links once pinned; only http(s), site-relative and # links are made clickable.
  • Labels of places give way to each other: a place with more flow keeps its label first, a label that would overlap is left to the tooltip.

Time

Flows carry start and end — years, YYYY-MM or ISO dates; a missing bound is open. Turn on timeframes, navigator or both and the map gets a time scale, as TimeSeries has: timeframes puts period buttons in the header, navigator a strip under the map with a time axis that shows how many flows run over time — brush it to pick any period. Flows outside the period are hidden (timeWindowMode: 'dim' fades them instead), and a place whose flows are all outside fades with them.

const chart = new RareCharts.MapFlow('#chart', {
  timeframes: [
    { key: '1957', label: '1957', range: ['1957-01-01', '1957-12-31'] },   // an era
    { key: '1968', label: '1968', range: ['1968-01-01', '1968-12-31'] },
    'ALL',
  ],
  defaultView: ['1957-01-01', '1957-12-31'],   // the period shown first
  navigator: true,
});

chart.setTimeframe('1968');
chart.setTimeWindow(null, '1970');   // everything up to the end of 1970; the buttons and the brush follow
chart.onViewChange(([from, to]) => { /* … */ });

Without the time scale, setTimeWindow(from, to) filters the flows on its own, and your page can drive it from any control.

Options

Every geometry option of Map works the same here (topoUrl, topoData, geoUrl, geoData, topoObject, projection, rotate, fitPadding, featureFilter, clipExtent, defaultFill, borderColor, graticule, zoom…); common options (title, subtitle, source, note, controls, theme) are on the Settings page.

Option Type Default Description
heightnumber420Card height in px — title, period buttons, navigator and footer included, the map gets the rest; the type legend adds its own row
nodes / linksarray—Data at construction; or call setData({ nodes, links })
linkTypesobject—{ type: { color, dash?, label } }; a flow without a type is drawn in the muted color; a type not described here takes a palette color
hiddenLinkTypesarray[]Types hidden at start; the legend shows them dimmed and turns them on
linkLegendbooleantrueThe type legend (shown with two or more types, or when linkTypes is set)
linkWidthobject{ by: 'value', scale: 'sqrt', min: 1, max: 6 }Arc width from a value field; scale: 'linear' also available. The arrowhead grows with the arc, more slowly
bendnumber0.18How far an arc bows to its side: bend × 0.6 of the arc's length, at most bend × 90 px; parallel flows fan out from there
timeZonestring'local''local' or 'UTC': the zone the flows' start / end, the time window and the view bounds are read in, the timeframes cut in, and the navigator counts and labels its periods in. A year or a month is a period; as an end it runs to its last moment. See Dates and time zones
timeframesarray | true—Period buttons in the header: '1Y', 'ALL'… or { key, label, range: [from, to] }
navigatorboolean | object—A brushable strip with a time axis under the map
defaultViewarray—[from, to] shown first with the time scale on
defaultTimeframestring—Key of the timeframe shown first (instead of defaultView)
timeWindowarraynull[from, to] at start without the time scale; then setTimeWindow()
timeWindowModestring'hide'What happens to flows outside the window: 'hide' or 'dim'
fitTostring'features''links' fits the projection to the places and the arcs between them instead of the whole map — a great circle that runs far from its ends and the bow of each arc stay inside the frame; the frame covers every flow, so the time window and the legend do not move it. An arc that crosses the projection's cut (the antimeridian, Mercator's polar edge) is framed by its pieces, their ends on the cut included.
nodeRadiusnumber4Dot radius in px
nodeLabelsbooleantruePlace labels
tooltipFormatfunction—({ node, links }) => html for a place
regionTooltipFormatfunction—({ feature, item }) => html for a country under the flows (Map’s tooltipFormat); item is always null — MapFlow takes no region data
linkTooltipFormatfunction—({ link, source, target }) => html for a flow
valueFormatfunctionlocale numberv => string for a flow’s value in its tooltip, as on Sankey and Graph

Methods

chart.setData({ nodes, links });
chart.setTimeWindow(from, to);
chart.setTimeframe(key);                // with timeframes; setView([from, to]), getView(), onViewChange(fn)
chart.setLinkTypesVisible(['goods']);   // what the legend does; null shows all
chart.whenReady().then(() => { /* the map and the flows are drawn */ });   // as on Map

Interaction

Hover a place or an arc for its tooltip. Click an arc to pin its tooltip — links inside it stay clickable; click elsewhere or press Escape to close it. Arcs are in the Tab order: Enter pins the tooltip of the focused one. With arcs to focus, the map is a group named by ariaLabel, else from title / subtitle, and each arc is a button named "from → to, type, label".

Legend — click a type to hide or show its flows, double-click it to keep it alone, Show all to bring all back; its buttons are in the Tab order, and Enter or Space keeps focus on the one pressed. See Interactive legend.

Zoom — with zoom: true, as on Map: Ctrl/⌘ + wheel or a pinch zooms, two fingers on a phone; a plain wheel scrolls the page. Arcs keep their width; dots, labels and arrowheads keep their size and move with the map, and the labels are placed again, so places that crowd each other at first get theirs as you zoom in.

Not in this version

Moving particles along the arcs, clustering places on zoom, choropleth values under the flows, and hand-bent curves.