d3-sankey-diagram


Sankey diagrams show flows between processes or relationships between sets. This library, is a reusable d3 diagram featuring:
- automatic layout
- multiple types of flow
- loops / reversed flows
- flow routing across layers

See the demo for examples of these.

d3-sankey-diagram versions v0.6 and up are based on d3 v4.

Installation

Install using npm if you are using browserify or the like:
``js
npm install d3-sankey-diagram
`

Or download the standalone bundle and include in your page as
`html

`

Usage

`js
var layout = d3.sankey()
.extent([[100, 10], [840, 580]]);

var diagram = d3.sankeyDiagram()
.linkColor(function(d) { return d.color; });

d3.json('uk_energy.json', function(energy) {
layout.ordering(energy.order);
d3.select('#sankey')
.datum(layout(energy))
.call(diagram);
});
`

Try more live examples.

If you use the Jupyter notebook, try
ipysankeywidget.

d3-sankey-diagram works both in node (using jsdom) and in the browser.

Contributing 🎁

Thanks for your interest in contributing! To get started see CONTRIBUTING.md and our code of
conduct. We have a Roadmap showing what we
are working on, and you can browse the list of good first issues for ideas.

Documentation

`js
var layout = d3.sankey();

var graph = layout({
nodes: [
{"id": "a", "title": "Source"},
{"id": "b", "title": "Stage 1"}
],
links: [
{"source": "a", "target": "b", "type": "x", "value": 2}
]
});
// Resulting graph object can be used as datum for d3.sankeyDiagram() below
`

#### Data accessors

# layout.nodes([nodes])

If nodes is specified, sets the nodes accessor to the specified function and
returns this layout. If nodes is not specified, return the current accessor, which defaults to:
`js
function nodes(graph) {
return graph.nodes;
}
`

# layout.links([links])

If links is specified, sets the links accessor to the specified function and
returns this layout. If links is not specified, return the current accessor, which defaults to:
`js
function links(graph) {
return graph.links;
}
`

# layout.nodeId([nodeId])

If nodeId is specified, sets the node id accessor to the specified function and
returns this layout. If nodeId is not specified, return the current accessor, which defaults to:
`js
function nodeId(d) {
return d.id;
}
`

# layout.sourceId([sourceId])

# layout.targetId([targetId])

If sourceId/targetId is specified, sets the link source/target id accessor to the specified function and
returns this layout. If sourceId/targetId is not specified, return the current accessor, which defaults to:
`js
function sourceId (d) {
return {
id: typeof d.source === 'object' ? d.source.id : d.source,
port: typeof d.sourcePort === 'object' ? d.sourcePort.id : d.sourcePort
}
}
// similarly for targetId
`

See below for more discussion of ports. If this accessor returns a string, it is
interpreted as the node id and the port is set to undefined.

# layout.nodeBackwards([nodeBackwards])

If nodeBackwards is specified, sets the node direction accessor to the specified function and
returns this layout. If nodeBackwards is not specified, return the current accessor, which defaults to:
`js
function nodeBackwards(d) {
return d.direction && d.direction.toLowerCase() === 'l';
}
`

# layout.linkValue([linkValue])

If linkValue is specified, sets the link value accessor to the specified function and
returns this layout. If linkValue is not specified, return the current accessor, which defaults to:
`js
function linkValue(d) {
return d.value;
}
`

#
layout.linkType([linkType])

If linkType is specified, sets the link type accessor to the specified function and
returns this layout. If linkType is not specified, return the current accessor, which defaults to:
`js
function linkType(d) {
return d.type;
}
`

#### Adjusting layout

# layout.ordering([ordering])

If ordering is specified, sets the node ordering to the specified value and
returns this layout. If ordering is not specified, return the current value, which defaults to null.

When ordering is null, the node ordering will be calculated automatically.

When ordering is specified, it is used directly and no rank assignment or
ordering algorithm takes place. The ordering structure has three nested lists:
ordering is a list of layers, each of which is a list of bands, each of which is
a list of node ids. For example,
`js
[
[ ["layer 1 band 1"], ["layer 1 band 2"] ],
[ ["layer 2 band 1"], ["layer 2 band 2"] ],
...
]
`

# layout.rankSets([rankSets])

If rankSets is specified, sets the rank sets to the specified value and
returns this layout. If rankSets is not specified, return the current value,
which defaults to [].

Rank sets are optional constraints to keep nodes in the same layer. Each entry
has the form
`js
{
type: 'same|min', // optional, default 'min'
nodes: [node ids], // required
}
`

# layout.sortPorts([sortPorts])

If sortPorts is specified, sets the port sorting function to the specified
function and returns this layout. If sortPorts is not specified, return the
current value, which defaults to:
`js
function sortPorts(a, b) {
return a.id.localeCompare(b.id)
}
`

Note: in a future version this may be changed to sort ports to avoid
crossings by default.

#### Dimensions

# layout.extent([extent])

If extent is specified, sets this layout’s extent to the specified array of
points [[x0, y0], [x1, y1]], where [x0, y0] is the top-left corner
and [x1, y1] is the bottom-right corner, and returns this tile layout. If
extent is not specified, returns the current layout extent.

# layout.size([size])

If size is specified, sets this layout’s size to the specified two-element
array of numbers [width, height] and returns this layout. If size is not
specified, returns the current layout size. This is a convenience method
equivalent to setting the extent to [[0, 0], [width,
height]].

# diagram.scale([scale])

If scale is specified as a number, sets the layout's scale (from data units to
pixels). If scale is null, the scale will be reset and automatically
calculated the next time the diagram is called, to achieve the desired
whitespace fraction (below). If scale is not specified, return the current
scale.

# diagram.whitespace([whitespace])

If whitespace is specified as a number, sets the layout's whitespace fraction,
used when automatically calculating a scale (above). If whitespace is not
specified, return the current whitespace.

#### Manual positioning

# diagram.nodePosition([nodePosition])

If nodePosition is specified, use the specified function to directly set node
positions, bypassing the layout algorithm (link positions and shapes are still
calculated). If nodePosition is not specified, return the current
function, which defaults to null.

$3

# sankeyDiagram()

Creates a new Sankey diagram component.

# diagram(selection)

Apply the diagram to a selection, which should be an svg element.

`js
var diagram = d3.sankeyDiagram();
d3.select('#sankey')
.datum(sankey)
.call(diagram);
`

The Sankey data is taken from the selection's bound data, which should be a
graph object, as generated by d3.sankey.

#### Dimensions

# diagram.margin({ [top], [right], [bottom], [left] })

If called with an argument, set the margins of the diagram, otherwise return the
current value.

#### Titles

# diagram.nodeTitle([nodeTitle])

If called with an argument, set the node title to the specified function,
otherwise return the current function, which defaults to:
`js
function nodeTitle(d) {
return d.title !== undefined ? d.title : d.id;
}
`

# diagram.nodeValue([nodeValue])

If called with an argument, set the node value getter to the specified function,
otherwise return the current function, which defaults to:
`js
function nodeValue(d) {
return null;
}
`

The node value is shown with an SVG text element within the node body, only when
the nodeWidth is greater than zero.

#
diagram.linkTitle([linkTitle])

If called with an argument, set the link title to the specified function,
otherwise return the current function, which defaults to:
`js
const fmt = d3.format('.3s')
function linkTitle(d) {
const parts = []
const sourceTitle = nodeTitle(d.source)
const targetTitle = nodeTitle(d.target)
const matTitle = d.type

parts.push(${sourceTitle} → ${targetTitle})
if (matTitle) parts.push(matTitle)
parts.push(fmt(d.value))
return parts.join('\n')
}
`

The link title is displayed in an SVG title element, visible on hover.

To make it easier to customise this function to your data, you can use
d3.sankeyLinkTitle to generate new functions:

# sankeyLinkTitle(nodeTitle, typeTitle, fmt)

Generates a function similar to the one above, with custom accessors for the
node title nodeTitle, link-type title typeTitle and number format fmt.

# diagram.linkLabel([linkLabel])

If called with an argument, set the link label to the specified function,
otherwise return the current function, which defaults to:
`js
function linkLabel(d) {
return null
}
`

The link label is displayed in an SVG text element, so unlike the /title/, it
is visible all the time.

#### Link appearance

# diagram.linkColor([linkColor])

If linkColor is specified, sets the link color accessor to the specified
function, otherwise return the current accessor, which defaults to:
`js
function linkColor(d) {
return null;
}
`

# diagram.linkMinWidth([linkMinWidth])

If linkMinWidth is specified, sets the minimum link width accessor to the
specified function, otherwise return the current accessor, which by default
returns 1.

# diagram.linkImportance([linkImportance])

If linkImportance is specified, sets the link importance accessor to the
specified function, otherwise return the current accessor, which defaults to:
`js
function linkImportance(d) {
// Return negative values for special cases to put them at the bottom
if (!d.source || (d.target && d.target.direction === 'd')) return -2
if (!d.target || (d.source && d.source.direction === 'd')) return -1
// Return dy (visual width) for normal links
return d.dy
}
`

The link importance determines the z-order (stacking order) of links in the
diagram. Links are grouped by source-target pair, and groups are sorted by their
aggregated importance (see linkImportanceAgg below). This
ensures that multiple links between the same nodes are always rendered together,
avoiding a "woven" pattern where some links from one group go over and others go
under links from another group.

# diagram.linkImportanceAgg([linkImportanceAgg])

If linkImportanceAgg is specified, sets the link importance aggregation
function to the specified function, otherwise return the current function, which
defaults to:
`js
function linkImportanceAgg(values) {
// Sum of importance values for all links in the group
return values.reduce((a, b) => a + b, 0)
}
`

This function aggregates the individual link importance values (from
linkImportance) for all links between the same source and
target nodes. The aggregated value is used to determine the z-order of link
groups.

#### Node groups

# diagram.groups([groups])

If groups is specified, sets the list of node groups to the specified value.
If groups is not specified, return the current list. Node groups display a box
around the specified nodes, and should be given in the following format:
`js
[
{ title: "Group title to be displayed above nodes",
nodes: ["nodeid1", "nodeid", ...]
}
]
`

#### Events

# diagram.on(type[, listener])

Adds or removes an event listener for the specified type. The type string
is one of selectNode, selectLink or selectGroup. The listener is invoked
with the context as the element and one argument, the corresponding data.

If listener is not specified, returns the currently-assigned listener for the
specified type, if any.

Tests

Run the tests:
`js
npm test
`

Licence

MIT licence.

Contributors

- Rick Lupton
- @harisbal
- @svwielga4

Changelog

$3

$3

- Add linkImportance and linkImportanceAgg: links between the same source
and target node are now kept grouped together in the SVG so they have similar
Z-orders, avoiding the effect of links "weaving" through each other.

$3

- Fix package.json metadata from ESM module import.

$3

- Update many dependencies.

$3

- Modified code to assign type and value attributes to link objects
(thanks @harisbal)
- EXPERIMENTAL: allow short "stub" flows in or out of nodes using
fromElsewhere and toElsewhere attributes. These can be useful for
simplifying diagrams by avoiding uninteresting flows while still showing how
nodes balance.

$3

- Fix packaging to avoid overwriting the d3 global object in UMD module!
- Add a basic link label feature to show the values of links with SVG text
elements. See diagram.linkLabel. (#2)

$3

- Update packaging to produce different module builds:
- d3-sankey-diagram.esm.js: An ES module
- d3-sankey-diagram.cjs.js: A CommonJS module for use with NodeJS
- d3-sankey-diagram.umd.js: A UMD module for use in