Axis category ordering - adds feature #189

src/plot_api/plot_api.js

@@ -854,10 +854,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

@@ -20,7 +20,9 @@ var layoutAttributes = require('./layout_attributes');
 var handleTickValueDefaults = require('./tick_value_defaults');
 var handleTickMarkDefaults = require('./tick_mark_defaults');
 var handleTickLabelDefaults = require('./tick_label_defaults');
+var handleCategoryOrderDefaults = require('./category_order_defaults');
 var setConvert = require('./set_convert');
+var orderedCategories = require('./ordered_categories');
 var cleanDatum = require('./clean_datum');
 var axisIds = require('./axis_ids');
 
@@ -72,6 +74,10 @@ module.exports = function handleAxisDefaults(containerIn, containerOut, coerce,
         }
     }
 
+    containerOut._initialCategories = axType === 'category' ?
+        orderedCategories(letter, containerIn.categoryorder, containerIn.categoryarray, options.data) :
+        [];
+
     setConvert(containerOut);
 
     var dfltColor = coerce('color');
@@ -105,6 +111,7 @@ module.exports = function handleAxisDefaults(containerIn, containerOut, coerce,
     handleTickValueDefaults(containerIn, containerOut, coerce, axType);
     handleTickLabelDefaults(containerIn, containerOut, coerce, axType, options);
     handleTickMarkDefaults(containerIn, containerOut, coerce, options);
+    handleCategoryOrderDefaults(containerIn, containerOut, coerce);
 
     var lineColor = coerce2('linecolor', dfltColor),
         lineWidth = coerce2('linewidth'),

src/plots/cartesian/category_order_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';
+
+var layoutAttributes = require('./layout_attributes');
+
+module.exports = function handleCategoryOrderDefaults(containerIn, containerOut, coerce) {
+
+    if(containerIn.type !== 'category') return;
+
+    var validCategories = layoutAttributes.categoryorder.values;
+
+    var propercategoryarray = Array.isArray(containerIn.categoryarray) && containerIn.categoryarray.length > 0;
+
+    if(validCategories.indexOf(containerIn.categoryorder) === -1 && propercategoryarray) {
+
+        // when unspecified or invalid, use the default, unless categoryarray implies 'array'
+        coerce('categoryorder', 'array'); // promote to 'array'
+
+    } else if(containerIn.categoryorder === 'array' && !propercategoryarray) {
+
+        // when mode is 'array' but no list is given, revert to default
+
+        containerIn.categoryorder = 'trace'; // revert to default
+        coerce('categoryorder');
+
+    } else {
+
+        // otherwise use the supplied mode, or the default one if unsupplied or invalid
+        coerce('categoryorder');
+
+    }
+};

src/plots/cartesian/layout_attributes.js

@@ -465,6 +465,36 @@ module.exports = {
             'Only has an effect if `anchor` is set to *free*.'
         ].join(' ')
     },
+    categoryorder: {
+        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 `categoryorder` to *category ascending* or *category descending* if order should be determined by',
+            'the alphanumerical order of the category names.',
+            /*'Set `categoryorder` 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 `categoryorder` to *array* to derive the ordering from the attribute `categoryarray`. If a category',
+            'is not found in the `categoryarray` array, the sorting behavior for that attribute will be identical to',
+            'the *trace* mode. The unspecified categories will follow the categories in `categoryarray`.'
+        ].join(' ')
+    },
+    categoryarray: {
+        valType: 'data_array',
+        role: 'info',
+        description: [
+            'Sets the order in which categories on this axis appear.',
+            'Only has an effect if `categoryorder` is set to *array*.',
+            'Used with `categoryorder`.'
+        ].join(' ')
+    },
+
 
     _deprecated: {
         autotick: {

src/plots/cartesian/ordered_categories.js

@@ -0,0 +1,77 @@
+/**
+* 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');
+
+// flattenUniqueSort :: String -> Function -> [[String]] -> [String]
+function flattenUniqueSort(axisLetter, sortFunction, data) {
+
+    // Bisection based insertion sort of distinct values for logarithmic time complexity.
+    // Can't use a hashmap, which is O(1), because ES5 maps coerce keys to strings. If it ever becomes a bottleneck,
+    // code can be separated: a hashmap (JS object) based version if all values encountered are strings; and
+    // downgrading to this O(log(n)) array on the first encounter of a non-string value.
+
+    var categoryArray = [];
+
+    var traceLines = data.map(function(d) {return d[axisLetter];});
+
+    var i, j, tracePoints, category, insertionIndex;
+
+    var bisector = d3.bisector(sortFunction).left;
+
+    for(i = 0; i < traceLines.length; i++) {
+
+        tracePoints = traceLines[i];
+
+        for(j = 0; j < tracePoints.length; j++) {
+
+            category = tracePoints[j];
+
+            // skip loop: ignore null and undefined categories
+            if(category === null || category === undefined) continue;
+
+            insertionIndex = bisector(categoryArray, category);
+
+            // skip loop on already encountered values
+            if(insertionIndex < categoryArray.length - 1 && categoryArray[insertionIndex] === category) continue;
+
+            // insert value
+            categoryArray.splice(insertionIndex, 0, category);
+        }
+    }
+
+    return categoryArray;
+}
+
+
+/**
+ * This pure function returns the ordered categories for specified axisLetter, categoryorder, categoryarray and data.
+ *
+ * If categoryorder is 'array', the result is a fresh copy of categoryarray, or if unspecified, an empty array.
+ *
+ * If categoryorder 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 categoryorder and categoryarray
+ *
+ */
+
+// orderedCategories :: String -> String -> [String] -> [[String]] -> [String]
+module.exports = function orderedCategories(axisLetter, categoryorder, categoryarray, data) {
+
+    switch(categoryorder) {
+        case 'array': return Array.isArray(categoryarray) ? categoryarray.slice() : [];
+        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);

src/plots/gl3d/layout/axis_attributes.js

@@ -68,6 +68,8 @@ module.exports = {
         description: 'Sets whether or not this axis is labeled'
     },
     color: axesAttrs.color,
+    categoryorder: axesAttrs.categoryorder,
+    categoryarray: axesAttrs.categoryarray,
     title: axesAttrs.title,
     titlefont: axesAttrs.titlefont,
     type: axesAttrs.type,

test/image/mocks/axes_category_ascending.json

@@ -0,0 +1,13 @@
+{
+    "data": [{
+        "x": ["c","a","e","b","d"],
+        "y": [15,11,12,13,14]}
+    ],
+    "layout": {
+        "xaxis": {
+            "title": "category ascending",
+            "type": "category",
+            "categoryorder": "category ascending",
+            "categoryarray": ["y","b","x","a","d","z","e","c", "q", "k"]
+        }}
+}

test/image/mocks/axes_category_categoryarray.json

@@ -0,0 +1,46 @@
+{
+    "data": [
+        {
+            "x": [
+                1,
+                2,
+                null,
+                4,
+                5
+            ],
+            "y": [
+                1,
+                2,
+                3,
+                4,
+                5
+            ],
+            "connectgaps": false,
+            "uid": "8ac13a"
+        }
+    ],
+    "layout": {
+        "title": "categoryarray",
+        "xaxis": {
+            "type": "category",
+            "range": [
+                -0.18336673346693386,
+                3.1833667334669338
+            ],
+            "autorange": true,
+            "categoryorder": "array",
+            "categoryarray": [2,4,5,1]
+        },
+        "yaxis": {
+            "type": "linear",
+            "range": [
+                0.7070063694267517,
+                5.292993630573249
+            ],
+            "autorange": true
+        },
+        "height": 450,
+        "width": 1000,
+        "autosize": true
+    }
+}

test/image/mocks/axes_category_categoryarray_truncated_tails.json

@@ -0,0 +1,13 @@
+{
+    "data": [{
+        "x": ["c","a","e","b","d"],
+        "y": [15,11,12,13,14]}
+    ],
+    "layout": {
+        "title": "categoryarray with truncated tails (y, q, k not plotted)",
+        "xaxis": {
+            "type": "category",
+            "categoryorder": "array",
+            "categoryarray": ["y","b","x","a","d","z","e","c", "q", "k"]
+        }}
+}

test/image/mocks/axes_category_descending.json

@@ -0,0 +1,41 @@
+{
+    "data": [
+        {
+            "x": [
+                5,
+                1,
+                3,
+                2,
+                4
+            ],
+            "y": [
+                1,
+                2,
+                3,
+                4,
+                5
+            ],
+            "connectgaps": false,
+            "uid": "8ac13a"
+        }
+    ],
+    "layout": {
+        "title": "category descending",
+        "xaxis": {
+            "type": "category",
+            "categoryorder": "category descending",
+            "categoryarray": [2,4,5,1]
+        },
+        "yaxis": {
+            "type": "linear",
+            "range": [
+                0.7070063694267517,
+                5.292993630573249
+            ],
+            "autorange": true
+        },
+        "height": 450,
+        "width": 1000,
+        "autosize": true
+    }
+}

test/image/mocks/axes_category_descending_with_gaps.json

@@ -0,0 +1,41 @@
+{
+    "data": [
+        {
+            "x": [
+                5,
+                null,
+                3,
+                2,
+                4
+            ],
+            "y": [
+                1,
+                2,
+                3,
+                null,
+                5
+            ],
+            "connectgaps": false,
+            "uid": "8ac13a"
+        }
+    ],
+    "layout": {
+        "title": "category descending",
+        "xaxis": {
+            "type": "category",
+            "categoryorder": "category descending",
+            "categoryarray": [2,4,5,1]
+        },
+        "yaxis": {
+            "type": "linear",
+            "range": [
+                0.7070063694267517,
+                5.292993630573249
+            ],
+            "autorange": true
+        },
+        "height": 450,
+        "width": 1000,
+        "autosize": true
+    }
+}