Sankey feature branch

lib/index.js

@@ -21,6 +21,7 @@ Plotly.register([
     require('./pie'),
     require('./contour'),
     require('./scatterternary'),
+    require('./sankey'),
 
     require('./scatter3d'),
     require('./surface'),

lib/sankey.js

@@ -0,0 +1,11 @@
+/**
+* Copyright 2012-2017, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+'use strict';
+
+module.exports = require('../src/traces/sankey');

package.json

@@ -54,12 +54,14 @@
   },
   "dependencies": {
     "3d-view": "^2.0.0",
+    "@plotly/d3-sankey": "^0.5.0",
     "alpha-shape": "^1.0.0",
     "arraytools": "^1.0.0",
     "color-rgba": "^1.0.4",
     "convex-hull": "^1.0.3",
     "country-regex": "^1.1.0",
     "d3": "^3.5.12",
+    "d3-force": "^1.0.6",
     "delaunay-triangulate": "^1.1.6",
     "es6-promise": "^3.0.2",
     "fast-isnumeric": "^1.1.1",
@@ -93,6 +95,7 @@
     "right-now": "^1.0.0",
     "robust-orientation": "^1.1.3",
     "sane-topojson": "^2.0.0",
+    "strongly-connected-components": "^1.0.1",
     "superscript-text": "^1.0.0",
     "tinycolor2": "^1.3.0",
     "topojson-client": "^2.1.0",

src/plots/cartesian/graph_interact.js

@@ -300,7 +300,7 @@ fx.hover = function(gd, evt, subplot) {
 // The actual implementation is here:
 
 function hover(gd, evt, subplot) {
-    if(subplot === 'pie') {
+    if(['pie', 'sankey'].indexOf(subplot) !== -1) {
         gd.emit('plotly_hover', {
             event: evt.originalEvent,
             points: [evt]

src/traces/sankey/attributes.js

@@ -0,0 +1,207 @@
+/**
+* Copyright 2012-2017, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+'use strict';
+
+var shapeAttrs = require('../../components/shapes/attributes');
+var fontAttrs = require('../../plots/font_attributes');
+var plotAttrs = require('../../plots/attributes');
+var colorAttrs = require('../../components/color/attributes');
+
+var extendFlat = require('../../lib/extend').extendFlat;
+
+module.exports = {
+    hoverinfo: extendFlat({}, plotAttrs.hoverinfo, {
+        flags: ['label', 'text', 'value', 'percent', 'name']
+    }),
+    domain: {
+        x: {
+            valType: 'info_array',
+            role: 'info',
+            items: [
+                {valType: 'number', min: 0, max: 1},
+                {valType: 'number', min: 0, max: 1}
+            ],
+            dflt: [0, 1],
+            description: [
+                'Sets the horizontal domain of this `sankey` trace',
+                '(in plot fraction).'
+            ].join(' ')
+        },
+        y: {
+            valType: 'info_array',
+            role: 'info',
+            items: [
+                {valType: 'number', min: 0, max: 1},
+                {valType: 'number', min: 0, max: 1}
+            ],
+            dflt: [0, 1],
+            description: [
+                'Sets the vertical domain of this `sankey` trace',
+                '(in plot fraction).'
+            ].join(' ')
+        }
+    },
+
+    orientation: {
+        valType: 'enumerated',
+        values: ['v', 'h'],
+        dflt: 'h',
+        role: 'style',
+        description: 'Sets the orientation of the Sankey diagram.'
+    },
+
+    valueformat: {
+        valType: 'string',
+        dflt: '.3s',
+        role: 'style',
+        description: [
+            'Sets the value formatting rule using d3 formatting mini-language',
+            'which is similar to those of Python. See',
+            'https://github.com/d3/d3-format/blob/master/README.md#locale_format'
+        ].join(' ')
+    },
+
+    valuesuffix: {
+        valType: 'string',
+        dflt: '',
+        role: 'style',
+        description: [
+            'Adds a unit to follow the value in the hover tooltip. Add a space if a separation',
+            'is necessary from the value.'
+        ].join(' ')
+    },
+
+    arrangement: {
+        valType: 'enumerated',
+        values: ['snap', 'perpendicular', 'freeform', 'fixed'],
+        dflt: 'snap',
+        role: 'style',
+        description: [
+            'If value is `snap` (the default), the node arrangement is assisted by automatic snapping of elements to',
+            'preserve space between nodes specified via `nodepad`.',
+            'If value is `perpendicular`, the nodes can only move along a line perpendicular to the flow.',
+            'If value is `freeform`, the nodes can freely move on the plane.',
+            'If value is `fixed`, the nodes are stationary.'
+        ].join(' ')
+    },
+
+    textfont: fontAttrs,
+
+    node: {
+        label: {
+            valType: 'data_array',
+            dflt: [],
+            role: 'info',
+            description: 'The shown name of the node.'
+        },
+        color: extendFlat({}, shapeAttrs.fillcolor, {
+            arrayOk: true,
+            description: [
+                'Sets the `node` color. It can be a single value, or an array for specifying color for each `node`.',
+                'If `node.color` is omitted, then the default `Plotly` color palette will be cycled through',
+                'to have a variety of colors. These defaults are not fully opaque, to allow some visibility of',
+                'what is beneath the node.'
+            ].join(' ')
+        }),
+        line: {
+            color: {
+                valType: 'color',
+                role: 'style',
+                dflt: colorAttrs.defaultLine,
+                arrayOk: true,
+                description: [
+                    'Sets the color of the `line` around each `node`.'
+                ].join(' ')
+            },
+            width: {
+                valType: 'number',
+                role: 'style',
+                min: 0,
+                dflt: 0.5,
+                arrayOk: true,
+                description: [
+                    'Sets the width (in px) of the `line` around each `node`.'
+                ].join(' ')
+            }
+        },
+        pad: {
+            valType: 'number',
+            arrayOk: false,
+            min: 0,
+            dflt: 20,
+            role: 'style',
+            description: 'Sets the padding (in px) between the `nodes`.'
+        },
+        thickness: {
+            valType: 'number',
+            arrayOk: false,
+            min: 1,
+            dflt: 20,
+            role: 'style',
+            description: 'Sets the thickness (in px) of the `nodes`.'
+        },
+        description: 'The nodes of the Sankey plot.'
+    },
+
+    link: {
+        label: {
+            valType: 'data_array',
+            dflt: [],
+            role: 'info',
+            description: 'The shown name of the link.'
+        },
+        color: extendFlat({}, shapeAttrs.fillcolor, {
+            arrayOk: true,
+            description: [
+                'Sets the `link` color. It can be a single value, or an array for specifying color for each `link`.',
+                'If `link.color` is omitted, then by default, a translucent grey link will be used.'
+            ].join(' ')
+        }),
+        line: {
+            color: {
+                valType: 'color',
+                role: 'style',
+                dflt: colorAttrs.defaultLine,
+                arrayOk: true,
+                description: [
+                    'Sets the color of the `line` around each `link`.'
+                ].join(' ')
+            },
+            width: {
+                valType: 'number',
+                role: 'style',
+                min: 0,
+                dflt: 0,
+                arrayOk: true,
+                description: [
+                    'Sets the width (in px) of the `line` around each `link`.'
+                ].join(' ')
+            }
+        },
+        source: {
+            valType: 'data_array',
+            role: 'info',
+            dflt: [],
+            description: 'An integer number `[0..nodes.length - 1]` that represents the source node.'
+        },
+        target: {
+            valType: 'data_array',
+            role: 'info',
+            dflt: [],
+            description: 'An integer number `[0..nodes.length - 1]` that represents the target node.'
+        },
+        value: {
+            valType: 'data_array',
+            dflt: [],
+            role: 'info',
+            description: 'A numeric value representing the flow volume value.'
+        },
+        description: 'The links of the Sankey plot.'
+    }
+};

src/traces/sankey/base_plot.js

@@ -0,0 +1,30 @@
+/**
+* Copyright 2012-2017, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+'use strict';
+
+var Plots = require('../../plots/plots');
+var plot = require('./plot');
+
+exports.name = 'sankey';
+
+exports.attr = 'type';
+
+exports.plot = function(gd) {
+    var calcData = Plots.getSubplotCalcData(gd.calcdata, 'sankey', 'sankey');
+    if(calcData.length) plot(gd, calcData);
+};
+
+exports.clean = function(newFullData, newFullLayout, oldFullData, oldFullLayout) {
+    var hadPlot = (oldFullLayout._has && oldFullLayout._has('sankey'));
+    var hasPlot = (newFullLayout._has && newFullLayout._has('sankey'));
+
+    if(hadPlot && !hasPlot) {
+        oldFullLayout._paperdiv.selectAll('.sankey').remove();
+    }
+};

src/traces/sankey/calc.js

@@ -0,0 +1,51 @@
+/**
+* Copyright 2012-2017, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+'use strict';
+
+var tarjan = require('strongly-connected-components');
+var Lib = require('../../lib');
+
+function circularityPresent(nodeList, sources, targets) {
+
+    var nodes = nodeList.map(function() {return [];});
+
+    for(var i = 0; i < Math.min(sources.length, targets.length); i++) {
+        if(sources[i] === targets[i]) {
+            return true; // self-link which is also a scc of one
+        }
+        nodes[sources[i]].push(targets[i]);
+    }
+
+    var scc = tarjan(nodes);
+
+    // Tarján's strongly connected components algorithm coded by Mikola Lysenko
+    // returns at least one non-singular component if there's circularity in the graph
+    return scc.components.some(function(c) {
+        return c.length > 1;
+    });
+}
+
+module.exports = function calc(gd, trace) {
+
+    if(circularityPresent(trace.node.label, trace.link.source, trace.link.target)) {
+        Lib.error('Circularity is present in the Sankey data. Removing all nodes and links.');
+        trace.link.label = [];
+        trace.link.source = [];
+        trace.link.target = [];
+        trace.link.value = [];
+        trace.link.color = [];
+        trace.node.label = [];
+        trace.node.color = [];
+    }
+
+    return [{
+        link: trace.link,
+        node: trace.node
+    }];
+};

src/traces/sankey/constants.js

@@ -0,0 +1,20 @@
+/**
+* Copyright 2012-2017, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+'use strict';
+
+module.exports = {
+    nodeTextOffsetHorizontal: 4,
+    nodeTextOffsetVertical: 3,
+    nodePadAcross: 10,
+    sankeyIterations: 50,
+    forceIterations: 5,
+    forceTicksPerFrame: 10,
+    duration: 500,
+    ease: 'linear'
+};