Adding box plots drawn on std-deviation instead of quartiles

CONTRIBUTING.md

@@ -118,7 +118,7 @@ npm start
 
 This command bundles up the source files and opens up a tab in your browser.
 
-#### Step 6: Open up the console and start developing
+#### Step 6a: Open up the console and start developing
 
 A typical workflow is to make some modifications to the source, update the
 test dashboard, inspect and debug the changes, then repeat. The test dashboard
@@ -146,6 +146,12 @@ Three additional helpers exist that are refreshed every second:
 There is also a search bar in the top right of the dashboard. This fuzzy-searches
 image mocks based on their file name and trace type.
 
+#### Step 6b: Create a mock to test new features
+Create a new JSON inside
+`test\image\mocks\`
+which you'll then be able to search from the test dashboard
+
+
 #### Step 7: Regenerate plot-schema in "test" folder then review & commit potential changes
 
 ```bash

draftlogs/6697_add.md

@@ -0,0 +1 @@
+- Add [1-6]-sigma (std deviations) box plots as an alternative to quartiles [[#6697](https://github.com/plotly/plotly.js/issues/6697)]

src/traces/box/attributes.js

@@ -218,7 +218,30 @@ module.exports = {
             'right (left) for vertical boxes and above (below) for horizontal boxes'
         ].join(' ')
     },
-
+    sdmultiple: {
+        valType: 'number',
+        min: 0,
+        editType: 'calc',
+        dflt: 1,
+        description: [
+            'Scales the box size when sizemode=sd',
+            'Allowing boxes to be drawn across any stddev range',
+            'For example 1-stddev, 3-stddev, 5-stddev',
+        ].join(' ')
+    },
+    sizemode: {
+        valType: 'enumerated',
+        values: ['quartiles', 'sd'],
+        editType: 'calc',
+        dflt: 'quartiles',
+        description: [
+            'Sets the upper and lower bound for the boxes',
+            'quartiles means box is drawn between Q1 and Q3',
+            'SD means the box is drawn between Mean +- Standard Deviation',
+            'Argument sdmultiple (default 1) to scale the box size',
+            'So it could be drawn 1-stddev, 3-stddev etc',
+        ].join(' ')
+    },
     boxmean: {
         valType: 'enumerated',
         values: [true, 'sd', false],
@@ -378,6 +401,15 @@ module.exports = {
         ].join(' ')
     },
 
+    showwhiskers: {
+        valType: 'boolean',
+        dflt: true,
+        editType: 'calc',
+        description: [
+            'Determines whether or not whiskers are visible'
+        ].join(' ')
+    },
+
     offsetgroup: barAttrs.offsetgroup,
     alignmentgroup: barAttrs.alignmentgroup,
 

src/traces/box/calc.js

@@ -221,7 +221,7 @@ module.exports = function calc(gd, trace) {
                 cdi.min = boxVals[0];
                 cdi.max = boxVals[N - 1];
                 cdi.mean = Lib.mean(boxVals, N);
-                cdi.sd = Lib.stdev(boxVals, N, cdi.mean);
+                cdi.sd = Lib.stdev(boxVals, N, cdi.mean) * trace.sdmultiple;
                 cdi.med = Lib.interp(boxVals, 0.5);
 
                 if((N % 2) && (usesExclusive || usesInclusive)) {
@@ -286,7 +286,7 @@ module.exports = function calc(gd, trace) {
                 q1: _(gd, 'q1:'),
                 q3: _(gd, 'q3:'),
                 max: _(gd, 'max:'),
-                mean: trace.boxmean === 'sd' ? _(gd, 'mean ± σ:') : _(gd, 'mean:'),
+                mean: (trace.boxmean === 'sd') || (trace.sizemode === 'sd') ? (gd, 'mean ± ' + trace.sdmultiple + 'σ:') : _(gd, 'mean:'),
                 lf: _(gd, 'lower fence:'),
                 uf: _(gd, 'upper fence:')
             }

src/traces/box/defaults.js

@@ -43,6 +43,9 @@ function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
     coerce('boxmean', boxmeanDflt);
 
     coerce('whiskerwidth');
+    coerce('showwhiskers');
+    coerce('sizemode');
+    coerce('sdmultiple');
     coerce('width');
     coerce('quartilemethod');
 

src/traces/box/hover.js

@@ -140,7 +140,7 @@ function hoverOnBoxes(pointData, xval, yval, hovermode) {
     pointData.spikeDistance = dxy(di) * spikePseudoDistance / hoverPseudoDistance;
     pointData[spikePosAttr] = pAxis.c2p(di.pos, true);
 
-    var hasMean = trace.boxmean || (trace.meanline || {}).visible;
+    var hasMean = trace.boxmean || (trace.sizemode === 'sd') || (trace.meanline || {}).visible;
     var hasFences = trace.boxpoints || trace.points;
 
     // labels with equal values (e.g. when min === q1) should still be presented in the order they have when they're unequal
@@ -179,7 +179,7 @@ function hoverOnBoxes(pointData, xval, yval, hovermode) {
         // clicked point from a box during click-to-select
         pointData2.hoverOnBox = true;
 
-        if(attr === 'mean' && ('sd' in di) && trace.boxmean === 'sd') {
+        if(attr === 'mean' && ('sd' in di) && ((trace.boxmean === 'sd') || (trace.sizemode === 'sd'))) {
             pointData2[vLetter + 'err'] = di.sd;
         }
 

src/traces/box/plot.js

@@ -54,6 +54,7 @@ function plotBoxAndWhiskers(sel, axes, trace, t, isStatic) {
     var wdPos = t.wdPos || 0;
     var bPosPxOffset = t.bPosPxOffset || 0;
     var whiskerWidth = trace.whiskerwidth || 0;
+    var showWhiskers = trace.showwhiskers;
     var notched = trace.notched || false;
     var nw = notched ? 1 - 2 * trace.notchwidth : 1;
 
@@ -94,12 +95,15 @@ function plotBoxAndWhiskers(sel, axes, trace, t, isStatic) {
 
         var posm0 = posAxis.l2p(lcenter - bdPos0 * nw) + bPosPxOffset;
         var posm1 = posAxis.l2p(lcenter + bdPos1 * nw) + bPosPxOffset;
-        var q1 = valAxis.c2p(d.q1, true);
-        var q3 = valAxis.c2p(d.q3, true);
+        var q1 = trace.sizemode === 'sd' ? valAxis.c2p(d.mean - 1 * d.sd, true) :
+                                           valAxis.c2p(d.q1, true);
+        var q3 = trace.sizemode === 'sd' ? valAxis.c2p(d.mean + 1 * d.sd, true) :
+                                           valAxis.c2p(d.q3, true);
         // make sure median isn't identical to either of the
         // quartiles, so we can see it
         var m = Lib.constrain(
-            valAxis.c2p(d.med, true),
+            trace.sizemode === 'sd' ? valAxis.c2p(d.mean, true) :
+                                      valAxis.c2p(d.med, true),
             Math.min(q1, q3) + 1, Math.max(q1, q3) - 1
         );
 
@@ -109,7 +113,7 @@ function plotBoxAndWhiskers(sel, axes, trace, t, isStatic) {
         // - box always has d.lf, but boxpoints can be anything
         // - violin has d.lf and should always use it (boxpoints is undefined)
         // - candlestick has only min/max
-        var useExtremes = (d.lf === undefined) || (trace.boxpoints === false);
+        var useExtremes = (d.lf === undefined) || (trace.boxpoints === false) || (trace.sizemode === 'sd');
         var lf = valAxis.c2p(useExtremes ? d.min : d.lf, true);
         var uf = valAxis.c2p(useExtremes ? d.max : d.uf, true);
         var ln = valAxis.c2p(d.ln, true);
@@ -127,10 +131,13 @@ function plotBoxAndWhiskers(sel, axes, trace, t, isStatic) {
                 'V' + pos0 + // right edge
                 (notched ? 'H' + un + 'L' + m + ',' + posm0 + 'L' + ln + ',' + pos0 : '') + // bottom notched edge
                 'Z' + // end of the box
-                'M' + q1 + ',' + posc + 'H' + lf + 'M' + q3 + ',' + posc + 'H' + uf + // whiskers
-                (whiskerWidth === 0 ?
-                    '' : // whisker caps
-                    'M' + lf + ',' + posw0 + 'V' + posw1 + 'M' + uf + ',' + posw0 + 'V' + posw1
+                (showWhiskers ?
+                    'M' + q1 + ',' + posc + 'H' + lf + 'M' + q3 + ',' + posc + 'H' + uf + // whiskers
+                    (whiskerWidth === 0 ?
+                        '' : // whisker caps
+                        'M' + lf + ',' + posw0 + 'V' + posw1 + 'M' + uf + ',' + posw0 + 'V' + posw1
+                    ) :
+                    ''
                 )
             );
         } else {
@@ -148,10 +155,13 @@ function plotBoxAndWhiskers(sel, axes, trace, t, isStatic) {
                     ''
                 ) + // notched left edge
                 'Z' + // end of the box
-                'M' + posc + ',' + q1 + 'V' + lf + 'M' + posc + ',' + q3 + 'V' + uf + // whiskers
-                (whiskerWidth === 0 ?
-                    '' : // whisker caps
-                    'M' + posw0 + ',' + lf + 'H' + posw1 + 'M' + posw0 + ',' + uf + 'H' + posw1
+                (showWhiskers ?
+                    'M' + posc + ',' + q1 + 'V' + lf + 'M' + posc + ',' + q3 + 'V' + uf + // whiskers
+                    (whiskerWidth === 0 ?
+                        '' : // whisker caps
+                        'M' + posw0 + ',' + lf + 'H' + posw1 + 'M' + posw0 + ',' + uf + 'H' + posw1
+                    ) :
+                    ''
                 )
             );
         }

test/image/mocks/box_sizemode_sd.json

@@ -0,0 +1,156 @@
+{
+  "data": [
+    {
+      "y": [
+        0.4995, 0.3786, 0.5188, 0.4505, 0.5805, 0.5539, 0.7341, 0.3303, 0.6202, 0.4754, 0.4814, 0.6103, 0.5157, 0.3841, 0.6166, 0.4917, 0.5646, 0.4532, 0.5983,
+        0.5079, 0.5227, 0.5483, 0.3081, 0.5172, 0.4127, 0.3871, 0.4703, 0.5331, 0.4573, 0.6187, 0.5718, 0.4474, 0.5349, 0.4614, 0.3096, 0.4411, 0.7143, 0.5956,
+        0.5171, 0.5515, 0.4234, 0.4589, 0.4289, 0.417, 0.4229, 0.5039, 0.4726, 0.5382, 0.261, 0.5326, 0.4472, 0.54, 0.4998, 0.5513, 0.3891, 0.4821, 0.5006,
+        0.4362, 0.4184, 0.3632, 0.5182, 0.5229, 0.5493, 0.507, 0.4528, 0.4836, 0.5009, 0.49, 0.5757, 0.5408, 0.4246, 0.511, 0.5216, 0.3817, 0.4471, 0.4935,
+        0.5668, 0.3187, 0.3633, 0.5964, 0.637, 0.4701, 0.4292, 0.4921, 0.439, 0.5846, 0.4502, 0.44, 0.3057, 0.4756, 0.4867, 0.502, 0.438, 0.6819, 0.2607,
+        0.5233, 0.3291, 0.5555, 0.5397, 0.5068
+      ],
+      "line": {
+        "color": "#1c9099"
+      },
+      "type": "box",
+      "boxpoints": "all",
+      "pointpos": 0,
+      "name": "1-sigma",
+      "sizemode": "sd",
+      "showwhiskers": false
+    },
+    {
+      "y": [
+         0.4995, 0.3786, 0.5188, 0.4505, 0.5805, 0.5539, 0.7341, 0.3303, 0.6202, 0.4754, 0.4814, 0.6103, 0.5157, 0.3841, 0.6166, 0.4917, 0.5646, 0.4532, 0.5983,
+         0.5079, 0.5227, 0.5483, 0.3081, 0.5172, 0.4127, 0.3871, 0.4703, 0.5331, 0.4573, 0.6187, 0.5718, 0.4474, 0.5349, 0.4614, 0.3096, 0.4411, 0.7143, 0.5956,
+         0.5171, 0.5515, 0.4234, 0.4589, 0.4289, 0.417, 0.4229, 0.5039, 0.4726, 0.5382, 0.261, 0.5326, 0.4472, 0.54, 0.4998, 0.5513, 0.3891, 0.4821, 0.5006,
+         0.4362, 0.4184, 0.3632, 0.5182, 0.5229, 0.5493, 0.507, 0.4528, 0.4836, 0.5009, 0.49, 0.5757, 0.5408, 0.4246, 0.511, 0.5216, 0.3817, 0.4471, 0.4935,
+         0.5668, 0.3187, 0.3633, 0.5964, 0.637, 0.4701, 0.4292, 0.4921, 0.439, 0.5846, 0.4502, 0.44, 0.3057, 0.4756, 0.4867, 0.502, 0.438, 0.6819, 0.2607,
+         0.5233, 0.3291, 0.5555, 0.5397, 0.5068
+       ],
+      "line": {
+        "color": "#1c9099"
+      },
+      "boxpoints": "all",
+      "pointpos": 0,
+      "type": "box",
+      "name": "2-sigma",
+      "sdmultiple" : 2,
+      "sizemode": "sd",
+      "showwhiskers": false
+    },
+    {
+      "y": [
+         0.4995, 0.3786, 0.5188, 0.4505, 0.5805, 0.5539, 0.7341, 0.3303, 0.6202, 0.4754, 0.4814, 0.6103, 0.5157, 0.3841, 0.6166, 0.4917, 0.5646, 0.4532, 0.5983,
+         0.5079, 0.5227, 0.5483, 0.3081, 0.5172, 0.4127, 0.3871, 0.4703, 0.5331, 0.4573, 0.6187, 0.5718, 0.4474, 0.5349, 0.4614, 0.3096, 0.4411, 0.7143, 0.5956,
+         0.5171, 0.5515, 0.4234, 0.4589, 0.4289, 0.417, 0.4229, 0.5039, 0.4726, 0.5382, 0.261, 0.5326, 0.4472, 0.54, 0.4998, 0.5513, 0.3891, 0.4821, 0.5006,
+         0.4362, 0.4184, 0.3632, 0.5182, 0.5229, 0.5493, 0.507, 0.4528, 0.4836, 0.5009, 0.49, 0.5757, 0.5408, 0.4246, 0.511, 0.5216, 0.3817, 0.4471, 0.4935,
+         0.5668, 0.3187, 0.3633, 0.5964, 0.637, 0.4701, 0.4292, 0.4921, 0.439, 0.5846, 0.4502, 0.44, 0.3057, 0.4756, 0.4867, 0.502, 0.438, 0.6819, 0.2607,
+         0.5233, 0.3291, 0.5555, 0.5397, 0.5068
+        ],
+      "line": {
+        "color": "#1c9099"
+      },
+      "type": "box",
+      "boxpoints": "all",
+      "pointpos": 0,
+      "name": "3-sigma",
+      "sdmultiple" : 3,
+      "sizemode": "sd",
+      "showwhiskers": false
+    },
+    {
+      "y": [
+         0.4995, 0.3786, 0.5188, 0.4505, 0.5805, 0.5539, 0.7341, 0.3303, 0.6202, 0.4754, 0.4814, 0.6103, 0.5157, 0.3841, 0.6166, 0.4917, 0.5646, 0.4532, 0.5983,
+         0.5079, 0.5227, 0.5483, 0.3081, 0.5172, 0.4127, 0.3871, 0.4703, 0.5331, 0.4573, 0.6187, 0.5718, 0.4474, 0.5349, 0.4614, 0.3096, 0.4411, 0.7143, 0.5956,
+         0.5171, 0.5515, 0.4234, 0.4589, 0.4289, 0.417, 0.4229, 0.5039, 0.4726, 0.5382, 0.261, 0.5326, 0.4472, 0.54, 0.4998, 0.5513, 0.3891, 0.4821, 0.5006,
+         0.4362, 0.4184, 0.3632, 0.5182, 0.5229, 0.5493, 0.507, 0.4528, 0.4836, 0.5009, 0.49, 0.5757, 0.5408, 0.4246, 0.511, 0.5216, 0.3817, 0.4471, 0.4935,
+         0.5668, 0.3187, 0.3633, 0.5964, 0.637, 0.4701, 0.4292, 0.4921, 0.439, 0.5846, 0.4502, 0.44, 0.3057, 0.4756, 0.4867, 0.502, 0.438, 0.6819, 0.2607,
+         0.5233, 0.3291, 0.5555, 0.5397, 0.5068
+       ],
+      "line": {
+        "color": "#1c9099"
+      },
+      "type": "box",
+      "boxpoints": "all",
+      "pointpos": 0,
+      "name": "1-sigma + whiskers",
+      "sizemode": "sd",
+      "showwhiskers": true
+    },
+    {
+      "y": [
+         0.4995, 0.3786, 0.5188, 0.4505, 0.5805, 0.5539, 0.7341, 0.3303, 0.6202, 0.4754, 0.4814, 0.6103, 0.5157, 0.3841, 0.6166, 0.4917, 0.5646, 0.4532, 0.5983,
+         0.5079, 0.5227, 0.5483, 0.3081, 0.5172, 0.4127, 0.3871, 0.4703, 0.5331, 0.4573, 0.6187, 0.5718, 0.4474, 0.5349, 0.4614, 0.3096, 0.4411, 0.7143, 0.5956,
+         0.5171, 0.5515, 0.4234, 0.4589, 0.4289, 0.417, 0.4229, 0.5039, 0.4726, 0.5382, 0.261, 0.5326, 0.4472, 0.54, 0.4998, 0.5513, 0.3891, 0.4821, 0.5006,
+         0.4362, 0.4184, 0.3632, 0.5182, 0.5229, 0.5493, 0.507, 0.4528, 0.4836, 0.5009, 0.49, 0.5757, 0.5408, 0.4246, 0.511, 0.5216, 0.3817, 0.4471, 0.4935,
+         0.5668, 0.3187, 0.3633, 0.5964, 0.637, 0.4701, 0.4292, 0.4921, 0.439, 0.5846, 0.4502, 0.44, 0.3057, 0.4756, 0.4867, 0.502, 0.438, 0.6819, 0.2607,
+         0.5233, 0.3291, 0.5555, 0.5397, 0.5068
+       ],
+      "line": {
+        "color": "#1c9099"
+      },
+      "boxpoints": "all",
+      "pointpos": 0,
+      "type": "box",
+      "name": "3-sigma + whiskers",
+      "sdmultiple" : 3,
+      "sizemode": "sd",
+      "showwhiskers": true
+    },
+    {
+      "y": [
+         0.4995, 0.3786, 0.5188, 0.4505, 0.5805, 0.5539, 0.7341, 0.3303, 0.6202, 0.4754, 0.4814, 0.6103, 0.5157, 0.3841, 0.6166, 0.4917, 0.5646, 0.4532, 0.5983,
+         0.5079, 0.5227, 0.5483, 0.3081, 0.5172, 0.4127, 0.3871, 0.4703, 0.5331, 0.4573, 0.6187, 0.5718, 0.4474, 0.5349, 0.4614, 0.3096, 0.4411, 0.7143, 0.5956,
+         0.5171, 0.5515, 0.4234, 0.4589, 0.4289, 0.417, 0.4229, 0.5039, 0.4726, 0.5382, 0.261, 0.5326, 0.4472, 0.54, 0.4998, 0.5513, 0.3891, 0.4821, 0.5006,
+         0.4362, 0.4184, 0.3632, 0.5182, 0.5229, 0.5493, 0.507, 0.4528, 0.4836, 0.5009, 0.49, 0.5757, 0.5408, 0.4246, 0.511, 0.5216, 0.3817, 0.4471, 0.4935,
+         0.5668, 0.3187, 0.3633, 0.5964, 0.637, 0.4701, 0.4292, 0.4921, 0.439, 0.5846, 0.4502, 0.44, 0.3057, 0.4756, 0.4867, 0.502, 0.438, 0.6819, 0.2607,
+         0.5233, 0.3291, 0.5555, 0.5397, 0.5068
+       ],
+      "line": {
+        "color": "#1c9099"
+      },
+      "boxpoints": "all",
+      "pointpos": 0,
+      "type": "box",
+      "name": "diamond 1-sigma",
+      "boxmean": "sd",
+      "showwhiskers": false
+    },
+    {
+      "y": [
+         0.4995, 0.3786, 0.5188, 0.4505, 0.5805, 0.5539, 0.7341, 0.3303, 0.6202, 0.4754, 0.4814, 0.6103, 0.5157, 0.3841, 0.6166, 0.4917, 0.5646, 0.4532, 0.5983,
+         0.5079, 0.5227, 0.5483, 0.3081, 0.5172, 0.4127, 0.3871, 0.4703, 0.5331, 0.4573, 0.6187, 0.5718, 0.4474, 0.5349, 0.4614, 0.3096, 0.4411, 0.7143, 0.5956,
+         0.5171, 0.5515, 0.4234, 0.4589, 0.4289, 0.417, 0.4229, 0.5039, 0.4726, 0.5382, 0.261, 0.5326, 0.4472, 0.54, 0.4998, 0.5513, 0.3891, 0.4821, 0.5006,
+         0.4362, 0.4184, 0.3632, 0.5182, 0.5229, 0.5493, 0.507, 0.4528, 0.4836, 0.5009, 0.49, 0.5757, 0.5408, 0.4246, 0.511, 0.5216, 0.3817, 0.4471, 0.4935,
+         0.5668, 0.3187, 0.3633, 0.5964, 0.637, 0.4701, 0.4292, 0.4921, 0.439, 0.5846, 0.4502, 0.44, 0.3057, 0.4756, 0.4867, 0.502, 0.438, 0.6819, 0.2607,
+         0.5233, 0.3291, 0.5555, 0.5397, 0.5068
+       ],
+      "line": {
+        "color": "#1c9099"
+      },
+      "boxpoints": "all",
+      "pointpos": 0,
+      "type": "box",
+      "name": "diamond 3-sigma",
+      "sdmultiple" : 3,
+      "boxmean": "sd",
+      "showwhiskers": false
+    }
+  ],
+  "layout": {
+    "showlegend": false,
+    "yaxis": {
+      "title": { "text": "Random Variable" },
+      "type": "linear",
+      "range":[-0.2, 1.2]
+    },
+    "title": { "text": "Box plots drawn on std deviation instead of quartiles" },
+    "xaxis": {
+      "type": "category"
+    },
+    "height": 598,
+    "width": 1080,
+    "autosize": true
+  }
+}

test/jasmine/tests/box_test.js

@@ -769,7 +769,7 @@ describe('Test box hover:', function() {
         },
         nums: [
             'median: 0.55', 'min: 0', 'lower fence: 0', 'q1: 0.3', 'q3: 0.6', 'upper fence: 0.7', 'max: 0.7',
-            'mean ± σ: 0.45 ± 0.2362908'
+            'mean ± 1σ: 0.45 ± 0.2362908'
         ],
         name: ['radishes', '', '', '', '', '', '', ''],
         axis: 'day 1'
@@ -927,7 +927,7 @@ describe('Test box hover:', function() {
             'max: 1',
             'lower fence: 0.3',
             'upper fence: 1',
-            'mean ± σ: 0.6833333 ± 0.2409472',
+            'mean ± 1σ: 0.6833333 ± 0.2409472',
         ],
         name: ['carrots', '', '', '', '', '', '', ''],
         axis: 'day 2'
@@ -943,7 +943,7 @@ describe('Test box hover:', function() {
             '(max: 1, day 2)',
             '(lower fence: 0.3, day 2)',
             '(upper fence: 1, day 2)',
-            '(mean ± σ: 0.6833333 ± 0.2409472, day 2)'
+            '(mean ± 1σ: 0.6833333 ± 0.2409472, day 2)'
         ],
         name: ['carrots', '', '', '', '', '', '', ''],
     }, {