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,11 @@ 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'
         ],
         dflt: 'trace',
         role: 'info',
@@ -828,11 +831,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 or the sums of 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/plots.js

@@ -2843,10 +2843,203 @@ 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) (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;
+
+                var catIndex = axLetter === 'y' ? l : o;
+                return catIndex - 1;
+            };
+        } else {
+            return function(o, l) {
+                return axLetter === 'y' ? l : o;
+            };
+        }
+    }
+
+    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) {
+            // 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 = cdi.trace[axLetter + 'axes'].indexOf(ax._id);
+
+                        // Apply logic to associated x axis
+                        if(axLetter === 'y') {
+                            var associatedXAxis = ax._id.split('');
+                            associatedXAxis[0] = 'x';
+                            associatedXAxis = associatedXAxis.join('');
+                            ax = gd._fullLayout[axisIDs.id2name(associatedXAxis)];
+                        }
+
+                        var categories = cdi.trace.dimensions[currentDimensionIndex].values;
+                        for(l = 0; l < categories.length; l++) {
+                            cat = categories[l];
+                            catIndex = ax._categoriesMap[cat];
+
+                            // Collect values 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]);
+                            }
+                        }
+                    }
+                }
+            }
+
+            // Aggregate values
+            var aggFn;
+            switch(match[1]) {
+                case 'min':
+                    aggFn = Math.min;
+                    break;
+                case 'max':
+                    aggFn = Math.max;
+                    break;
+                default:
+                    aggFn = function(a, b) { return a + b;};
+            }
+
+            ax._categoriesValue = categoriesValue;
+
+            var categoriesAggregatedValue = [];
+            for(j = 0; j < categoriesValue.length; j++) {
+                categoriesAggregatedValue.push([
+                    categoriesValue[j][0],
+                    Lib.aggNums(aggFn, null, 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(match[2] === '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];
 

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"
+    }
+  }
+}

test/image/mocks/scatter_category_value_descending.json

@@ -0,0 +1,26 @@
+{
+    "data": [
+        {
+            "x": ["a", "b", "c", "d"],
+            "y": [4, 2, 3, 1],
+            "type": "scatter",
+            "mode": "markers"
+        },
+        {
+            "x": ["a", "b", "c", "d", "c", "c"],
+            "type": "histogram"
+        }
+    ],
+    "layout": {
+        "title": "xaxis.categoryorder: \"value descending\"",
+        "width": 400,
+        "height": 400,
+        "xaxis": {
+            "domain": [
+                0,
+                1
+            ],
+            "categoryorder": "value descending"
+        }
+    }
+}

test/image/mocks/sort_by_value_matching_axes.json

@@ -0,0 +1,29 @@
+{
+  "data": [{
+    "type": "scatter",
+    "orientation": "v",
+    "x": ["a", "b", "c"],
+    "y": [7, 2, 3]
+  }, {
+    "type": "bar",
+    "x": ["a", "b", "c"],
+    "y": [10, 20, 30],
+    "yaxis": "y2",
+    "xaxis": "x2"
+  }],
+  "layout": {
+    "xaxis": {
+        "type": "category",
+        "categoryorder": "value ascending"
+    },
+    "xaxis2": {
+        "matches": "x"
+    },
+    "yaxis": {
+      "domain": [0, 0.45]
+    },
+    "yaxis2": {
+      "domain": [0.55, 1]
+    }
+  }
+}