d3-sankey

What is d3-sankey?

The d3-sankey npm package is a plugin for D3.js that provides tools for creating Sankey diagrams. Sankey diagrams are a type of flow diagram in which the width of the arrows is proportional to the flow rate. They are typically used to visualize energy or material transfers between processes.

What are d3-sankey's main functionalities?

Creating a Sankey Diagram

This code demonstrates how to create a basic Sankey diagram using the d3-sankey package. It defines nodes and links, sets up the Sankey generator, and generates the Sankey layout.

const { sankey, sankeyLinkHorizontal } = require('d3-sankey');
const data = {
  nodes: [
    { name: 'A' },
    { name: 'B' },
    { name: 'C' }
  ],
  links: [
    { source: 0, target: 1, value: 10 },
    { source: 1, target: 2, value: 5 }
  ]
};
const sankeyGenerator = sankey().nodeWidth(15).nodePadding(10).extent([[1, 1], [500, 500]]);
const sankeyData = sankeyGenerator(data);
console.log(sankeyData);

Customizing Node Width and Padding

This code shows how to customize the node width and padding in a Sankey diagram. By adjusting these parameters, you can control the appearance and spacing of the nodes in the diagram.

const { sankey } = require('d3-sankey');
const data = {
  nodes: [
    { name: 'A' },
    { name: 'B' },
    { name: 'C' }
  ],
  links: [
    { source: 0, target: 1, value: 10 },
    { source: 1, target: 2, value: 5 }
  ]
};
const sankeyGenerator = sankey().nodeWidth(20).nodePadding(15).extent([[1, 1], [500, 500]]);
const sankeyData = sankeyGenerator(data);
console.log(sankeyData);

Generating Sankey Links

This code demonstrates how to generate the path for a Sankey link using the sankeyLinkHorizontal function. This function creates a path string that can be used to render the link in an SVG element.

const { sankey, sankeyLinkHorizontal } = require('d3-sankey');
const data = {
  nodes: [
    { name: 'A' },
    { name: 'B' },
    { name: 'C' }
  ],
  links: [
    { source: 0, target: 1, value: 10 },
    { source: 1, target: 2, value: 5 }
  ]
};
const sankeyGenerator = sankey().nodeWidth(15).nodePadding(10).extent([[1, 1], [500, 500]]);
const sankeyData = sankeyGenerator(data);
const linkPath = sankeyLinkHorizontal();
const link = sankeyData.links[0];
console.log(linkPath(link));

Other packages similar to d3-sankey

react-sankey

The react-sankey package is designed for use with React applications. It provides a React component for rendering Sankey diagrams, making it easier to integrate with React projects compared to d3-sankey, which requires more manual setup.

README

d3-sankey

Sankey diagrams visualize the directed flow between nodes in an acyclic network. For example, this diagram shows a possible scenario of UK energy production and consumption in 2050:

Source: Department of Energy & Climate Change, Tom Counsell.

Installing

If you use NPM, npm install d3-sankey. Otherwise, download the latest release.

You can also load directly from unpkg.

<script src="https://unpkg.com/d3-array@1"></script>
<script src="https://unpkg.com/d3-collection@1"></script>
<script src="https://unpkg.com/d3-path@1"></script>
<script src="https://unpkg.com/d3-shape@1"></script>
<script src="https://unpkg.com/d3-sankey@0"></script>
<script>

var sankey = d3.sankey();

</script>

API Reference

# d3.sankey() <>

Constructs a new Sankey generator with the default settings.

# sankey(arguments…) <>

Computes the node and link positions for the given arguments, returning a graph representing the Sankey layout. The returned graph has the following properties:

• graph.nodes - the array of nodes
• graph.links - the array of links

# sankey.update(graph) <>

Recomputes the specified graph’s links’ positions, updating the following properties of each link:

• link.sy - the link’s vertical starting position (at source node)
• link.ty - the link’s vertical end position (at target node)

This method is intended to be called after computing the initial Sankey layout, for example when the diagram is repositioned interactively.

# sankey.nodes([nodes]) <>

If nodes is specified, sets the Sankey generator’s nodes accessor to the specified function or array and returns this Sankey generator. If nodes is not specified, returns the current nodes accessor, which defaults to:

function nodes(graph) {
  return graph.nodes;
}

If nodes is specified as a function, the function is invoked when the Sankey layout is generated, being passed any arguments passed to the Sankey generator. This function must return an array of nodes. If nodes is not a function, it must be a constant array of nodes.

Each node must be an object. The following properties are assigned by the Sankey generator:

• node.sourceLinks - the array of outgoing links which have this node as their source
• node.targetLinks - the array of incoming links which have this node as their target
• node.value - the node’s value; the sum of link.value for the node’s incoming links
• nodex - the node’s horizontal position (derived from the graph topology)
• node.dx - the node’s node width
• node.y - the node’s vertical position
• node.dy - the node’s height (proportional to its value)

See also sankey.links.

# sankey.links([links]) <>

If links is specified, sets the Sankey generator’s links accessor to the specified function or array and returns this Sankey generator. If links is not specified, returns the current links accessor, which defaults to:

function links(graph) {
  return graph.links;
}

If links is specified as a function, the function is invoked when the Sankey layout is generated, being passed any arguments passed to the Sankey generator. This function must return an array of links. If links is not a function, it must be a constant array of links.

Each link must be an object with the following properties:

• link.source - the link’s source node
• link.target - the link’s target node
• link.value - the link’s numeric value

For convenience, a link’s source and target may be initialized using the zero-based index of corresponding node in the array of nodes passed to the Sankey generator rather than object references. The following properties are assigned to each link by the Sankey generator:

• link.dy - the link’s breadth (proportional to its value)
• link.sy - the link’s vertical starting position (at source node)
• link.ty - the link’s vertical end position (at target node)

# sankey.nodeWidth([width]) <>

If width is specified, sets the node width to the specified number and returns this Sankey generator. If width is not specified, returns the current node width, which defaults to 24.

# sankey.nodePadding([padding]) <>

If padding is specified, sets the vertical separation between nodes at each column to the specified number and returns this Sankey generator. If padding is not specified, returns the current node padding, which defaults to 8.

# sankey.extent([extent]) <>

If extent is specified, sets the extent of the Sankey layout to the specified bounds and returns the layout. The extent bounds are specified as an array [[x0, y0], [x1, y1]], where x0 is the left side of the extent, y0 is the top, x1 is the right and y1 is the bottom. If extent is not specified, returns the current extent which defaults to null.

# sankey.size([size]) <>

An alias for sankey.extent where the minimum x and y of the extent are ⟨0,0⟩. Equivalent to:

sankey.extent([[0, 0], size]);

# sankey.iterations([iterations]) <>

If iterations is specified, sets the number of relaxation iterations when generating the layout and returns this Sankey generator. If iterations is not specified, returns the current number of relaxation iterations, which defaults to 32.

Links

# d3.sankeyLinkHorizontal() <>

Returns a horizontal link shape suitable for a Sankey diagram. The source accessor is defined as:

function source(d) {
  return [d.source.x + d.source.dx, d.source.y + d.sy + d.dy / 2];
}

The target accessor is defined as:

function target(d) {
  return [d.target.x, d.target.y + d.ty + d.dy / 2];
}

For example, to render the links of a Sankey diagram in SVG, you might say:

svg.append("g")
    .attr("fill", "none")
    .attr("stroke", "#000")
    .attr("stroke-opacity", 0.2)
  .selectAll("path")
  .data(graph.links)
  .enter().append("path")
    .attr("d", d3.sankeyLinkHorizontal())
    .attr("stroke-width", function(d) { return d.dy; });