sort categorical Cartesian axes by value

src/plot_api/plot_schema.js

@@ -503,6 +503,8 @@ function getTraceAttributes(type) {
 
     var out = {
         meta: _module.meta || {},
+        categories: _module.categories || {},
+        type: type,
         attributes: formatAttributes(attributes),
     };
 

src/plots/cartesian/layout_attributes.js

@@ -817,8 +817,13 @@ module.exports = {
     categoryorder: {
         valType: 'enumerated',
         values: [
-            'trace', 'category ascending', 'category descending', 'array'
-            /* , 'value ascending', 'value descending'*/ // value ascending / descending to be implemented later
+            'trace', 'category ascending', 'category descending', 'array',
+            'value ascending', 'value descending',
+            'min ascending', 'min descending',
+            'max ascending', 'max descending',
+            'sum ascending', 'sum descending',
+            'mean ascending', 'mean descending',
+            'median ascending', 'median descending'
         ],
         dflt: 'trace',
         role: 'info',
@@ -828,11 +833,12 @@ module.exports = {
             '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`.'
+            'the *trace* mode. The unspecified categories will follow the categories in `categoryarray`.',
+            'Set `categoryorder` to *value ascending* or *value descending* if order should be determined by the',
+            'numerical order of the values.',
+            'Similarly, the order can be determined by the min, max, sum, mean or media of all the values.'
         ].join(' ')
     },
     categoryarray: {

src/plots/cartesian/set_convert.js

@@ -612,6 +612,37 @@ module.exports = function setConvert(ax, fullLayout) {
         }
     };
 
+    // sort the axis (and all the matching ones) by _initialCategories
+    // returns the indices of the traces affected by the reordering
+    ax.sortByInitialCategories = function() {
+        var affectedTraces = [];
+        var emptyCategories = function() {
+            ax._categories = [];
+            ax._categoriesMap = {};
+        };
+
+        emptyCategories();
+
+        if(ax._initialCategories) {
+            for(var j = 0; j < ax._initialCategories.length; j++) {
+                setCategoryIndex(ax._initialCategories[j]);
+            }
+        }
+
+        affectedTraces = affectedTraces.concat(ax._traceIndices);
+
+        // Propagate to matching axes
+        var group = ax._matchGroup;
+        for(var axId2 in group) {
+            if(axId === axId2) continue;
+            var ax2 = fullLayout[axisIds.id2name(axId2)];
+            ax2._categories = ax._categories;
+            ax2._categoriesMap = ax._categoriesMap;
+            affectedTraces = affectedTraces.concat(ax2._traceIndices);
+        }
+        return affectedTraces;
+    };
+
     // Propagate localization into the axis so that
     // methods in Axes can use it w/o having to pass fullLayout
     // Default (non-d3) number formatting uses separators directly

src/plots/cartesian/type_defaults.js

@@ -80,14 +80,8 @@ function setAutoType(ax, data) {
         ax.type = autoType(boxPositions, calendar, opts);
     } else if(d0.type === 'splom') {
         var dimensions = d0.dimensions;
-        var diag = d0._diag;
-        for(i = 0; i < dimensions.length; i++) {
-            var dim = dimensions[i];
-            if(dim.visible && (diag[i][0] === id || diag[i][1] === id)) {
-                ax.type = autoType(dim.values, calendar, opts);
-                break;
-            }
-        }
+        var dim = dimensions[d0._axesDim[id]];
+        if(dim.visible) ax.type = autoType(dim.values, calendar, opts);
     } else {
         ax.type = autoType(d0[axLetter] || [d0[axLetter + '0']], calendar, opts);
     }

src/plots/plots.js

@@ -2843,10 +2843,199 @@ plots.doCalcdata = function(gd, traces) {
 
     doCrossTraceCalc(gd);
 
+    // Sort axis categories per value if specified
+    var sorted = sortAxisCategoriesByValue(axList, gd);
+    if(sorted.length) {
+        // If a sort operation was performed, run calc() again
+        for(i = 0; i < sorted.length; i++) calci(sorted[i], true);
+        for(i = 0; i < sorted.length; i++) calci(sorted[i], false);
+        doCrossTraceCalc(gd);
+    }
+
     Registry.getComponentMethod('fx', 'calc')(gd);
     Registry.getComponentMethod('errorbars', 'calc')(gd);
 };
 
+var sortAxisCategoriesByValueRegex = /(value|sum|min|max|mean|median) (ascending|descending)/;
+
+function sortAxisCategoriesByValue(axList, gd) {
+    var affectedTraces = [];
+    var i, j, k, l, o;
+
+    function zMapCategory(type, ax, value) {
+        var axLetter = ax._id.charAt(0);
+        if(type === 'histogram2dcontour') {
+            var counterAxLetter = ax._counterAxes[0];
+            var counterAx = axisIDs.getFromId(gd, counterAxLetter);
+
+            var xCategorical = axLetter === 'x' || (counterAxLetter === 'x' && counterAx.type === 'category');
+            var yCategorical = axLetter === 'y' || (counterAxLetter === 'y' && counterAx.type === 'category');
+
+            return function(o, l) {
+                if(o === 0 || l === 0) return -1; // Skip first row and column
+                if(xCategorical && o === value[l].length - 1) return -1;
+                if(yCategorical && l === value.length - 1) return -1;
+
+                return (axLetter === 'y' ? l : o) - 1;
+            };
+        } else {
+            return function(o, l) {
+                return axLetter === 'y' ? l : o;
+            };
+        }
+    }
+
+    var aggFn = {
+        'min': function(values) {return Lib.aggNums(Math.min, null, values);},
+        'max': function(values) {return Lib.aggNums(Math.max, null, values);},
+        'sum': function(values) {return Lib.aggNums(function(a, b) { return a + b;}, null, values);},
+        'value': function(values) {return Lib.aggNums(function(a, b) { return a + b;}, null, values);},
+        'mean': function(values) {return Lib.mean(values);},
+        'median': function(values) {values.sort(); var mid = Math.round((values.length - 1) / 2); return values[mid];}
+    };
+
+    for(i = 0; i < axList.length; i++) {
+        var ax = axList[i];
+        if(ax.type !== 'category') continue;
+
+        // Order by value
+        var match = ax.categoryorder.match(sortAxisCategoriesByValueRegex);
+        if(match) {
+            var aggregator = match[1];
+            var order = match[2];
+
+            // Store values associated with each category
+            var categoriesValue = [];
+            for(j = 0; j < ax._categories.length; j++) {
+                categoriesValue.push([ax._categories[j], []]);
+            }
+
+            // Collect values across traces
+            for(j = 0; j < ax._traceIndices.length; j++) {
+                var traceIndex = ax._traceIndices[j];
+                var fullTrace = gd._fullData[traceIndex];
+                var axLetter = ax._id.charAt(0);
+
+                // Skip over invisible traces
+                if(fullTrace.visible !== true) continue;
+
+                var type = fullTrace.type;
+                if(Registry.traceIs(fullTrace, 'histogram')) delete fullTrace._autoBinFinished;
+
+                var cd = gd.calcdata[traceIndex];
+                for(k = 0; k < cd.length; k++) {
+                    var cdi = cd[k];
+                    var cat, catIndex, value;
+
+                    // If `splom`, collect values across dimensions
+                    if(type === 'splom') {
+                        // Find which dimension the current axis is representing
+                        var currentDimensionIndex = fullTrace._axesDim[ax._id];
+
+                        // Apply logic to associated x axis
+                        if(axLetter === 'y') {
+                            var associatedXAxisID = fullTrace._diag[currentDimensionIndex][0];
+                            ax = gd._fullLayout[axisIDs.id2name(associatedXAxisID)];
+                        }
+
+                        var categories = cdi.trace.dimensions[currentDimensionIndex].values;
+                        for(l = 0; l < categories.length; l++) {
+                            cat = categories[l];
+                            catIndex = ax._categoriesMap[cat];
+
+                            // Collect associated values at index `l` over all other dimensions
+                            for(o = 0; o < cdi.trace.dimensions.length; o++) {
+                                if(o === currentDimensionIndex) continue;
+                                var dimension = cdi.trace.dimensions[o];
+                                categoriesValue[catIndex][1].push(dimension.values[l]);
+                            }
+                        }
+                    // If `scattergl`, collect all values stashed under cdi.t
+                    } else if(type === 'scattergl') {
+                        for(l = 0; l < cdi.t.x.length; l++) {
+                            if(axLetter === 'x') {
+                                cat = cdi.t.x[l];
+                                catIndex = cat;
+                                value = cdi.t.y[l];
+                            }
+
+                            if(axLetter === 'y') {
+                                cat = cdi.t.y[l];
+                                catIndex = cat;
+                                value = cdi.t.x[l];
+                            }
+                            categoriesValue[catIndex][1].push(value);
+                        }
+                        // must clear scene 'batches', so that 2nd
+                        // _module.calc call starts from scratch
+                        if(cdi.t && cdi.t._scene) {
+                            delete cdi.t._scene.dirty;
+                        }
+                    // For all other 2d cartesian traces
+                    } else {
+                        if(axLetter === 'x') {
+                            cat = cdi.p + 1 ? cdi.p : cdi.x;
+                            value = cdi.s || cdi.v || cdi.y;
+                        } else if(axLetter === 'y') {
+                            cat = cdi.p + 1 ? cdi.p : cdi.y;
+                            value = cdi.s || cdi.v || cdi.x;
+                        }
+
+                        // If 2dMap, collect values in `z`
+                        if(cdi.hasOwnProperty('z')) {
+                            value = cdi.z;
+                            var mapping = zMapCategory(fullTrace.type, ax, value);
+
+                            for(l = 0; l < value.length; l++) {
+                                for(o = 0; o < value[l].length; o++) {
+                                    catIndex = mapping(o, l);
+                                    if(catIndex + 1) categoriesValue[catIndex][1].push(value[l][o]);
+                                }
+                            }
+                        } else {
+                            if(!Array.isArray(value)) value = [value];
+                            for(l = 0; l < value.length; l++) {
+                                categoriesValue[cat][1].push(value[l]);
+                            }
+                        }
+                    }
+                }
+            }
+
+            ax._categoriesValue = categoriesValue;
+
+            var categoriesAggregatedValue = [];
+            for(j = 0; j < categoriesValue.length; j++) {
+                categoriesAggregatedValue.push([
+                    categoriesValue[j][0],
+                    aggFn[aggregator](categoriesValue[j][1])
+                ]);
+            }
+
+            // Sort by aggregated value
+            categoriesAggregatedValue.sort(function(a, b) {
+                return a[1] - b[1];
+            });
+
+            ax._categoriesAggregatedValue = categoriesAggregatedValue;
+
+            // Set new category order
+            ax._initialCategories = categoriesAggregatedValue.map(function(c) {
+                return c[0];
+            });
+
+            // Reverse if descending
+            if(order === 'descending') {
+                ax._initialCategories.reverse();
+            }
+
+            // Sort all matching axes
+            affectedTraces = affectedTraces.concat(ax.sortByInitialCategories());
+        }
+    }
+    return affectedTraces;
+}
+
 function setupAxisCategories(axList, fullData) {
     for(var i = 0; i < axList.length; i++) {
         var ax = axList[i];

src/traces/box/calc.js

@@ -80,6 +80,10 @@ module.exports = function calc(gd, trace) {
             cdi.pos = posDistinct[i];
             cdi.pts = pts;
 
+            // Sort categories by values
+            cdi[posLetter] = cdi.pos;
+            cdi[valLetter] = cdi.pts.map(function(pt) { return pt.v; });
+
             cdi.min = boxVals[0];
             cdi.max = boxVals[bvLen - 1];
             cdi.mean = Lib.mean(boxVals, bvLen);

src/traces/ohlc/calc.js

@@ -86,6 +86,10 @@ function calcCommon(gd, trace, x, ya, ptFunc) {
             pt.i = i;
             pt.dir = increasing ? 'increasing' : 'decreasing';
 
+            // For categoryorder, store low and high
+            pt.x = pt.pos;
+            pt.y = [li, hi];
+
             if(hasTextArray) pt.tx = trace.text[i];
             if(hasHovertextArray) pt.htx = trace.hovertext[i];
 

src/traces/splom/defaults.js

@@ -127,6 +127,7 @@ function handleAxisDefaults(traceIn, traceOut, layout, coerce) {
     var mustShiftX = !showDiag && !showLower;
     var mustShiftY = !showDiag && !showUpper;
 
+    traceOut._axesDim = {};
     for(i = 0; i < dimLength; i++) {
         var dim = dimensions[i];
         var i0 = i === 0;
@@ -143,6 +144,8 @@ function handleAxisDefaults(traceIn, traceOut, layout, coerce) {
         fillAxisStashes(xaId, yaId, dim, xList);
         fillAxisStashes(yaId, xaId, dim, yList);
         diag[i] = [xaId, yaId];
+        traceOut._axesDim[xaId] = i;
+        traceOut._axesDim[yaId] = i;
     }
 
     // fill in splom subplot keys

test/image/mocks/hist_category_value_ascending.json

@@ -0,0 +1,39 @@
+{
+  "data": [{
+    "x": ["a", "b", "c", "a", "b", "d", "b", "c", "b", "b"],
+    "type": "histogram"
+  },
+  {
+    "x": ["d", "c", "a", "e", "a"],
+    "type": "histogram"
+  },
+  {
+    "y": ["a", "b", "c", "a", "b", "d", "b", "c"],
+    "type": "histogram",
+    "xaxis": "x2",
+    "yaxis": "y2"
+  },
+  {
+    "y": ["d", "c", "b", "a", "e", "a", "b"],
+    "type": "histogram",
+    "xaxis": "x2",
+    "yaxis": "y2"
+  }],
+  "layout": {
+    "title": "categoryorder: \"value ascending\"",
+    "height": 400,
+    "width": 600,
+    "barmode": "stack",
+    "xaxis": {
+      "domain": [0, 0.45],
+      "categoryorder": "value ascending"
+    },
+    "xaxis2": {
+      "domain": [0.55, 1]
+    },
+    "yaxis2": {
+      "anchor": "x2",
+      "categoryorder": "value ascending"
+    }
+  }
+}