189 ordinal scale domain item ordering

src/plot_api/plot_api.js

@@ -851,10 +851,10 @@ function doCalcdata(gd) {
     fullLayout._piecolormap = {};
     fullLayout._piedefaultcolorcount = 0;
 
-    // delete category list, if there is one, so we start over
+    // initialize the category list, if there is one, so we start over
     // to be filled in later by ax.d2c
     for(i = 0; i < axList.length; i++) {
-        axList[i]._categories = [];
+        axList[i]._categories = axList[i]._initialCategories.slice();
     }
 
     for(i = 0; i < fullData.length; i++) {

src/plots/cartesian/axis_defaults.js

@@ -18,6 +18,7 @@ var layoutAttributes = require('./layout_attributes');
 var handleTickValueDefaults = require('./tick_value_defaults');
 var handleTickDefaults = require('./tick_defaults');
 var setConvert = require('./set_convert');
+var orderedCategories = require('./ordered_categories');
 var cleanDatum = require('./clean_datum');
 var axisIds = require('./axis_ids');
 
@@ -64,6 +65,10 @@ module.exports = function handleAxisDefaults(containerIn, containerOut, coerce,
         }
     }
 
+    containerOut._initialCategories = axType === 'category' ?
+        orderedCategories(letter, containerIn.categorymode, containerIn.categorylist, options.data) :
+        [];
+
     setConvert(containerOut);
 
     coerce('title', defaultTitle);

src/plots/cartesian/layout_attributes.js

@@ -446,6 +446,36 @@ module.exports = {
             'Only has an effect if `anchor` is set to *free*.'
         ].join(' ')
     },
+    categorymode: {
+        valType: 'enumerated',
+        values: [
+            'trace', 'category ascending', 'category descending',
+            'value ascending', 'value descending','array'
+        ],
+        dflt: 'trace',
+        role: 'style',
+        description: [
+            'Specifies the ordering logic for the case of categorical variables.',
+            'By default, plotly uses *trace*, which specifies the order that is present in the data supplied.',
+            'Set `categorymode` to *category ascending* or *category descending* if order should be determined by',
+            'the alphanumerical order of the category names.',
+            'Set `categorymode` to *value ascending* or *value descending* if order should be determined by the',
+            'numerical order of the values.',
+            'Set `categorymode` to *array* to derive the ordering from the attribute `categorylist`. If a category',
+            'is not found in the `categorylist` array, the sorting behavior for that attribute will be identical to',
+            'the *trace* mode. The unspecified categories will follow the categories in `categorylist`.'
+        ].join(' ')
+    },
+    categorylist: {
+        valType: 'data_array',
+        role: 'style',
+        description: [
+            'Sets the order in which categories on this axis appear.',
+            'Only has an effect if `categorymode` is set to *array*.',
+            'Used with `categorymode`.'
+        ].join(' ')
+    },
+
 
     _deprecated: {
         autotick: {

src/plots/cartesian/ordered_categories.js

@@ -0,0 +1,33 @@
+/**
+* Copyright 2012-2016, 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 d3 = require('d3');
+
+
+/**
+ * TODO add documentation
+ */
+module.exports = function orderedCategories(axisLetter, categorymode, categorylist, data) {
+
+    return categorymode === 'array' ?
+
+        // just return a copy of the specified array ...
+        categorylist.slice() :
+
+        // ... or take the union of all encountered tick keys and sort them as specified
+        // (could be simplified with lodash-fp or ramda)
+        [].concat.apply([], data.map(function(d) {return d[axisLetter];}))
+            .filter(function(element, index, array) {return index === array.indexOf(element);})
+            .sort(({
+                'category ascending': d3.ascending,
+                'category descending': d3.descending
+            })[categorymode]);
+};

src/plots/cartesian/set_convert.js

@@ -182,8 +182,9 @@ module.exports = function setConvert(ax) {
             // encounters them, ie all the categories from the
             // first data set, then all the ones from the second
             // that aren't in the first etc.
-            // TODO: sorting options - do the sorting
-            // progressively here as we insert?
+            // it is assumed that this function is being invoked in the
+            // already sorted category order; otherwise there would be
+            // a disconnect between the array and the index returned
 
             if(v !== null && v !== undefined && ax._categories.indexOf(v) === -1) {
                 ax._categories.push(v);

test/jasmine/tests/calcdata_test.js

@@ -4,15 +4,16 @@ var createGraphDiv = require('../assets/create_graph_div');
 var destroyGraphDiv = require('../assets/destroy_graph_div');
 
 describe('calculated data and points', function() {
-    describe('connectGaps', function() {
 
-        var gd;
+    var gd;
 
-        beforeEach(function() {
-            gd = createGraphDiv();
-        });
+    beforeEach(function() {
+        gd = createGraphDiv();
+    });
 
-        afterEach(destroyGraphDiv);
+    afterEach(destroyGraphDiv);
+
+    describe('connectGaps', function() {
 
         it('should exclude null and undefined points when false', function() {
             Plotly.plot(gd, [{ x: [1,2,3,undefined,5], y: [1,null,3,4,5]}], {});
@@ -28,4 +29,215 @@ describe('calculated data and points', function() {
             expect(gd.calcdata[0][3]).toEqual({ x: false, y: false});
         });
     });
+
+    xdescribe('category ordering', function() {
+
+        describe('default category ordering reified', function() {
+
+            it('should output categories in the given order by default', function() {
+
+                Plotly.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], { xaxis: {
+                    type: 'category'
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(15);
+                expect(gd.calcdata[0][1].y).toEqual(11);
+                expect(gd.calcdata[0][2].y).toEqual(12);
+                expect(gd.calcdata[0][3].y).toEqual(13);
+                expect(gd.calcdata[0][4].y).toEqual(14);
+            });
+
+            it('should output categories in the given order if `trace` order is explicitly specified', function() {
+
+                Plotly.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], { xaxis: {
+                    type: 'category',
+                    categorymode: 'trace'
+                    // Wouldn't it be preferred to supply a function and plotly would have several functions like this?
+                    // E.g. it's easier for symbol completion (whereas there's no symbol completion on string config)
+                    // See arguments from Mike Bostock, highlighted in medium green here:
+                    // https://medium.com/@mbostock/what-makes-software-good-943557f8a488#eef9
+                    // Plus if it's a function, then users can roll their own.
+                    //
+                    // Also, if axis tick order is made configurable, shouldn't we make trace order configurable?
+                    // Trace order as in, if a line or curve is drawn through points, what's the trace sequence.
+                    // These are two orthogonal concepts. In this round, I'm assuming that the trace order is implied
+                    // by the order the {x,y} arrays are specified.
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(15);
+                expect(gd.calcdata[0][1].y).toEqual(11);
+                expect(gd.calcdata[0][2].y).toEqual(12);
+                expect(gd.calcdata[0][3].y).toEqual(13);
+                expect(gd.calcdata[0][4].y).toEqual(14);
+            });
+        });
+
+        describe('domain alphanumerical category ordering', function() {
+
+            it('should output categories in ascending domain alphanumerical order', function() {
+
+                Plotly.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], { xaxis: {
+                    type: 'category',
+                    categorymode: 'category ascending'
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(11);
+                expect(gd.calcdata[0][1].y).toEqual(13);
+                expect(gd.calcdata[0][2].y).toEqual(15);
+                expect(gd.calcdata[0][3].y).toEqual(14);
+                expect(gd.calcdata[0][4].y).toEqual(12);
+            });
+
+            it('should output categories in descending domain alphanumerical order', function() {
+
+                Plotly.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], { xaxis: {
+                    type: 'category',
+                    categorymode: 'category descending'
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(12);
+                expect(gd.calcdata[0][1].y).toEqual(14);
+                expect(gd.calcdata[0][2].y).toEqual(15);
+                expect(gd.calcdata[0][3].y).toEqual(13);
+                expect(gd.calcdata[0][4].y).toEqual(11);
+            });
+
+            it('should output categories in categorymode order even if category array is defined', function() {
+
+                Plotly.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], { xaxis: {
+                    type: 'category',
+                    categorymode: 'category ascending',
+                    categorylist: ['b','a','d','e','c'] // These must be ignored. Alternative: error?
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(11);
+                expect(gd.calcdata[0][1].y).toEqual(13);
+                expect(gd.calcdata[0][2].y).toEqual(15);
+                expect(gd.calcdata[0][3].y).toEqual(14);
+                expect(gd.calcdata[0][4].y).toEqual(12);
+            });
+
+            it('should output categories in ascending domain alphanumerical order, excluding undefined', function() {
+
+                Plotly.plot(gd, [{x: ['c',undefined,'e','b','d'], y: [15,11,12,13,14]}], { xaxis: {
+                    type: 'category',
+                    categorymode: 'category ascending'
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(11);
+                expect(gd.calcdata[0][1].y).toEqual(15);
+                expect(gd.calcdata[0][2].y).toEqual(14);
+                expect(gd.calcdata[0][3].y).toEqual(12);
+            });
+        });
+
+        describe('codomain numerical category ordering', function() {
+
+            it('should output categories in ascending codomain numerical order', function() {
+
+                Plotly.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], { xaxis: {
+                    type: 'category',
+                    categorymode: 'value ascending'
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(11);
+                expect(gd.calcdata[0][1].y).toEqual(12);
+                expect(gd.calcdata[0][2].y).toEqual(13);
+                expect(gd.calcdata[0][3].y).toEqual(14);
+                expect(gd.calcdata[0][4].y).toEqual(15);
+            });
+
+            it('should output categories in descending codomain numerical order', function() {
+
+                Plotly.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], { xaxis: {
+                    type: 'category',
+                    categorymode: 'value descending'
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(15);
+                expect(gd.calcdata[0][1].y).toEqual(14);
+                expect(gd.calcdata[0][2].y).toEqual(13);
+                expect(gd.calcdata[0][3].y).toEqual(12);
+                expect(gd.calcdata[0][4].y).toEqual(11);
+            });
+
+            it('should output categories in descending codomain numerical order, excluding nulls', function() {
+
+                Plotly.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,null,13,14]}], { xaxis: {
+                    type: 'category',
+                    categorymode: 'value descending'
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(15);
+                expect(gd.calcdata[0][1].y).toEqual(14);
+                expect(gd.calcdata[0][2].y).toEqual(12);
+                expect(gd.calcdata[0][3].y).toEqual(11);
+
+            });
+        });
+
+        describe('explicit category ordering', function() {
+
+            it('should output categories in explicitly supplied order, independent of trace order', function() {
+
+                Plotly.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], { xaxis: {
+                    type: 'category',
+                    categorymode: 'array',
+                    categorylist: ['b','a','d','e','c']
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(13);
+                expect(gd.calcdata[0][1].y).toEqual(11);
+                expect(gd.calcdata[0][2].y).toEqual(14);
+                expect(gd.calcdata[0][3].y).toEqual(12);
+                expect(gd.calcdata[0][4].y).toEqual(15);
+            });
+
+            it('should output categories in explicitly supplied order, independent of trace order, pruned', function() {
+
+                Plotly.plot(gd, [{x: ['c',undefined,'e','b','d'], y: [15,11,12,null,14]}], { xaxis: {
+                    type: 'category',
+                    categorymode: 'array',
+                    categorylist: ['b','a','d','e','c']
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(13);
+                expect(gd.calcdata[0][1].y).toEqual(14);
+                expect(gd.calcdata[0][2].y).toEqual(15);
+            });
+
+            it('should output categories in explicitly supplied order even if not all categories are present', function() {
+
+                Plotly.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], { xaxis: {
+                    type: 'category',
+                    categorymode: 'array',
+                    categorylist: ['y','b','x','a','d','z','e','c']
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(13);
+                expect(gd.calcdata[0][1].y).toEqual(11);
+                expect(gd.calcdata[0][2].y).toEqual(14);
+                expect(gd.calcdata[0][3].y).toEqual(12);
+                expect(gd.calcdata[0][4].y).toEqual(15);
+            });
+
+            it('should output categories in explicitly supplied order first, if not all categories are covered', function() {
+
+                Plotly.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], { xaxis: {
+                    type: 'category',
+                    categorymode: 'array',
+                    categorylist: ['b','a','x','c']
+                }});
+
+                expect(gd.calcdata[0][0].y).toEqual(13);
+                expect(gd.calcdata[0][1].y).toEqual(11);
+                expect(gd.calcdata[0][2].y).toEqual(15);
+
+                // The order of the rest is unspecified, no need to check. Alternative: make _both_ categorymode and
+                // categories effective; categories would take precedence and the remaining items would be sorted
+                // based on the categorymode. This of course means that the mere presence of categories triggers this
+                // behavior, rather than an explicit 'explicit' categorymode.
+            });
+        });
+    });
 });