Violin plots

lib/index-cartesian.js

@@ -19,7 +19,8 @@ Plotly.register([
     require('./histogram2dcontour'),
     require('./pie'),
     require('./contour'),
-    require('./scatterternary')
+    require('./scatterternary'),
+    require('./violin')
 ]);
 
 module.exports = Plotly;

lib/index.js

@@ -21,7 +21,7 @@ Plotly.register([
     require('./pie'),
     require('./contour'),
     require('./scatterternary'),
-    require('./sankey'),
+    require('./violin'),
 
     require('./scatter3d'),
     require('./surface'),
@@ -34,10 +34,13 @@ Plotly.register([
     require('./pointcloud'),
     require('./heatmapgl'),
     require('./parcoords'),
-    require('./table'),
 
     require('./scattermapbox'),
 
+    require('./sankey'),
+
+    require('./table'),
+
     require('./carpet'),
     require('./scattercarpet'),
     require('./contourcarpet'),

lib/violin.js

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

src/plots/cartesian/constants.js

@@ -57,18 +57,13 @@ module.exports = {
     DFLTRANGEX: [-1, 6],
     DFLTRANGEY: [-1, 4],
 
-    // Layers to keep trace types in the right order.
-    // from back to front:
-    // 1. heatmaps, 2D histos and contour maps
-    // 2. bars / 1D histos
-    // 3. errorbars for bars and scatter
-    // 4. scatter
-    // 5. box plots
+    // Layers to keep trace types in the right order
     traceLayerClasses: [
         'imagelayer',
         'maplayer',
         'barlayer',
         'carpetlayer',
+        'violinlayer',
         'boxlayer',
         'scatterlayer'
     ],

src/plots/plots.js

@@ -2160,6 +2160,7 @@ plots.doCalcdata = function(gd, traces) {
 
     // how many box/violins plots do we have (in case they're grouped)
     fullLayout._numBoxes = 0;
+    fullLayout._numViolins = 0;
 
     // for calculating avg luminosity of heatmaps
     gd._hmpixcount = 0;

src/traces/box/plot.js

@@ -161,7 +161,8 @@ function plotPoints(sel, plotinfo, trace, t) {
     var bdPos = t.bdPos;
     var bPos = t.bPos;
 
-    var mode = trace.boxpoints;
+    // TODO ... unfortunately
+    var mode = trace.boxpoints || trace.points;
 
     // repeatable pseudorandom number generator
     seed();

src/traces/box/set_positions.js

@@ -12,13 +12,14 @@ var Registry = require('../../registry');
 var Axes = require('../../plots/cartesian/axes');
 var Lib = require('../../lib');
 
-
 module.exports = function setPositions(gd, plotinfo) {
     var fullLayout = gd._fullLayout;
     var xa = plotinfo.xaxis;
     var ya = plotinfo.yaxis;
     var orientations = ['v', 'h'];
 
+    // TODO figure this out
+    // should violins and boxes share 'num' fields?
     var numKey = '_numBoxes';
 
     var posAxis, i, j, k;
@@ -84,8 +85,10 @@ module.exports = function setPositions(gd, plotinfo) {
             gd.calcdata[boxListIndex][0].t.dPos = dPos;
         }
 
-        var gap = fullLayout.boxgap;
-        var groupgap = fullLayout.boxgroupgap;
+        // TODO this won't work when both boxes and violins are present
+        // on same graph
+        var gap = fullLayout.boxgap || fullLayout.violingap;
+        var groupgap = fullLayout.boxgroupgap || fullLayout.violingroupgap;
 
         // autoscale the x axis - including space for points if they're off the side
         // TODO: this will overdo it if the outermost boxes don't have

src/traces/violin/attributes.js

@@ -0,0 +1,113 @@
+/**
+* Copyright 2012-2017, 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 boxAttrs = require('../box/attributes');
+var scatterAttrs = require('../scatter/attributes');
+var extendFlat = require('../../lib/extend').extendFlat;
+
+module.exports = {
+    y: boxAttrs.y,
+    x: boxAttrs.x,
+    x0: boxAttrs.x0,
+    y0: boxAttrs.y0,
+    name: boxAttrs.name,
+    orientation: extendFlat({}, boxAttrs.orientation, {
+        description: [
+            'Sets the orientation of the violin(s).',
+            'If *v* (*h*), the distribution is visualized along',
+            'the vertical (horizontal).'
+        ].join(' ')
+    }),
+
+    bandwidth: {
+        valType: 'number',
+        min: 0,
+        role: 'info',
+        editType: 'plot',
+        description: [
+            'Sets the bandwidth used to compute the kernel density estimate.',
+            'By default, the bandwidth is determined by Silverman\'s rule of thumb.'
+        ].join(' ')
+    },
+    scaleby: {
+        valType: 'enumerated',
+        values: ['width', 'area', 'count'],
+        dflt: 'width',
+        role: 'info',
+        editType: 'calc',
+        description: [
+            'Sets the method by which the width of each violin is determined.',
+            '*width* means each violin has the same (max) width',
+            '*area* means each violin has the same area',
+            '*count* means the violins are scaled by the number of sample points making',
+            'up each violin.'
+        ].join('')
+    },
+    span: {
+        valType: 'info_array',
+        items: [
+            {valType: 'any', editType: 'plot'},
+            {valType: 'any', editType: 'plot'}
+        ],
+        role: 'info',
+        editType: 'plot',
+        description: [
+            'Sets the span in data space for which the density function will be computed.',
+            'By default, the span goes from the minimum value to maximum value in the sample.'
+        ].join(' ')
+    },
+    side: {
+        valType: 'enumerated',
+        values: ['both', 'left', 'right'],
+        dflt: 'both',
+        role: 'info',
+        editType: 'plot',
+        description: [
+            'Determines which side of the position line the density function making up',
+            'one half of a is plotting.',
+            'Useful when comparing two violin traces under *overlay* mode, where one trace.'
+        ].join(' ')
+    },
+
+    // TODO update description
+    points: boxAttrs.boxpoints,
+    jitter: boxAttrs.jitter,
+    pointpos: boxAttrs.pointpos,
+    marker: boxAttrs.marker,
+    text: boxAttrs.text,
+
+    // TODO need attribute(s) similar to 'boxmean' to toggle lines for:
+    // - mean
+    // - median
+    // - std
+    // - quartiles
+
+    line: {
+        color: {
+            valType: 'color',
+            role: 'style',
+            editType: 'style',
+            description: 'Sets the color of line bounding the violin(s).'
+        },
+        width: {
+            valType: 'number',
+            role: 'style',
+            min: 0,
+            dflt: 2,
+            editType: 'style',
+            description: 'Sets the width (in px) of line bounding the violin(s).'
+        },
+        smoothing: scatterAttrs.line.smoothing,
+        editType: 'plot'
+    },
+
+    fillcolor: boxAttrs.fillcolor,
+    hoveron: boxAttrs.hoveron
+};

src/traces/violin/calc.js

@@ -0,0 +1,75 @@
+/**
+* Copyright 2012-2017, 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 Lib = require('../../lib');
+var boxCalc = require('../box/calc');
+
+var kernels = {
+    gaussian: function(v) {
+        return (1 / Math.sqrt(2 * Math.PI)) * Math.exp(-0.5 * v * v);
+    }
+};
+
+module.exports = function calc(gd, trace) {
+    var cd = boxCalc(gd, trace);
+
+    if(cd[0].t.empty) return cd;
+
+    for(var i = 0; i < cd.length; i++) {
+        var cdi = cd[i];
+        var vals = cdi.pts.map(extractVal);
+        var len = vals.length;
+        var span = trace.span || [cdi.min, cdi.max];
+        var dist = span[1] - span[0];
+        // sample standard deviation
+        var ssd = Lib.stdev(vals, len - 1, cdi.mean);
+        var bandwidthDflt = ruleOfThumbBandwidth(vals, ssd, cdi.q3 - cdi.q1);
+        var bandwidth = trace.bandwidth || bandwidthDflt;
+        var kde = makeKDE(vals, kernels.gaussian, bandwidth);
+        // step that well covers the bandwidth and is multiple of span distance
+        var n = Math.ceil(dist / (Math.min(bandwidthDflt, bandwidth) / 3));
+        var step = dist / n;
+
+        cdi.density = new Array(n);
+        cdi.violinMaxWidth = 0;
+
+        for(var k = 0, t = span[0]; t < (span[1] + step / 2); k++, t += step) {
+            var v = kde(t);
+            cdi.violinMaxWidth = Math.max(cdi.violinMaxWidth, v);
+            cdi.density[k] = {v: v, t: t};
+        }
+    }
+
+    return cd;
+};
+
+// Default to Silveman's rule of thumb:
+// - https://en.wikipedia.org/wiki/Kernel_density_estimation#A_rule-of-thumb_bandwidth_estimator
+// - https://github.com/statsmodels/statsmodels/blob/master/statsmodels/nonparametric/bandwidths.py
+function ruleOfThumbBandwidth(vals, ssd, iqr) {
+    var a = Math.min(ssd, iqr / 1.349);
+    return 1.059 * a * Math.pow(vals.length, -0.2);
+}
+
+function makeKDE(vals, kernel, bandwidth) {
+    var len = vals.length;
+    var factor = 1 / (len * bandwidth);
+
+    // don't use Lib.aggNums to skip isNumeric checks
+    return function(x) {
+        var sum = 0;
+        for(var i = 0; i < len; i++) {
+            sum += kernel((x - vals[i]) / bandwidth);
+        }
+        return factor * sum;
+    };
+}
+
+function extractVal(o) { return o.v; }

src/traces/violin/defaults.js

@@ -0,0 +1,36 @@
+/**
+* Copyright 2012-2017, 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 Lib = require('../../lib');
+var Color = require('../../components/color');
+
+var boxDefaults = require('../box/defaults');
+var attributes = require('./attributes');
+
+module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
+    function coerce(attr, dflt) {
+        return Lib.coerce(traceIn, traceOut, attributes, attr, dflt);
+    }
+
+    boxDefaults.handleSampleDefaults(traceIn, traceOut, coerce, layout);
+    if(traceOut.visible === false) return;
+
+    coerce('bandwidth');
+    coerce('scaleby');
+    coerce('span');
+    coerce('side');
+
+    coerce('line.color', (traceIn.marker || {}).color || defaultColor);
+    coerce('line.width');
+    coerce('line.smoothing');
+    coerce('fillcolor', Color.addOpacity(traceOut.line.color, 0.5));
+
+    boxDefaults.handlePointsDefaults(traceIn, traceOut, coerce, {prefix: ''});
+};

src/traces/violin/index.js

@@ -0,0 +1,40 @@
+/**
+* Copyright 2012-2017, 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 = {
+    attributes: require('./attributes'),
+    layoutAttributes: require('./layout_attributes'),
+    supplyDefaults: require('./defaults'),
+    supplyLayoutDefaults: require('./layout_defaults'),
+    calc: require('./calc'),
+    setPositions: require('../box/set_positions'),
+    plot: require('./plot'),
+    style: require('./style'),
+    hoverPoints: require('../box/hover'),
+    selectPoints: require('../box/select'),
+
+    moduleType: 'trace',
+    name: 'violin',
+    basePlotModule: require('../../plots/cartesian'),
+    // TODO
+    // - should maybe rename 'box' category to something more general
+    categories: ['cartesian', 'symbols', 'oriented', 'box', 'showLegend'],
+    meta: {
+        description: [
+            'In vertical (horizontal) violin plots,',
+            'statistics are computed using `y` (`x`) values.',
+            'By supplying an `x` (`y`) array, one violin per distinct x (y) value',
+            'is drawn',
+            'If no `x` (`y`) {array} is provided, a single violin is drawn.',
+            'That violin position is then positioned with',
+            'with `name` or with `x0` (`y0`) if provided.'
+        ].join(' ')
+    }
+};