add quartilemethod attribute to box traces

... with values 'linear', 'exclusive' and 'inclusive'

Author: etpinard

src/traces/box/attributes.js

@@ -187,6 +187,30 @@ module.exports = {
         ].join(' ')
     },
 
+    quartilemethod: {
+        valType: 'enumerated',
+        values: ['linear', 'exclusive', 'inclusive'],
+        dflt: 'linear',
+        role: 'info',
+        editType: 'calc',
+        description: [
+            'Sets the method used to compute the sample\'s Q1 and Q3 quartiles.',
+
+            'The *linear* method uses the 25th percentile for Q1 and 75th percentile for Q3',
+            'as computed using method #10 listed on http://www.amstat.org/publications/jse/v14n3/langford.html).',
+
+            'The *exclusive* method uses the median to divide the ordered dataset into two halves',
+            'if the sample is odd, it does not includes the median in either half -',
+            'Q1 is then the median of the lower half and',
+            'Q3 the median of the upper half.',
+
+            'The *inclusive* method also uses the median to divide the ordered dataset into two halves',
+            'but if the sample is odd, it includes the median in both halves -',
+            'Q1 is then the median of the lower half and',
+            'Q3 the median of the upper half.'
+        ].join(' ')
+    },
+
     width: {
         valType: 'number',
         min: 0,

src/traces/box/calc.js

@@ -77,35 +77,54 @@ module.exports = function calc(gd, trace) {
         if(ptsPerBin[i].length > 0) {
             var pts = ptsPerBin[i].sort(sortByVal);
             var boxVals = pts.map(extractVal);
-            var bvLen = boxVals.length;
+            var N = boxVals.length;
 
             cdi = {};
             cdi.pos = posDistinct[i];
             cdi.pts = pts;
 
             // Sort categories by values
             cdi[posLetter] = cdi.pos;
-            cdi[valLetter] = cdi.pts.map(function(pt) { return pt.v; });
+            cdi[valLetter] = cdi.pts.map(extractVal);
 
             cdi.min = boxVals[0];
-            cdi.max = boxVals[bvLen - 1];
-            cdi.mean = Lib.mean(boxVals, bvLen);
-            cdi.sd = Lib.stdev(boxVals, bvLen, cdi.mean);
+            cdi.max = boxVals[N - 1];
+            cdi.mean = Lib.mean(boxVals, N);
+            cdi.sd = Lib.stdev(boxVals, N, cdi.mean);
 
-            // first quartile
-            cdi.q1 = Lib.interp(boxVals, 0.25);
-             // median
+            // median
             cdi.med = Lib.interp(boxVals, 0.5);
-            // third quartile
-            cdi.q3 = Lib.interp(boxVals, 0.75);
+
+            var quartilemethod = trace.quartilemethod;
+
+            if((N % 2) && (quartilemethod === 'exclusive' || quartilemethod === 'inclusive')) {
+                var lower;
+                var upper;
+
+                if(quartilemethod === 'exclusive') {
+                    // do NOT include the median in either half
+                    lower = boxVals.slice(0, N / 2);
+                    upper = boxVals.slice(N / 2 + 1);
+                } else if(quartilemethod === 'inclusive') {
+                    // include the median in either half
+                    lower = boxVals.slice(0, N / 2 + 1);
+                    upper = boxVals.slice(N / 2);
+                }
+
+                cdi.q1 = Lib.interp(lower, 0.5);
+                cdi.q3 = Lib.interp(upper, 0.5);
+            } else {
+                cdi.q1 = Lib.interp(boxVals, 0.25);
+                cdi.q3 = Lib.interp(boxVals, 0.75);
+            }
 
             // lower and upper fences - last point inside
             // 1.5 interquartile ranges from quartiles
             cdi.lf = Math.min(
                 cdi.q1,
                 boxVals[Math.min(
                     Lib.findBin(2.5 * cdi.q1 - 1.5 * cdi.q3, boxVals, true) + 1,
-                    bvLen - 1
+                    N - 1
                 )]
             );
             cdi.uf = Math.max(
@@ -123,7 +142,7 @@ module.exports = function calc(gd, trace) {
 
             // lower and upper notches ~95% Confidence Intervals for median
             var iqr = cdi.q3 - cdi.q1;
-            var mci = 1.57 * iqr / Math.sqrt(bvLen);
+            var mci = 1.57 * iqr / Math.sqrt(N);
             cdi.ln = cdi.med - mci;
             cdi.un = cdi.med + mci;
             minLowerNotch = Math.min(minLowerNotch, cdi.ln);

src/traces/box/defaults.js

@@ -29,6 +29,7 @@ function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
     coerce('whiskerwidth');
     coerce('boxmean');
     coerce('width');
+    coerce('quartilemethod');
 
     var notched = coerce('notched', traceIn.notchwidth !== undefined);
     if(notched) coerce('notchwidth');

test/image/baselines/box_quartile-methods.png

@@ -0,0 +1,17 @@
+{
+  "data": [{
+    "type": "box",
+    "y": [1, 2, 3, 4, 5],
+    "name": "linear"
+  }, {
+    "type": "box",
+    "y": [1, 2, 3, 4, 5],
+    "name": "exclusive",
+    "quartilemethod": "exclusive"
+  }, {
+    "type": "box",
+    "y": [1, 2, 3, 4, 5],
+    "name": "inclusive",
+    "quartilemethod": "inclusive"
+  }]
+}

test/image/mocks/box_quartile-methods.json

@@ -1,5 +1,6 @@
 var Plotly = require('@lib');
 var Lib = require('@src/lib');
+var Plots = require('@src/plots/plots');
 
 var Box = require('@src/traces/box');
 
@@ -610,3 +611,94 @@ describe('Test box restyle:', function() {
         .then(done);
     });
 });
+
+describe('Test box calc', function() {
+    var gd;
+
+    function _calc(attrs, layout) {
+        gd = {
+            data: [Lib.extendFlat({type: 'box'}, attrs)],
+            layout: layout || {},
+            calcdata: []
+        };
+        supplyAllDefaults(gd);
+        Plots.doCalcdata(gd);
+        return gd.calcdata[0];
+    }
+
+    it('should compute q1/q3 depending on *quartilemethod*', function() {
+        // samples from https://en.wikipedia.org/wiki/Quartile
+        var specs = {
+            // N is odd and is spanned by (4n+3)
+            odd: {
+                sample: [6, 7, 15, 36, 39, 40, 41, 42, 43, 47, 49],
+                methods: {
+                    linear: {q1: 20.25, q3: 42.75},
+                    exclusive: {q1: 15, q3: 43},
+                    inclusive: {q1: 25.5, q3: 42.5}
+                }
+            },
+            // N is odd and is spanned by (4n+1)
+            odd2: {
+                sample: [6, 15, 36, 39, 40, 42, 43, 47, 49],
+                methods: {
+                    linear: {q1: 30.75, q3: 44},
+                    exclusive: {q1: 25.5, q3: 45},
+                    inclusive: {q1: 36, q3: 43}
+                }
+            },
+            // N is even
+            even: {
+                sample: [7, 15, 36, 39, 40, 41],
+                methods: {
+                    linear: {q1: 15, q3: 40},
+                    exclusive: {q1: 15, q3: 40},
+                    inclusive: {q1: 15, q3: 40}
+                }
+            },
+            // samples from http://jse.amstat.org/v14n3/langford.html
+            s4: {
+                sample: [1, 2, 3, 4],
+                methods: {
+                    linear: {q1: 1.5, q3: 3.5},
+                    exclusive: {q1: 1.5, q3: 3.5},
+                    inclusive: {q1: 1.5, q3: 3.5}
+                }
+            },
+            s5: {
+                sample: [1, 2, 3, 4, 5],
+                methods: {
+                    linear: {q1: 1.75, q3: 4.25},
+                    exclusive: {q1: 1.5, q3: 4.5},
+                    inclusive: {q1: 2, q3: 4}
+                }
+            },
+            s6: {
+                sample: [1, 2, 3, 4, 5, 6],
+                methods: {
+                    linear: {q1: 2, q3: 5},
+                    exclusive: {q1: 2, q3: 5},
+                    inclusive: {q1: 2, q3: 5}
+                }
+            },
+            s7: {
+                sample: [1, 2, 3, 4, 5, 6, 7],
+                methods: {
+                    linear: {q1: 2.25, q3: 5.75},
+                    exclusive: {q1: 2, q3: 6},
+                    inclusive: {q1: 2.5, q3: 5.5}
+                }
+            }
+        };
+
+        for(var name in specs) {
+            var spec = specs[name];
+
+            for(var m in spec.methods) {
+                var cd = _calc({y: spec.sample, quartilemethod: m});
+                expect(cd[0].q1).toBe(spec.methods[m].q1, ['q1', m, name].join(' | '));
+                expect(cd[0].q3).toBe(spec.methods[m].q3, ['q3', m, name].join(' | '));
+            }
+        }
+    });
+});