Sort transform

lib/index.js

@@ -56,7 +56,8 @@ Plotly.register([
 //
 Plotly.register([
     require('./filter'),
-    require('./groupby')
+    require('./groupby'),
+    require('./sort')
 ]);
 
 // components

lib/sort.js

@@ -0,0 +1,11 @@
+/**
+* Copyright 2012-2017, 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 = require('../src/transforms/sort');

src/transforms/sort.js

@@ -0,0 +1,189 @@
+/**
+* Copyright 2012-2017, 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 Lib = require('../lib');
+var PlotSchema = require('../plot_api/plot_schema');
+var axisIds = require('../plots/cartesian/axis_ids');
+var autoType = require('../plots/cartesian/axis_autotype');
+var setConvert = require('../plots/cartesian/set_convert');
+
+exports.moduleType = 'transform';
+
+exports.name = 'sort';
+
+exports.attributes = {
+    enabled: {
+        valType: 'boolean',
+        dflt: true,
+        description: [
+            'Determines whether this sort transform is enabled or disabled.'
+        ].join(' ')
+    },
+    target: {
+        valType: 'string',
+        strict: true,
+        noBlank: true,
+        arrayOk: true,
+        dflt: 'x',
+        description: [
+            'Sets the target by which the sort transform is applied.',
+
+            'If a string, *target* is assumed to be a reference to a data array',
+            'in the parent trace object.',
+            'To sort about nested variables, use *.* to access them.',
+            'For example, set `target` to *marker.size* to sort',
+            'about the marker size array.',
+
+            'If an array, *target* is then the data array by which',
+            'the sort transform is applied.'
+        ].join(' ')
+    },
+    order: {
+        valType: 'enumerated',
+        values: ['ascending', 'descending'],
+        dflt: 'ascending',
+        description: [
+            'Sets the sort transform order.'
+        ].join(' ')
+    }
+};
+
+exports.supplyDefaults = function(transformIn) {
+    var transformOut = {};
+
+    function coerce(attr, dflt) {
+        return Lib.coerce(transformIn, transformOut, exports.attributes, attr, dflt);
+    }
+
+    var enabled = coerce('enabled');
+
+    if(enabled) {
+        coerce('target');
+        coerce('order');
+    }
+
+    return transformOut;
+};
+
+exports.calcTransform = function(gd, trace, opts) {
+    if(!opts.enabled) return;
+
+    var target = opts.target;
+    var targetArray = getTargetArray(trace, target);
+    var len = targetArray.length;
+
+    if(!len) return;
+
+    var arrayAttrs = PlotSchema.findArrayAttributes(trace);
+    var d2c = getDataToCoordFunc(gd, trace, target, targetArray);
+    var indices = getIndices(opts, targetArray, d2c);
+
+    for(var i = 0; i < arrayAttrs.length; i++) {
+        var np = Lib.nestedProperty(trace, arrayAttrs[i]);
+        var arrayCopy = np.get().slice();
+        var arrayNew = new Array(len);
+
+        for(var j = 0; j < len; j++) {
+            arrayNew[j] = arrayCopy[indices[j]];
+        }
+
+        np.set(arrayNew);
+    }
+};
+
+// TODO reuse for filter.js
+function getTargetArray(trace, target) {
+    if(typeof target === 'string' && target) {
+        var array = Lib.nestedProperty(trace, target).get();
+
+        return Array.isArray(array) ? array : [];
+    }
+    else if(Array.isArray(target)) return target.slice();
+
+    return false;
+}
+
+// TODO reuse for filter.js
+function getDataToCoordFunc(gd, trace, target, targetArray) {
+    var ax;
+
+    // If target points to an axis, use the type we already have for that
+    // axis to find the data type. Otherwise use the values to autotype.
+    if(target === 'x' || target === 'y' || target === 'z') {
+        ax = axisIds.getFromTrace(gd, trace, target);
+    }
+    // In the case of an array target, make a mock data array
+    // and call supplyDefaults to the data type and
+    // setup the data-to-calc method.
+    else if(Array.isArray(target)) {
+        ax = {
+            type: autoType(targetArray),
+            // TODO does this still work with the new hash object
+            _categories: []
+        };
+        setConvert(ax);
+
+        // build up ax._categories (usually done during ax.makeCalcdata()
+        if(ax.type === 'category') {
+            for(var i = 0; i < targetArray.length; i++) {
+                ax.d2c(targetArray[i]);
+            }
+        }
+    }
+
+    // if 'target' has corresponding axis
+    // -> use setConvert method
+    if(ax) return ax.d2c;
+
+    // special case for 'ids'
+    // -> cast to String
+    if(target === 'ids') return function(v) { return String(v); };
+
+    // otherwise (e.g. numeric-array of 'marker.color' or 'marker.size')
+    // -> cast to Number
+    return function(v) { return +v; };
+}
+
+function getIndices(opts, targetArray, d2c) {
+    var len = targetArray.length;
+    var indices = new Array(len);
+
+    var sortedArray = targetArray
+        .slice()
+        .sort(getSortFunc(opts, d2c));
+
+    for(var i = 0; i < len; i++) {
+        var vTarget = targetArray[i];
+
+        for(var j = 0; j < len; j++) {
+            var vSorted = sortedArray[j];
+
+            if(vTarget === vSorted) {
+                indices[j] = i;
+
+                // clear sortedArray item to get correct
+                // index of duplicate items (if any)
+                sortedArray[j] = null;
+                break;
+            }
+        }
+    }
+
+    return indices;
+}
+
+function getSortFunc(opts, d2c) {
+    switch(opts.order) {
+        case 'ascending':
+            return function(a, b) { return d2c(a) - d2c(b); };
+        case 'descending':
+            return function(a, b) { return d2c(b) - d2c(a); };
+    }
+}