Add 'cumulative' histogram 'mode' for CDF

src/plot_api/plot_api.js

@@ -1296,7 +1296,7 @@ function _restyle(gd, aobj, _traces) {
         'tilt', 'tiltaxis', 'depth', 'direction', 'rotation', 'pull',
         'line.showscale', 'line.cauto', 'line.autocolorscale', 'line.reversescale',
         'marker.line.showscale', 'marker.line.cauto', 'marker.line.autocolorscale', 'marker.line.reversescale',
-        'xcalendar', 'ycalendar'
+        'xcalendar', 'ycalendar', 'cumulative', 'currentbin'
     ];
 
     for(i = 0; i < traces.length; i++) {

src/traces/histogram/attributes.js

@@ -71,14 +71,44 @@ module.exports = {
         ].join(' ')
     },
 
-    mode: {
+    cumulative: {
+        valType: 'boolean',
+        dflt: false,
+        role: 'info',
+        description: [
+            'If true, display the cumulative distribution by summing the',
+            'binned values. Use the `direction` and `centralbin` attributes',
+            'to tune the accumulation method.'
+        ].join(' ')
+    },
+
+    direction: {
         valType: 'enumerated',
-        values: ['density', 'cumulative'],
-        dflt: 'density',
+        values: ['increasing', 'decreasing'],
+        dflt: 'increasing',
         role: 'info',
         description: [
-            ''
-        ].join('')
+            'Only applies if `cumulative=true.',
+            'If *increasing* (default) we sum all prior bins, so the result',
+            'increases from left to right. If *decreasing* we sum later bins',
+            'so the fresult decreases from left to right.'
+        ].join(' ')
+    },
+
+    currentbin: {
+        valType: 'enumerated',
+        values: ['include', 'exclude', 'half'],
+        dflt: 'include',
+        role: 'info',
+        description: [
+            'Only applies if `cumulative=true.',
+            'Sets whether the current bin is included, excluded, or has half',
+            'of its value included in the current cumulative value.',
+            '*include* is the default for compatibility with various other',
+            'tools, however it introduces a half-bin bias to the results.',
+            '*exclude* makes the opposite half-bin bias, and *half* removes',
+            'it.'
+        ].join(' ')
     },
 
     autobinx: {

src/traces/histogram/calc.js

@@ -41,15 +41,29 @@ module.exports = function calc(gd, trace) {
     var pos0 = pa.makeCalcdata(trace, maindata);
 
     // calculate the bins
-    if((trace['autobin' + maindata] !== false) || !(maindata + 'bins' in trace)) {
-        trace[maindata + 'bins'] = Axes.autoBin(pos0, pa, trace['nbins' + maindata], false, calendar);
+    var binAttr = maindata + 'bins',
+        binspec;
+    if((trace['autobin' + maindata] !== false) || !(binAttr in trace)) {
+        binspec = Axes.autoBin(pos0, pa, trace['nbins' + maindata], false, calendar);
+
+        // adjust for CDF edge cases
+        if(trace.cumulative && (trace.currentbin !== 'include')) {
+            if(trace.direction === 'decreasing') {
+                binspec.start = pa.c2r(pa.r2c(binspec.start) - binspec.size);
+            }
+            else {
+                binspec.end = pa.c2r(pa.r2c(binspec.end) + binspec.size);
+            }
+        }
 
-        // copy bin info back to the source data.
-        trace._input[maindata + 'bins'] = trace[maindata + 'bins'];
+        // copy bin info back to the source and full data.
+        trace._input[binAttr] = trace[binAttr] = binspec;
+    }
+    else {
+        binspec = trace[binAttr];
     }
 
-    var binspec = trace[maindata + 'bins'],
-        nonuniformBins = typeof binspec.size === 'string',
+    var nonuniformBins = typeof binspec.size === 'string',
         bins = nonuniformBins ? [] : binspec,
         // make the empty bin array
         i2,
@@ -115,7 +129,9 @@ module.exports = function calc(gd, trace) {
     // average and/or normalize the data, if needed
     if(doavg) total = doAvg(size, counts);
     if(normfunc) normfunc(size, total, inc);
-    if(trace.mode === 'cumulative') cdf(size);
+
+    // after all normalization etc, now we can accumulate if desired
+    if(trace.cumulative) cdf(size, trace.direction, trace.currentbin);
 
 
     var serieslen = Math.min(pos.length, size.length),
@@ -146,8 +162,56 @@ module.exports = function calc(gd, trace) {
     return cd;
 };
 
-function cdf(size) {
-    for(var i = 1; i < size.length; i++) {
-        size[i] += size[i - 1];
+function cdf(size, direction, currentbin) {
+    var i,
+        vi,
+        prevSum;
+
+    function firstHalfPoint(i) {
+        prevSum = size[i];
+        size[i] /= 2;
+    }
+
+    function nextHalfPoint(i) {
+        vi = size[i];
+        size[i] = prevSum + vi / 2;
+        prevSum += vi;
+    }
+
+    if(currentbin === 'half') {
+
+        if(direction === 'increasing') {
+            firstHalfPoint(0);
+            for(i = 1; i < size.length; i++) {
+                nextHalfPoint(i);
+            }
+        }
+        else {
+            firstHalfPoint(size.length - 1);
+            for(i = size.length - 2; i >= 0; i--) {
+                nextHalfPoint(i);
+            }
+        }
+    }
+    else if(direction === 'increasing') {
+        for(i = 1; i < size.length; i++) {
+            size[i] += size[i - 1];
+        }
+
+        // 'exclude' is identical to 'include' just shifted one bin over
+        if(currentbin === 'exclude') {
+            size.unshift(0);
+            size.pop();
+        }
+    }
+    else {
+        for(i = size.length - 2; i >= 0; i--) {
+            size[i] += size[i + 1];
+        }
+
+        if(currentbin === 'exclude') {
+            size.push(0);
+            size.shift();
+        }
     }
 }

src/traces/histogram/defaults.js

@@ -27,7 +27,12 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     var x = coerce('x'),
         y = coerce('y');
 
-    coerce('mode');
+    var cumulative = coerce('cumulative');
+    if(cumulative) {
+        coerce('direction');
+        coerce('currentbin');
+    }
+
     coerce('text');
 
     var orientation = coerce('orientation', (y && !x) ? 'h' : 'v'),

test/jasmine/tests/histogram_test.js

@@ -246,5 +246,76 @@ describe('Test histogram', function() {
             ]);
         });
 
+        describe('cumulative distribution functions', function() {
+            var base = {x: [1, 2, 3, 4, 2, 3, 4, 3, 4, 4]};
+
+            it('makes the right base histogram', function() {
+                var baseOut = _calc(base);
+                expect(baseOut).toEqual([
+                    {b: 0, p: 1, s: 1},
+                    {b: 0, p: 2, s: 2},
+                    {b: 0, p: 3, s: 3},
+                    {b: 0, p: 4, s: 4},
+                ]);
+            });
+
+            var CDFs = [
+                {p: [1, 2, 3, 4], s: [1, 3, 6, 10]},
+                {
+                    direction: 'decreasing',
+                    p: [1, 2, 3, 4], s: [10, 9, 7, 4]
+                },
+                {
+                    currentbin: 'exclude',
+                    p: [2, 3, 4, 5], s: [1, 3, 6, 10]
+                },
+                {
+                    direction: 'decreasing', currentbin: 'exclude',
+                    p: [0, 1, 2, 3], s: [10, 9, 7, 4]
+                },
+                {
+                    currentbin: 'half',
+                    p: [1, 2, 3, 4, 5], s: [0.5, 2, 4.5, 8, 10]
+                },
+                {
+                    direction: 'decreasing', currentbin: 'half',
+                    p: [0, 1, 2, 3, 4], s: [10, 9.5, 8, 5.5, 2]
+                },
+                {
+                    direction: 'decreasing', currentbin: 'half', histnorm: 'percent',
+                    p: [0, 1, 2, 3, 4], s: [100, 95, 80, 55, 20]
+                },
+                {
+                    currentbin: 'exclude', histnorm: 'probability',
+                    p: [2, 3, 4, 5], s: [0.1, 0.3, 0.6, 1]
+                }
+            ];
+
+            CDFs.forEach(function(CDF) {
+                var direction = CDF.direction,
+                    currentbin = CDF.currentbin,
+                    histnorm = CDF.histnorm,
+                    p = CDF.p,
+                    s = CDF.s;
+
+                it('handles direction=' + direction + ', currentbin=' + currentbin + ', histnorm=' + histnorm, function() {
+                    var traceIn = Lib.extendFlat({}, base, {
+                        cumulative: true,
+                        direction: direction,
+                        currentbin: currentbin,
+                        histnorm: histnorm
+                    });
+                    var out = _calc(traceIn);
+
+                    expect(out.length).toBe(p.length);
+                    out.forEach(function(outi, i) {
+                        expect(outi.p).toBe(p[i]);
+                        expect(outi.s).toBeCloseTo(s[i], 6);
+                        expect(outi.b).toBe(0);
+                    });
+                });
+            });
+        });
+
     });
 });