Waterfall charts

lib/index.js

@@ -22,6 +22,7 @@ Plotly.register([
     require('./contour'),
     require('./scatterternary'),
     require('./violin'),
+    require('./waterfall'),
 
     require('./scatter3d'),
     require('./surface'),

lib/waterfall.js

@@ -0,0 +1,11 @@
+/**
+* Copyright 2012-2019, 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/waterfall');

src/components/drawing/index.js

@@ -110,7 +110,10 @@ drawing.hideOutsideRangePoints = function(traceGroups, subplot) {
         var trace = d[0].trace;
         var xcalendar = trace.xcalendar;
         var ycalendar = trace.ycalendar;
-        var selector = trace.type === 'bar' ? '.bartext' : '.point,.textpoint';
+        var selector = (
+            trace.type === 'bar' ||
+            trace.type === 'waterfall') ?
+            '.bartext' : '.point,.textpoint';
 
         traceGroups.selectAll(selector).each(function(d) {
             drawing.hideOutsideRangePoint(d, d3.select(this), xa, ya, xcalendar, ycalendar);

src/components/legend/defaults.js

@@ -50,7 +50,9 @@ module.exports = function legendDefaults(layoutIn, layoutOut, fullData) {
             }
         }
 
-        if((Registry.traceIs(trace, 'bar') && layoutOut.barmode === 'stack') ||
+        if(((Registry.traceIs(trace, 'bar') ||
+            Registry.traceIs(trace, 'waterfall')) &&
+            layoutOut.barmode === 'stack') ||
                 ['tonextx', 'tonexty'].indexOf(trace.fill) !== -1) {
             defaultOrder = helpers.isGrouped({traceorder: defaultOrder}) ?
                 'grouped+reversed' : 'reversed';

src/components/legend/style.js

@@ -248,7 +248,10 @@ module.exports = function style(s, gd) {
 
         var barpath = d3.select(this).select('g.legendpoints')
             .selectAll('path.legendbar')
-            .data(Registry.traceIs(trace, 'bar') ? [d] : []);
+            .data((
+                Registry.traceIs(trace, 'bar') ||
+                Registry.traceIs(trace, 'waterfall')
+            ) ? [d] : []);
         barpath.enter().append('path').classed('legendbar', true)
             .attr('d', 'M6,6H-6V-6H6Z')
             .attr('transform', 'translate(20,0)');

src/plot_api/helpers.js

@@ -290,7 +290,9 @@ exports.cleanData = function(data) {
         // error_y.opacity is obsolete - merge into color
         if(trace.error_y && 'opacity' in trace.error_y) {
             var dc = Color.defaults;
-            var yeColor = trace.error_y.color || (Registry.traceIs(trace, 'bar') ?
+            var yeColor = trace.error_y.color ||
+                ((Registry.traceIs(trace, 'bar') ||
+                Registry.traceIs(trace, 'waterfall')) ?
                 Color.defaultLine :
                 dc[tracei % dc.length]);
             trace.error_y.color = Color.addOpacity(
@@ -302,8 +304,10 @@ exports.cleanData = function(data) {
         // convert bardir to orientation, and put the data into
         // the axes it's eventually going to be used with
         if('bardir' in trace) {
-            if(trace.bardir === 'h' && (Registry.traceIs(trace, 'bar') ||
-                     trace.type.substr(0, 9) === 'histogram')) {
+            if(trace.bardir === 'h' &&
+                ((Registry.traceIs(trace, 'bar') ||
+                Registry.traceIs(trace, 'waterfall')) ||
+                trace.type.substr(0, 9) === 'histogram')) {
                 trace.orientation = 'h';
                 exports.swapXYData(trace);
             }
@@ -336,7 +340,9 @@ exports.cleanData = function(data) {
             trace.scene = Plots.subplotsRegistry.gl3d.cleanId(trace.scene);
         }
 
-        if(!Registry.traceIs(trace, 'pie') && !Registry.traceIs(trace, 'bar')) {
+        if(!Registry.traceIs(trace, 'pie') &&
+            !Registry.traceIs(trace, 'bar') &&
+            !Registry.traceIs(trace, 'waterfall')) {
             if(Array.isArray(trace.textposition)) {
                 for(i = 0; i < trace.textposition.length; i++) {
                     trace.textposition[i] = cleanTextPosition(trace.textposition[i]);

src/plot_api/plot_api.js

@@ -1670,7 +1670,11 @@ function _restyle(gd, aobj, traces) {
             else if(ai === 'type' && (newVal === 'pie') !== (oldVal === 'pie')) {
                 var labelsTo = 'x';
                 var valuesTo = 'y';
-                if((newVal === 'bar' || oldVal === 'bar') && cont.orientation === 'h') {
+                if(cont.orientation === 'h' && (
+                    newVal === 'bar' ||
+                    oldVal === 'bar' ||
+                    newVal === 'waterfall' ||
+                    oldVal === 'waterfall')) {
                     labelsTo = 'y';
                     valuesTo = 'x';
                 }

src/plots/cartesian/axes.js

@@ -2822,7 +2822,9 @@ function hasBarsOrFill(gd, ax) {
         if(trace.visible === true &&
             (trace.xaxis + trace.yaxis) === subplot &&
             (
-                Registry.traceIs(trace, 'bar') && trace.orientation === {x: 'h', y: 'v'}[axLetter] ||
+                (Registry.traceIs(trace, 'bar') ||
+                Registry.traceIs(trace, 'waterfall')) &&
+                trace.orientation === {x: 'h', y: 'v'}[axLetter] ||
                 trace.fill && trace.fill.charAt(trace.fill.length - 1) === axLetter
             )
         ) {

src/traces/bar/calc.js

@@ -17,7 +17,9 @@ var calcSelection = require('../scatter/calc_selection');
 module.exports = function calc(gd, trace) {
     var xa = Axes.getFromId(gd, trace.xaxis || 'x');
     var ya = Axes.getFromId(gd, trace.yaxis || 'y');
-    var size, pos;
+    var size, pos, i;
+
+    var isWaterfall = (trace.type === 'waterfall');
 
     if(trace.orientation === 'h') {
         size = xa.makeCalcdata(trace, 'x');
@@ -31,9 +33,25 @@ module.exports = function calc(gd, trace) {
     var serieslen = Math.min(pos.length, size.length);
     var cd = new Array(serieslen);
 
-    // set position and size
-    for(var i = 0; i < serieslen; i++) {
-        cd[i] = { p: pos[i], s: size[i] };
+    // set position and size (as well as for waterfall total size)
+    var previousSum = 0;
+    for(i = 0; i < serieslen; i++) {
+        cd[i] = {
+            p: pos[i],
+            s: size[i]
+        };
+
+        if(isWaterfall) {
+            if(cd[i].s === undefined) {
+                cd[i].isFall = true;
+                cd[i].s = previousSum;
+            } else {
+                cd[i].isFall = false;
+                var newSize = cd[i].s;
+                cd[i].s += previousSum;
+                previousSum += newSize;
+            }
+        }
 
         if(trace.ids) {
             cd[i].id = String(trace.ids[i]);

src/traces/bar/cross_trace_calc.js

@@ -36,7 +36,8 @@ function crossTraceCalc(gd, plotinfo) {
         var fullTrace = fullTraces[i];
         if(
             fullTrace.visible === true &&
-            Registry.traceIs(fullTrace, 'bar') &&
+            (Registry.traceIs(fullTrace, 'bar') ||
+            Registry.traceIs(fullTrace, 'waterfall')) &&
             fullTrace.xaxis === xa._id &&
             fullTrace.yaxis === ya._id
         ) {
@@ -646,6 +647,8 @@ function collectExtents(calcTraces, pa) {
         cd = calcTraces[i];
         cd[0].t.extents = extents;
 
+        var isWaterfall = (cd[0].trace.type === 'waterfall');
+
         var poffset = cd[0].t.poffset;
         var poffsetIsArray = Array.isArray(poffset);
 
@@ -667,6 +670,12 @@ function collectExtents(calcTraces, pa) {
             di.p1 = di.p0 + di.w;
             di.s0 = di.b;
             di.s1 = di.s0 + di.s;
+
+            if(isWaterfall) {
+                if(di.isFall === false) {
+                    di.s0 += (j === 0) ? 0 : cd[j - 1].s;
+                }
+            }
         }
     }
 }

src/traces/bar/defaults.js

@@ -14,7 +14,7 @@ var Color = require('../../components/color');
 var Registry = require('../../registry');
 
 var handleXYDefaults = require('../scatter/xy_defaults');
-var handleStyleDefaults = require('../bar/style_defaults');
+var handleStyleDefaults = require('./style_defaults');
 var attributes = require('./attributes');
 
 module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout) {

src/traces/bar/hover.js

@@ -120,6 +120,9 @@ function hoverPoints(pointData, xval, yval, hovermode) {
 
     var size = (trace.base) ? di.b + di.s : di.s;
     pointData[sizeLetter + '0'] = pointData[sizeLetter + '1'] = sa.c2p(di[sizeLetter], true);
+    if(trace.type === 'waterfall' && di.isFall === false) {
+        size -= (index === 0) ? 0 : cd[index - 1].s;
+    }
     pointData[sizeLetter + 'LabelVal'] = size;
 
     var extent = t.extents[t.extents.round(di.p)];

src/traces/bar/layout_defaults.js

@@ -28,7 +28,9 @@ module.exports = function(layoutIn, layoutOut, fullData) {
 
     for(var i = 0; i < fullData.length; i++) {
         var trace = fullData[i];
-        if(Registry.traceIs(trace, 'bar') && trace.visible) hasBars = true;
+        if((Registry.traceIs(trace, 'bar') ||
+            Registry.traceIs(trace, 'waterfall')) &&
+            trace.visible) hasBars = true;
         else continue;
 
         // if we have at least 2 grouped bar traces on the same subplot,

src/traces/bar/plot.js

@@ -38,6 +38,10 @@ module.exports = function plot(gd, plotinfo, cdbar, barLayer) {
         var cd0 = cd[0];
         var trace = cd0.trace;
 
+        var isWaterfall = (trace.type === 'waterfall');
+        var isTriangle = (isWaterfall) ? (trace.marker.shape === 'triangle') : false;
+        var isVertical = (trace.orientation === 'v');
+
         if(!plotinfo.isRangePlot) cd0.node3 = plotGroup;
 
         var pointGroup = Lib.ensureSingle(plotGroup, 'g', 'points');
@@ -111,6 +115,7 @@ module.exports = function plot(gd, plotinfo, cdbar, barLayer) {
                 // pixelation. if the bars ARE fully opaque and have
                 // no line, expand to a full pixel to make sure we
                 // can see them
+
                 var op = Color.opacity(di.mc || trace.marker.color);
                 var fixpx = (op < 1 || lw > 0.01) ? roundWithLine : expandToVisible;
                 x0 = fixpx(x0, x1);
@@ -119,11 +124,21 @@ module.exports = function plot(gd, plotinfo, cdbar, barLayer) {
                 y1 = fixpx(y1, y0);
             }
 
+            var shape;
+            if(isWaterfall && isTriangle && i > 0 && cd[i].isFall === false) {
+                if(isVertical) {
+                    shape = 'M' + x0 + ',' + y0 + 'L' + (0.5 * (x1 + x0)) + ',' + y1 + 'L' + x1 + ',' + y0 + 'Z';
+                } else {
+                    shape = 'M' + x0 + ',' + y0 + 'L' + x1 + ',' + (0.5 * (y1 + y0)) + 'L' + x0 + ',' + y1 + 'Z';
+                }
+            } else {
+                shape = 'M' + x0 + ',' + y0 + 'V' + y1 + 'H' + x1 + 'V' + y0 + 'Z';
+            }
+
             Lib.ensureSingle(bar, 'path')
-                .style('vector-effect', 'non-scaling-stroke')
-                .attr('d',
-                    'M' + x0 + ',' + y0 + 'V' + y1 + 'H' + x1 + 'V' + y0 + 'Z')
-                .call(Drawing.setClipUrl, plotinfo.layerClipId, gd);
+            .style('vector-effect', 'non-scaling-stroke')
+            .attr('d', shape)
+            .call(Drawing.setClipUrl, plotinfo.layerClipId, gd);
 
             appendBarText(gd, bar, cd, i, x0, x1, y0, y1);
 

src/traces/waterfall/attributes.js

@@ -0,0 +1,68 @@
+/**
+* Copyright 2012-2019, 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 extendFlat = require('../../lib/extend').extendFlat;
+
+var barAttrs = require('../bar/attributes');
+
+module.exports = {
+
+    x: barAttrs.x,
+    x0: barAttrs.x0,
+    dx: barAttrs.dx,
+    y: barAttrs.y,
+    y0: barAttrs.y0,
+    dy: barAttrs.dy,
+
+    r: barAttrs.r,
+    t: barAttrs.t,
+
+    text: barAttrs.text,
+    hovertext: barAttrs.hovertext,
+    hovertemplate: barAttrs.hovertemplate,
+
+    textposition: barAttrs.textposition,
+
+    textfont: barAttrs.textfont,
+
+    insidetextfont: barAttrs.insidetextfont,
+
+    outsidetextfont: barAttrs.outsidetextfont,
+
+    constraintext: barAttrs.constraintext,
+
+    cliponaxis: barAttrs.cliponaxis,
+
+    orientation: barAttrs.orientation,
+
+    base: barAttrs.base,
+
+    offset: barAttrs.offset,
+
+    width: barAttrs.width,
+
+    marker: extendFlat({}, barAttrs.marker, {
+        shape: {
+            valType: 'enumerated',
+            values: ['rectangle', 'triangle'],
+            dflt: 'rectangle',
+            role: 'style',
+            editType: 'style',
+            description: [
+                'Defines the shape of positive/negative bars on the plot.',
+                'Namely \'triangle`\ option could be used to emphasize on',
+                'the direction of the changes.'
+            ].join(' ')
+        }
+    }),
+
+    selected: barAttrs.selected,
+    unselected: barAttrs.unselected
+};