Parallel Categories trace type for multi dimensional categorical data

lib/index.js

@@ -38,7 +38,7 @@ Plotly.register([
     require('./pointcloud'),
     require('./heatmapgl'),
     require('./parcoords'),
-
+    require('./parcats'),
     require('./scattermapbox'),
 
     require('./sankey'),

lib/parcats.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/parcats');

src/components/fx/hover.js

@@ -153,6 +153,82 @@ exports.loneHover = function loneHover(hoverItem, opts) {
     return hoverLabel.node();
 };
 
+// TODO: replace loneHover?
+exports.customHovers = function customHovers(hoverItems, opts) {
+
+    if(!Array.isArray(hoverItems)) {
+        hoverItems = [hoverItems];
+    }
+
+    var pointsData = hoverItems.map(function(hoverItem) {
+        return {
+            color: hoverItem.color || Color.defaultLine,
+            x0: hoverItem.x0 || hoverItem.x || 0,
+            x1: hoverItem.x1 || hoverItem.x || 0,
+            y0: hoverItem.y0 || hoverItem.y || 0,
+            y1: hoverItem.y1 || hoverItem.y || 0,
+            xLabel: hoverItem.xLabel,
+            yLabel: hoverItem.yLabel,
+            zLabel: hoverItem.zLabel,
+            text: hoverItem.text,
+            name: hoverItem.name,
+            idealAlign: hoverItem.idealAlign,
+
+            // optional extra bits of styling
+            borderColor: hoverItem.borderColor,
+            fontFamily: hoverItem.fontFamily,
+            fontSize: hoverItem.fontSize,
+            fontColor: hoverItem.fontColor,
+
+            // filler to make createHoverText happy
+            trace: {
+                index: 0,
+                hoverinfo: ''
+            },
+            xa: {_offset: 0},
+            ya: {_offset: 0},
+            index: 0
+        };
+    });
+
+
+    var container3 = d3.select(opts.container),
+        outerContainer3 = opts.outerContainer ?
+            d3.select(opts.outerContainer) : container3;
+
+    var fullOpts = {
+        hovermode: 'closest',
+        rotateLabels: false,
+        bgColor: opts.bgColor || Color.background,
+        container: container3,
+        outerContainer: outerContainer3
+    };
+
+    var hoverLabel = createHoverText(pointsData, fullOpts, opts.gd);
+
+    // Fix vertical overlap
+    var tooltipSpacing = 5;
+    var lastBottomY = 0;
+    hoverLabel
+        .sort(function(a, b) {return a.y0 - b.y0;})
+        .each(function(d) {
+            var topY = d.y0 - d.by / 2;
+
+            if((topY - tooltipSpacing) < lastBottomY) {
+                d.offset = (lastBottomY - topY) + tooltipSpacing;
+            } else {
+                d.offset = 0;
+            }
+
+            lastBottomY = topY + d.by + d.offset;
+        });
+
+
+    alignHoverText(hoverLabel, fullOpts.rotateLabels);
+
+    return hoverLabel.node();
+};
+
 // The actual implementation is here:
 function _hover(gd, evt, subplot, noHoverEvent) {
     if(!subplot) subplot = 'xy';

src/components/fx/index.js

@@ -45,6 +45,7 @@ module.exports = {
     unhover: dragElement.unhover,
 
     loneHover: require('./hover').loneHover,
+    customHovers: require('./hover').customHovers,
     loneUnhover: loneUnhover,
 
     click: require('./click')

src/traces/parcats/attributes.js

@@ -0,0 +1,152 @@
+/**
+* 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 extendFlat = require('../../lib/extend').extendFlat;
+var colorAttributes = require('../../components/colorscale/attributes');
+var domainAttrs = require('../../plots/domain').attributes;
+var scatterAttrs = require('../scatter/attributes');
+var scatterLineAttrs = scatterAttrs.line;
+var colorbarAttrs = require('../../components/colorbar/attributes');
+
+var line = extendFlat({
+    editType: 'calc'
+}, colorAttributes('line', {editType: 'calc'}),
+    {
+        showscale: scatterLineAttrs.showscale,
+        colorbar: colorbarAttrs,
+        shape: {
+            valType: 'enumerated',
+            values: ['linear', 'hspline'],
+            dflt: 'linear',
+            role: 'info',
+            editType: 'plot',
+            description: 'Sets the shape of the paths'},
+    });
+
+module.exports = {
+    domain: domainAttrs({name: 'parcats', trace: true, editType: 'calc'}),
+
+    tooltip: {
+        valType: 'boolean',
+        dflt: true,
+        role: 'info',
+        editType: 'plot',
+        description: 'Shows a tooltip when hover mode is `category` or `color`.'
+    },
+
+    hovermode: {
+        valType: 'enumerated',
+        values: ['none', 'category', 'color'],
+        dflt: 'category',
+        role: 'info',
+        editType: 'plot',
+        description: 'Sets the hover mode of the parcats diagram'
+    },
+    bundlecolors: {
+        valType: 'boolean',
+        dflt: true,
+        role: 'info',
+        editType: 'plot',
+        description: 'Sort paths so that like colors are bundled together'
+    },
+    sortpaths: {
+        valType: 'enumerated',
+        values: ['forward', 'backward'],
+        dflt: 'forward',
+        role: 'info',
+        editType: 'plot',
+        description: [
+            'If `forward` then sort paths based on dimensions from left to right.',
+            'If `backward` sort based on dimensions from right to left.'
+        ].join(' ')
+    },
+    // labelfont: fontAttrs({
+    //     editType: 'calc',
+    //     description: 'Sets the font for the `dimension` labels.'
+    // }),
+    //
+    // catfont: fontAttrs({
+    //     editType: 'calc',
+    //     description: 'Sets the font for the `category` labels.'
+    // }),
+
+    dimensions: {
+        _isLinkedToArray: 'dimension',
+        label: {
+            valType: 'string',
+            role: 'info',
+            editType: 'calc',
+            description: 'The shown name of the dimension.'
+        },
+        catDisplayInds: {
+            valType: 'data_array',
+            role: 'info',
+            editType: 'calc',
+            dflt: [],
+            description: [
+                ''
+            ].join(' ')
+        },
+        catValues: {
+            valType: 'data_array',
+            role: 'info',
+            editType: 'calc',
+            dflt: [],
+            description: [
+                ''
+            ].join(' ')
+        },
+        catLabels: {
+            valType: 'data_array',
+            role: 'info',
+            editType: 'calc',
+            dflt: [],
+            description: [
+                ''
+            ].join(' ')
+        },
+        values: {
+            valType: 'data_array',
+            role: 'info',
+            dflt: [],
+            editType: 'calc',
+            description: [
+                'Dimension values. `values[n]` represents the category value of the `n`th point in the dataset,',
+                'therefore the `values` vector for all dimensions must be the same (longer vectors',
+                'will be truncated). Each value must an element of `catValues`.'
+            ].join(' ')
+        },
+        displayindex: {
+            valType: 'integer',
+            role: 'info',
+            editType: 'calc',
+            description: [
+                'The display index of dimension, from left to right, zero indexed, defaults to dimension' +
+                'index.'
+            ].join(' ')
+        },
+        editType: 'calc',
+        description: 'The dimensions (variables) of the parallel categories diagram.'
+    },
+
+    line: line,
+    counts: {
+        valType: 'number',
+        min: 0,
+        dflt: 1,
+        arrayOk: true,
+        role: 'info',
+        editType: 'calc',
+        description: [
+            'The number of observations represented by each state. Defaults to 1 so that each state represents ' +
+                'one observation'
+        ]
+    }
+};

src/traces/parcats/base_plot.js

@@ -0,0 +1,34 @@
+/**
+* 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 getModuleCalcData = require('../../plots/get_data').getModuleCalcData;
+var parcatsPlot = require('./plot');
+
+var PARCATS = 'parcats';
+exports.name = PARCATS;
+
+exports.plot = function(gd, traces, transitionOpts, makeOnCompleteCallback) {
+
+    var cdModuleAndOthers = getModuleCalcData(gd.calcdata, PARCATS);
+
+    if(cdModuleAndOthers.length) {
+        var calcData = cdModuleAndOthers[0];
+        parcatsPlot(gd, calcData, transitionOpts, makeOnCompleteCallback);
+    }
+};
+
+exports.clean = function(newFullData, newFullLayout, oldFullData, oldFullLayout) {
+    var hadTable = (oldFullLayout._has && oldFullLayout._has('parcats'));
+    var hasTable = (newFullLayout._has && newFullLayout._has('parcats'));
+
+    if(hadTable && !hasTable) {
+        oldFullLayout._paperdiv.selectAll('.parcats').remove();
+    }
+};