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

@@ -17,7 +17,9 @@ var Plots = require('../plots');
 var layoutAttributes = require('./layout_attributes');
 var handleTickValueDefaults = require('./tick_value_defaults');
 var handleTickDefaults = require('./tick_defaults');
+var handleCategoryModeDefaults = require('./category_mode_defaults');
 var setConvert = require('./set_convert');
+var orderedCategories = require('./ordered_categories');
 var cleanDatum = require('./clean_datum');
 var axisIds = require('./axis_ids');
 
@@ -64,6 +66,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);
@@ -91,6 +97,7 @@ module.exports = function handleAxisDefaults(containerIn, containerOut, coerce,
 
     handleTickValueDefaults(containerIn, containerOut, coerce, axType);
     handleTickDefaults(containerIn, containerOut, coerce, axType, options);
+    handleCategoryModeDefaults(containerIn, containerOut, coerce);
 
     var lineColor = Lib.coerce2(containerIn, containerOut, layoutAttributes, 'linecolor'),
         lineWidth = Lib.coerce2(containerIn, containerOut, layoutAttributes, 'linewidth'),

src/plots/cartesian/category_mode_defaults.js

@@ -0,0 +1,39 @@
+/**
+* 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';
+
+module.exports = function handleCategoryModeDefaults(containerIn, containerOut, coerce) {
+
+    if(containerIn.type === 'category') {
+
+        var validCategories = ['trace', 'category ascending', 'category descending', 'array'];
+
+        var properCategoryList = Array.isArray(containerIn.categorylist) && containerIn.categorylist.length > 0;
+
+        if(validCategories.indexOf(containerIn.categorymode) === -1 && properCategoryList) {
+
+            // when unspecified or invalid, use the default, unless categorylist implies 'array'
+            coerce('categorymode', 'array'); // promote to 'array
+
+        } else if(containerIn.categorymode === 'array' && !properCategoryList) {
+
+            // when mode is 'array' but no list is given, revert to default
+
+            containerIn.categorymode = 'trace'; // revert to default
+            coerce('categorymode');
+
+        } else {
+
+            // otherwise use the supplied mode, or the default one if unsupplied or invalid
+            coerce('categorymode');
+
+        }
+    }
+};

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', 'array'
+            /*, 'value ascending', 'value descending'*/ // value ascending / descending to be implemented later
+        ],
+        dflt: 'trace',
+        role: 'info',
+        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.',*/ // // value ascending / descending to be implemented later
+            '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: 'info',
+        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,59 @@
+/**
+* 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');
+
+// flattenUnique :: String -> [[String]] -> Object
+function flattenUnique(axisLetter, data) {
+    var traceLines = data.map(function(d) {return d[axisLetter];});
+    var categoryMap = {}; // hashmap is O(1);
+    var i, j, tracePoints, category;
+    for(i = 0; i < traceLines.length; i++) {
+        tracePoints = traceLines[i];
+        for(j = 0; j < tracePoints.length; j++) {
+            category = tracePoints[j];
+            if(!categoryMap[category]) {
+                categoryMap[category] = true;
+            }
+        }
+    }
+    return categoryMap;
+}
+
+// flattenUniqueSort :: String -> Function -> [[String]] -> [String]
+function flattenUniqueSort(axisLetter, sortFunction, data) {
+    return Object.keys(flattenUnique(axisLetter, data)).sort(sortFunction);
+}
+
+
+/**
+ * This pure function returns the ordered categories for specified axisLetter, categorymode, categorylist and data.
+ *
+ * If categorymode is 'array', the result is a fresh copy of categorylist, or if unspecified, an empty array.
+ *
+ * If categorymode is 'category ascending' or 'category descending', the result is an array of ascending or descending
+ * order of the unique categories encountered in the data for specified axisLetter.
+ *
+ * See cartesian/layout_attributes.js for the definition of categorymode and categorylist
+ *
+ */
+
+// orderedCategories :: String -> String -> [String] -> [[String]] -> [String]
+module.exports = function orderedCategories(axisLetter, categorymode, categorylist, data) {
+
+    switch(categorymode) {
+        case 'array': return Array.isArray(categorylist) ? categorylist : [];
+        case 'category ascending': return flattenUniqueSort(axisLetter, d3.ascending, data);
+        case 'category descending': return flattenUniqueSort(axisLetter, d3.descending, data);
+        case 'trace': return [];
+        default: return [];
+    }
+};

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/axes_test.js

@@ -7,8 +7,8 @@ var Color = require('@src/components/color');
 var handleTickValueDefaults = require('@src/plots/cartesian/tick_value_defaults');
 var Axes = PlotlyInternal.Axes;
 
-var createGraph = require('../assets/create_graph_div');
-var destroyGraph = require('../assets/destroy_graph_div');
+var createGraphDiv = require('../assets/create_graph_div');
+var destroyGraphDiv = require('../assets/destroy_graph_div');
 
 
 describe('Test axes', function() {
@@ -321,15 +321,137 @@ describe('Test axes', function() {
         });
     });
 
+    describe('categorymode', function() {
+
+        var gd;
+
+        beforeEach(function() {
+            gd = createGraphDiv();
+        });
+
+        afterEach(destroyGraphDiv);
+
+        describe('setting, or not setting categorymode if it is not explicitly declared', function() {
+
+            it('should set categorymode to default if categorymode and categorylist are not supplied', function() {
+                PlotlyInternal.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], {xaxis: {type: 'category'}});
+                expect(gd._fullLayout.xaxis.categorymode).toBe('trace');
+            });
+
+            it('should set categorymode to default even if type is not set to category explicitly', function() {
+                PlotlyInternal.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}]);
+                expect(gd._fullLayout.xaxis.categorymode).toBe('trace');
+            });
+
+            it('should NOT set categorymode to default if type is not category', function() {
+                PlotlyInternal.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}]);
+                expect(gd._fullLayout.yaxis.categorymode).toBe(undefined);
+            });
+
+            it('should set categorymode to default if type is overridden to be category', function() {
+                PlotlyInternal.plot(gd, [{x: [1,2,3,4,5], y: [15,11,12,13,14]}], {yaxis: {type: 'category'}});
+                expect(gd._fullLayout.xaxis.categorymode).toBe(undefined);
+                expect(gd._fullLayout.yaxis.categorymode).toBe('trace');
+            });
+
+        });
+
+        describe('setting categorymode to "array"', function() {
+
+            it('should leave categorymode on "array" if it is supplied', function() {
+                PlotlyInternal.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._fullLayout.xaxis.categorymode).toBe('array');
+            });
+
+            it('should switch categorymode on "array" if it is not supplied but categorylist is supplied', function() {
+                PlotlyInternal.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], {
+                    xaxis: {type: 'category', categorylist: ['b','a','d','e','c']}
+                });
+                expect(gd._fullLayout.xaxis.categorymode).toBe('array');
+            });
+
+            it('should revert categorymode to "trace" if "array" is supplied but there is no list', function() {
+                PlotlyInternal.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], {
+                    xaxis: {type: 'category', categorymode: 'array'}
+                });
+                expect(gd._fullLayout.xaxis.categorymode).toBe('trace');
+            });
+
+        });
+
+        describe('do not set categorymode to "array" if list exists but empty', function() {
+
+            it('should switch categorymode to default if list is not supplied', function() {
+                PlotlyInternal.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], {
+                    xaxis: {type: 'category', categorymode: 'array', categorylist: []}
+                });
+                expect(gd._fullLayout.xaxis.categorymode).toBe('trace');
+            });
+
+            it('should not switch categorymode on "array" if categorylist is supplied but empty', function() {
+                PlotlyInternal.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], {
+                    xaxis: {type: 'category', categorylist: []}
+                });
+                expect(gd._fullLayout.xaxis.categorymode).toBe('trace');
+            });
+        });
+
+        describe('do NOT set categorymode to "array" if it has some other proper value', function() {
+
+            it('should use specified categorymode if it is supplied even if categorylist exists', function() {
+                PlotlyInternal.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], {
+                    xaxis: {type: 'category', categorymode: 'trace', categorylist: ['b','a','d','e','c']}
+                });
+                expect(gd._fullLayout.xaxis.categorymode).toBe('trace');
+            });
+
+            it('should use specified categorymode if it is supplied even if categorylist exists', function() {
+                PlotlyInternal.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']}
+                });
+                expect(gd._fullLayout.xaxis.categorymode).toBe('category ascending');
+            });
+
+            it('should use specified categorymode if it is supplied even if categorylist exists', function() {
+                PlotlyInternal.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], {
+                    xaxis: {type: 'category', categorymode: 'category descending', categorylist: ['b','a','d','e','c']}
+                });
+                expect(gd._fullLayout.xaxis.categorymode).toBe('category descending');
+            });
+
+        });
+
+        describe('setting categorymode to the default if the value is unexpected', function() {
+
+            it('should switch categorymode to "trace" if mode is supplied but invalid', function() {
+                PlotlyInternal.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], {
+                    xaxis: {type: 'category', categorymode: 'invalid value'}
+                });
+                expect(gd._fullLayout.xaxis.categorymode).toBe('trace');
+            });
+
+            it('should switch categorymode to "array" if mode is supplied but invalid and list is supplied', function() {
+                PlotlyInternal.plot(gd, [{x: ['c','a','e','b','d'], y: [15,11,12,13,14]}], {
+                    xaxis: {type: 'category', categorymode: 'invalid value', categorylist: ['b','a','d','e','c']}
+                });
+                expect(gd._fullLayout.xaxis.categorymode).toBe('array');
+            });
+
+        });
+
+    });
+
     describe('handleTickDefaults', function() {
         var data = [{ x: [1,2,3], y: [3,4,5] }],
             gd;
 
         beforeEach(function() {
-            gd = createGraph();
+            gd = createGraphDiv();
         });
 
-        afterEach(destroyGraph);
+        afterEach(destroyGraphDiv);
 
         it('should set defaults on bad inputs', function() {
             var layout = {