d3-sankey-circular

A fork of the d3-sankey library (https://github.com/d3/d3-sankey) to allow circular links (ie cyclic graphs, like in this example).

The library contains a portion of code from Colin Fergus' bl.ock https://gist.github.com/cfergus/3956043 to detect circular links.

Install

If you use NPM, npm install d3-sankey-circular.

Else, use the d3-sankey-circular.js file from the compiled folder.

Usage

var sankey = d3.sankeyCircular();

API Reference

The API follows the original d3-sankey library, with additional options to allow the circular links to be laid out and drawn.

# d3.sankeyCircular() <>

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.y0 - the link’s vertical starting position (at source node)
link.y1 - the link’s vertical end position (at target node)
link.circularLinkType - the link's circularLinkType either top or bottom, depending on whether the center of the connected nodes is above or below the vertical midpoint of the figure.

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
node.index - the node’s zero-based index within the array of nodes
node.depth - the node’s zero-based graph depth, derived from the graph topology
node.column - the node’s zero-based depth, as drawn, going from left to right. Column is derived from node.depth and the sankey.nodeAlign setting.
node.height - the node’s zero-based graph height, derived from the graph topology
node.x0 - the node’s minimum horizontal position, derived from node.column
node.x1 - the node’s maximum horizontal position (node.x0 + sankey.nodeWidth)
node.y0 - the node’s minimum vertical position
node.y1 - the node’s maximum vertical position (node.y1 - node.y0 is proportional to node.value)
node.partOfCycle - set to true if the node has incoming or outgoing links that are circular
node.circularLinkType - set to either top or bottom, if node.partOfCycle is true, which relates to whether circular links are drawn above or below the main part of the graph

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 numeric or string identifiers rather than object references; ; see sankey.nodeId. The following properties are assigned to each link by the Sankey generator:

link.y0 - the link’s vertical starting position (at source node)
link.y1 - the link’s vertical end position (at target node)
link.width - the link’s width (proportional to link.value)
link.index - the zero-based index of link within the array of links
link.circular - set to true if the link is circular

For any links that circular (link.circular = true), the following properties are assigned

link.circularLinkID - the zero-based index of link within the array of circular links
link.circularLinkType - set to either top or bottom, which relates to whether the link is drawn above or below the main part of the graph
link.circularLinkPathData - an object containing the properties used to draw the SVG path, including link.circularLinkPathData.path, which is the string used for the d property.

# sankey.nodeId([id]) <>

If id is specified, sets the node id accessor to the specified function and returns this Sankey generator. If id is not specified, returns the current node id accessor, which defaults to the numeric node.index:

function id(d) {
  return d.index;
}

The default id accessor allows each link’s source and target to be specified as a zero-based index into the nodes array. For example:

var nodes = [
  {"id": "Alice"},
  {"id": "Bob"},
  {"id": "Carol"}
];

var links = [
  {"source": 0, "target": 1}, // Alice → Bob
  {"source": 1, "target": 2} // Bob → Carol
];

Now consider a different id accessor that returns a string:

function id(d) {
  return d.id;
}

With this accessor, you can use named sources and targets:

var nodes = [
  {"id": "Alice"},
  {"id": "Bob"},
  {"id": "Carol"}
];

var links = [
  {"source": "Alice", "target": "Bob"},
  {"source": "Bob", "target": "Carol"}
];

# sankey.nodeAlign([align]) <>

If align is specified, sets the node alignment method the specified function and returns this Sankey generator. If align is not specified, returns the current node alignment method, which defaults to d3.sankeyJustify. The specified function is evaluated for each input node in order, being passed the current node and the total depth n of the graph (one plus the maximum node.depth), and must return an integer between 0 and n - 1 that indicates the desired horizontal position of the node in the generated Sankey diagram.

# 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.nodePaddingRatio([proportion]) <>

If proportion is specified (from 0 to 1), sets the vertical separation between nodes at each column to the specified number and returns this Sankey generator. The proportion is applied to the most dense column of nodes, and calculates a minimum padding that will be used across the chart.

If a nodePaddingRatio is not specified, then defaults to the padding setting in pixels.

# 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 [[0, 0], [1, 1]].

# 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.

# sankey.circularLinkGap([circularLinkGap]) <>

If circularLinkGap is specified, sets the gap (in pixels) between circular links that travel next to each other. If circularLinkGap, it defaults to 2.

# sankey.nodeSort([nodeSort]) <>
If nodeSort is specified, sets the node sort method and returns this Sankey generator. If sort is not specified, returns the current node sort method, which defaults to undefined, indicating that vertical order of nodes within each column will be determined automatically by the layout. If sort is null, the order is fixed by the input. Otherwise, the specified sort function determines the order; the function is passed two nodes, and must return a value less than 0 if the first node should be above the second, and a value greater than 0 if the second node should be above the first, or 0 if the order is not specified.
Sorting is only applied to nodes that both part or not part of a circular loop. When the result of a nodeSort is 0 then nodes are sorted by the top (y0) of the node

Alignments

See sankey.nodeAlign.

# d3.sankeyLeft(node, n)

Returns node.depth.

# d3.sankeyRight(node, n)

Returns n - 1 - node.height.

# d3.sankeyCenter(node, n)

Like d3.sankeyLeft, except that nodes without any incoming links are moved as right as possible.

# d3.sankeyJustify(node, n)

Like d3.sankeyLeft, except that nodes without any outgoing links are moved to the far right.

Links

# link.path<>

Each link has a .path property which stores the svg path d string, which can be accessed to draw the path, for example

svg.append("g")
    .attr("class", "links")
    .attr("fill", "none")
    .attr("stroke-opacity", 0.2)
    .selectAll("path");
    .data(sankey.links)
    .enter()
    .append("path")
        .attr("d", function(d){
          return d.path;
        })
        .style("stroke-width", function (link) { link.width; })
        .style("stroke", function (link, i) {
            return link.circular ? "red" : "black"
        })

For normal paths, the path string is created by the d3-shape linkHorizontal function. For circular paths, the path string is calculated to reduced overlaps with other nodes and paths.