introduce box 'hoveron'

- flaglist w/ 'boxes' (current + default) and 'points'
- use point object x/y values (from Box.plot) to determine
  closest point(s)
- consider jitter offset under hovermode closest,
  but don't under 'x' or 'y' modes

Author: etpinard

src/traces/box/attributes.js

@@ -203,5 +203,16 @@ module.exports = {
         },
         editType: 'plot'
     },
-    fillcolor: scatterAttrs.fillcolor
+    fillcolor: scatterAttrs.fillcolor,
+    hoveron: {
+        valType: 'flaglist',
+        flags: ['boxes', 'points'],
+        dflt: 'boxes',
+        role: 'info',
+        editType: 'style',
+        description: [
+            'Do the hover effects highlight individual boxes ',
+            'or jitter points or both?'
+        ].join(' ')
+    }
 };

src/traces/box/defaults.js

@@ -71,4 +71,6 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
             coerce('marker.line.outlierwidth');
         }
     }
+
+    coerce('hoveron');
 };

src/traces/box/hover.js

@@ -14,94 +14,167 @@ var Fx = require('../../components/fx');
 var Color = require('../../components/color');
 
 module.exports = function hoverPoints(pointData, xval, yval, hovermode) {
-    // closest mode: handicap box plots a little relative to others
-    var cd = pointData.cd,
-        trace = cd[0].trace,
-        t = cd[0].t,
-        xa = pointData.xa,
-        ya = pointData.ya,
-        closeData = [],
-        dx, dy, distfn, boxDelta,
-        posLetter, posAxis,
-        val, valLetter, valAxis;
-
-    // adjust inbox w.r.t. to calculate box size
-    boxDelta = (hovermode === 'closest') ? 2.5 * t.bdPos : t.bdPos;
-
-    if(trace.orientation === 'h') {
-        dx = function(di) {
-            return Fx.inbox(di.min - xval, di.max - xval);
-        };
-        dy = function(di) {
-            var pos = di.pos + t.bPos - yval;
-            return Fx.inbox(pos - boxDelta, pos + boxDelta);
-        };
-        posLetter = 'y';
-        posAxis = ya;
-        valLetter = 'x';
-        valAxis = xa;
-    } else {
-        dx = function(di) {
-            var pos = di.pos + t.bPos - xval;
-            return Fx.inbox(pos - boxDelta, pos + boxDelta);
-        };
-        dy = function(di) {
-            return Fx.inbox(di.min - yval, di.max - yval);
-        };
-        posLetter = 'x';
-        posAxis = xa;
-        valLetter = 'y';
-        valAxis = ya;
-    }
+    var cd = pointData.cd;
+    var xa = pointData.xa;
+    var ya = pointData.ya;
+
+    var trace = cd[0].trace;
+    var hoveron = trace.hoveron;
+    var marker = trace.marker || {};
+
+    // output hover points array
+    var closeData = [];
+    // x/y/effective distance functions
+    var dx, dy, distfn;
+    // orientation-specific fields
+    var posLetter, valLetter, posAxis, valAxis;
+    // calcdata item
+    var di;
+    // hover point item extended from pointData
+    var pointData2;
+    // loop indices
+    var i, j;
+
+    if(hoveron.indexOf('boxes') !== -1) {
+        var t = cd[0].t;
+
+        // closest mode: handicap box plots a little relative to others
+        // adjust inbox w.r.t. to calculate box size
+        var boxDelta = (hovermode === 'closest') ? 2.5 * t.bdPos : t.bdPos;
+
+        if(trace.orientation === 'h') {
+            dx = function(di) {
+                return Fx.inbox(di.min - xval, di.max - xval);
+            };
+            dy = function(di) {
+                var pos = di.pos + t.bPos - yval;
+                return Fx.inbox(pos - boxDelta, pos + boxDelta);
+            };
+            posLetter = 'y';
+            posAxis = ya;
+            valLetter = 'x';
+            valAxis = xa;
+        } else {
+            dx = function(di) {
+                var pos = di.pos + t.bPos - xval;
+                return Fx.inbox(pos - boxDelta, pos + boxDelta);
+            };
+            dy = function(di) {
+                return Fx.inbox(di.min - yval, di.max - yval);
+            };
+            posLetter = 'x';
+            posAxis = xa;
+            valLetter = 'y';
+            valAxis = ya;
+        }
+
+        distfn = Fx.getDistanceFunction(hovermode, dx, dy);
+        Fx.getClosest(cd, distfn, pointData);
 
-    distfn = Fx.getDistanceFunction(hovermode, dx, dy);
-    Fx.getClosest(cd, distfn, pointData);
+        // skip the rest (for this trace) if we didn't find a close point
+        // and create the item(s) in closedata for this point
+        if(pointData.index !== false) {
+            di = cd[pointData.index];
 
-    // skip the rest (for this trace) if we didn't find a close point
-    if(pointData.index === false) return;
+            var lc = trace.line.color;
+            var mc = marker.color;
 
-    // create the item(s) in closedata for this point
+            if(Color.opacity(lc) && trace.line.width) pointData.color = lc;
+            else if(Color.opacity(mc) && trace.boxpoints) pointData.color = mc;
+            else pointData.color = trace.fillcolor;
 
-    // the closest data point
-    var di = cd[pointData.index],
-        lc = trace.line.color,
-        mc = (trace.marker || {}).color;
-    if(Color.opacity(lc) && trace.line.width) pointData.color = lc;
-    else if(Color.opacity(mc) && trace.boxpoints) pointData.color = mc;
-    else pointData.color = trace.fillcolor;
+            pointData[posLetter + '0'] = posAxis.c2p(di.pos + t.bPos - t.bdPos, true);
+            pointData[posLetter + '1'] = posAxis.c2p(di.pos + t.bPos + t.bdPos, true);
 
-    pointData[posLetter + '0'] = posAxis.c2p(di.pos + t.bPos - t.bdPos, true);
-    pointData[posLetter + '1'] = posAxis.c2p(di.pos + t.bPos + t.bdPos, true);
+            Axes.tickText(posAxis, posAxis.c2l(di.pos), 'hover').text;
+            pointData[posLetter + 'LabelVal'] = di.pos;
 
-    Axes.tickText(posAxis, posAxis.c2l(di.pos), 'hover').text;
-    pointData[posLetter + 'LabelVal'] = di.pos;
+            // box plots: each "point" gets many labels
+            var usedVals = {};
+            var attrs = ['med', 'min', 'q1', 'q3', 'max'];
 
-    // box plots: each "point" gets many labels
-    var usedVals = {},
-        attrs = ['med', 'min', 'q1', 'q3', 'max'],
-        attr,
-        pointData2;
-    if(trace.boxmean) attrs.push('mean');
-    if(trace.boxpoints) [].push.apply(attrs, ['lf', 'uf']);
+            if(trace.boxmean) attrs.push('mean');
+            if(trace.boxpoints) [].push.apply(attrs, ['lf', 'uf']);
 
-    for(var i = 0; i < attrs.length; i++) {
-        attr = attrs[i];
+            for(i = 0; i < attrs.length; i++) {
+                var attr = attrs[i];
 
-        if(!(attr in di) || (di[attr] in usedVals)) continue;
-        usedVals[di[attr]] = true;
+                if(!(attr in di) || (di[attr] in usedVals)) continue;
+                usedVals[di[attr]] = true;
 
-        // copy out to a new object for each value to label
-        val = valAxis.c2p(di[attr], true);
-        pointData2 = Lib.extendFlat({}, pointData);
-        pointData2[valLetter + '0'] = pointData2[valLetter + '1'] = val;
-        pointData2[valLetter + 'LabelVal'] = di[attr];
-        pointData2.attr = attr;
+                // copy out to a new object for each value to label
+                var val = valAxis.c2p(di[attr], true);
+                pointData2 = Lib.extendFlat({}, pointData);
+                pointData2[valLetter + '0'] = pointData2[valLetter + '1'] = val;
+                pointData2[valLetter + 'LabelVal'] = di[attr];
+                pointData2.attr = attr;
 
-        if(attr === 'mean' && ('sd' in di) && trace.boxmean === 'sd') {
-            pointData2[valLetter + 'err'] = di.sd;
+                if(attr === 'mean' && ('sd' in di) && trace.boxmean === 'sd') {
+                    pointData2[valLetter + 'err'] = di.sd;
+                }
+                // only keep name on the first item (median)
+                pointData.name = '';
+
+                closeData.push(pointData2);
+            }
         }
-        pointData.name = ''; // only keep name on the first item (median)
-        closeData.push(pointData2);
     }
+
+    if(hoveron.indexOf('points') !== -1) {
+        var xPx = xa.c2p(xval);
+        var yPx = ya.c2p(yval);
+
+        // do not take jitter into consideration in compare hover modes
+        var kx, ky;
+        if(hovermode === 'closest') {
+            kx = 'x';
+            ky = 'y';
+        } else {
+            kx = 'xh';
+            ky = 'yh';
+        }
+
+        dx = function(di) {
+            var rad = Math.max(3, di.mrc || 0);
+            return Math.max(Math.abs(xa.c2p(di[kx]) - xPx) - rad, 1 - 3 / rad);
+        };
+        dy = function(di) {
+            var rad = Math.max(3, di.mrc || 0);
+            return Math.max(Math.abs(ya.c2p(di[ky]) - yPx) - rad, 1 - 3 / rad);
+        };
+        distfn = Fx.getDistanceFunction(hovermode, dx, dy);
+
+        for(i = 0; i < cd.length; i++) {
+            di = cd[i];
+
+            for(j = 0; j < (di.pts || []).length; j++) {
+                var pt = di.pts[j];
+
+                var newDistance = distfn(pt);
+                if(newDistance <= pointData.distance) {
+                    pointData.distance = newDistance;
+
+                    var xc = xa.c2p(pt.x, true);
+                    var yc = ya.c2p(pt.y, true);
+                    var rad = pt.mrc || 1;
+
+                    pointData2 = Lib.extendFlat({}, pointData, {
+                        // corresponds to index in x/y input data array
+                        index: pt.i,
+                        color: marker.color,
+                        x0: xc - rad,
+                        x1: xc + rad,
+                        xLabelVal: pt.x,
+                        y0: yc - rad,
+                        y1: yc + rad,
+                        yLabelVal: pt.y
+                    });
+
+                    closeData.push(pointData2);
+                }
+            }
+        }
+    }
+
     return closeData;
 };

src/traces/box/plot.js

@@ -183,7 +183,7 @@ module.exports = function plot(gd, plotinfo, cdbox) {
                         newJitter = trace.jitter * 2 / maxJitterFactor;
                     }
 
-                    // fills in 'x' and 'y' in calcdata 'pts' item
+                    // fills in 'x' and 'y' (with and w/o jitter offset) in calcdata 'pts' item
                     for(i = 0; i < pts.length; i++) {
                         var pt = pts[i];
                         var v = pt.v;
@@ -192,14 +192,17 @@ module.exports = function plot(gd, plotinfo, cdbox) {
                             bdPos * (newJitter * jitterFactors[i] * (rand() - 0.5)) :
                             0;
 
-                        var posPx = d.pos + bPos + bdPos * trace.pointpos + jitterOffset;
+                        var posPxNoJitter = d.pos + bPos + bdPos * trace.pointpos;
+                        var posPx = posPxNoJitter + jitterOffset;
 
                         if(trace.orientation === 'h') {
                             pt.y = posPx;
-                            pt.x = v;
+                            pt.yh = posPxNoJitter;
+                            pt.x = pt.xh = v;
                         } else {
                             pt.x = posPx;
-                            pt.y = v;
+                            pt.xh = posPxNoJitter;
+                            pt.y = pt.yh = v;
                         }
 
                         // tag suspected outliers

test/jasmine/tests/box_test.js

@@ -174,6 +174,48 @@ describe('Test box hover:', function() {
         nums: ['8.15', '0.75', '6.8', '10.25', '23.25', '5.25', '12'],
         name: ['', '', '', '', '', '', ''],
         axis: 'trace 0',
+    }, {
+        desc: 'hoveron points | hovermode closest',
+        patch: function(fig) {
+            fig.data.forEach(function(trace) {
+                trace.boxpoints = 'all';
+                trace.hoveron = 'points';
+            });
+            fig.layout.hovermode = 'closest';
+            return fig;
+        },
+        nums: ['(day 1, 0.7)', '(day 1, 0.6)', '(day 1, 0.6)'],
+        name: ['radishes', 'radishes', 'radishes']
+    }, {
+        desc: 'hoveron points | hovermode x',
+        patch: function(fig) {
+            fig.data.forEach(function(trace) {
+                trace.boxpoints = 'all';
+                trace.hoveron = 'points';
+            });
+            fig.layout.hovermode = 'x';
+            return fig;
+        },
+        nums: ['0', '0.3', '0.5', '0.6', '0.6', '0.7'],
+        name: ['radishes', 'radishes', 'radishes', 'radishes', 'radishes', 'radishes'],
+        axis: 'day 1'
+    }, {
+        desc: 'hoveron boxes+points | hovermode x',
+        patch: function(fig) {
+            fig.data.forEach(function(trace) {
+                trace.boxpoints = 'all';
+                trace.hoveron = 'points+boxes';
+            });
+            fig.layout.hovermode = 'x';
+            return fig;
+        },
+        nums: [
+            '0', '0.7', '0.6', '0.6', '0.5', '0.3', '0', '0.7', '0.6', '0.3', '0.55'
+        ],
+        name: [
+            '', '', '', '', '', '', '', '', '', '', 'radishes'
+        ],
+        axis: 'day 1'
     }].forEach(function(specs) {
         it('should generate correct hover labels ' + specs.desc, function(done) {
             run(specs).catch(fail).then(done);