Gradient Coloring Option for Feature Metadata

empress/support_files/css/empress.css

@@ -609,7 +609,7 @@ p.side-header button:hover,
 #legend-main {
     margin: 20px;
     min-width: 150px;
-    max-width: 33vw;
+    max-width: 30vw;
     min-height: 30px;
     max-height: 85vh;
     padding-bottom: 0.1px;

empress/support_files/js/barplot-layer.js

@@ -3,9 +3,9 @@ define([
     "underscore",
     "spectrum",
     "Colorer",
-    "Legend",
+    "BarplotLegend",
     "util",
-], function ($, _, spectrum, Colorer, Legend, util) {
+], function ($, _, spectrum, Colorer, BarplotLegend, util) {
     /**
      *
      * @class BarplotLayer
@@ -634,14 +634,14 @@ define([
         this.colorLegendDiv.classList.add("hidden");
         this.colorLegendDiv.classList.add("legend");
         this.colorLegendDiv.classList.add("barplot-layer-legend");
-        this.colorLegend = new Legend(this.colorLegendDiv);
+        this.colorLegend = new BarplotLegend(this.colorLegendDiv);
         this.layerDiv.appendChild(this.colorLegendDiv);
 
         this.lengthLegendDiv = document.createElement("div");
         this.lengthLegendDiv.classList.add("hidden");
         this.lengthLegendDiv.classList.add("legend");
         this.lengthLegendDiv.classList.add("barplot-layer-legend");
-        this.lengthLegend = new Legend(this.lengthLegendDiv);
+        this.lengthLegend = new BarplotLegend(this.lengthLegendDiv);
         this.layerDiv.appendChild(this.lengthLegendDiv);
 
         // TODO: if possible, making the legend text selectable (overriding
@@ -757,7 +757,7 @@ define([
      * effect) will be excluded from the Array. However, if all legends are
      * active, the order in the Array will always be color then length.
      *
-     * @return {Array} Array of Legend objects
+     * @return {Array} Array of BarplotLegend objects
      */
     BarplotLayer.prototype.getLegends = function () {
         var containedLegends = [this.colorLegend, this.lengthLegend];

empress/support_files/js/barplot-legend.js

@@ -0,0 +1,35 @@
+define(["Legend"], function (Legend) {
+    /**
+     * @class SampleFeatureColorLegend
+     */
+    function BarplotLegend(container) {
+        // call Legend constructor
+        Legend.call(this, container);
+
+        /**
+         * @type {String}
+         * Text to display at the bottom of the continuous legend when some
+         * values in a field are either missing or non-numeric.
+         */
+        this.continuousMissingNonNumericWarning =
+            "Some value(s) in this field were missing and/or not numeric. " +
+            "These value(s) have been left out of the gradient, and no " +
+            "bar(s) have been drawn for them.";
+
+        /**
+         * @type {String}
+         * Short version of the above warning, shown for the same legends when
+         * exported to SVG
+         */
+        this.continuousMissingNonNumericWarningShort =
+            "Missing / non-numeric value(s) omitted.";
+    }
+
+    // inherit Legend functions
+    BarplotLegend.prototype = Object.create(Legend.prototype);
+
+    // set BarplotLegend's constructor
+    BarplotLegend.prototype.constructor = BarplotLegend;
+
+    return BarplotLegend;
+});

empress/support_files/js/empress.js

@@ -6,7 +6,7 @@ define([
     "VectorOps",
     "CanvasEvents",
     "BarplotPanel",
-    "Legend",
+    "SampleFeatureColorLegend",
     "util",
     "chroma",
     "LayoutsUtil",
@@ -20,7 +20,7 @@ define([
     VectorOps,
     CanvasEvents,
     BarplotPanel,
-    Legend,
+    SampleFeatureColorLegend,
     util,
     chroma,
     LayoutsUtil,
@@ -159,11 +159,13 @@ define([
         }
 
         /**
-         * @type {Legend}
+         * @type {SampleFeatureColorLegend}
          * Legend describing the way the tree is colored.
          * @private
          */
-        this._legend = new Legend(document.getElementById("legend-main"));
+        this._legend = new SampleFeatureColorLegend(
+            document.getElementById("legend-main")
+        );
 
         /**
          * @type {BiomTable}
@@ -2489,14 +2491,19 @@ define([
      * @param{Boolean} reverse Defaults to false. If true, the color scale
      *                         will be reversed, with respect to its default
      *                         orientation.
-     *
+     * @param{Boolean} continuous Defaults to false. If true, the colorer will
+     *                            try to use a gradient color scale.
+     * @param{Function} continousFailedFunc The function to call if continuous
+     *                                      coloring failed.
      * @return {Object} Maps unique values in this f. metadata column to colors
      */
     Empress.prototype.colorByFeatureMetadata = function (
         cat,
         color,
         method,
-        reverse = false
+        reverse = false,
+        continuous = false,
+        continousFailedFunc = null
     ) {
         var fmInfo = this.getUniqueFeatureMetadataInfo(cat, method);
         var sortedUniqueValues = fmInfo.sortedUniqueValues;
@@ -2509,26 +2516,70 @@ define([
             obs[uniqueVal] = new Set(uniqueValueToFeatures[uniqueVal]);
         });
 
-        // assign colors to unique values
-        var colorer = new Colorer(
-            color,
-            sortedUniqueValues,
-            undefined,
-            undefined,
-            reverse
-        );
-
+        var colorer;
+        try {
+            // assign colors to unique values
+            colorer = new Colorer(
+                color,
+                sortedUniqueValues,
+                continuous,
+                // Colorer will create a special gradient ID using the number
+                // we pass into this parameter. This allows empress to display
+                // multiple gradients at the same time without them overriding
+                // each other. Currently, the barplots are set up to start at
+                // 0. So, we set this value to -1 here to avoid conflict with
+                // the barplot gradients; this allows us to display the
+                // feature metadata gradient alongside the
+                // barplot gradients.
+                continuous ? -1 : undefined,
+                reverse
+            );
+        } catch (err) {
+            // If the Colorer construction failed (should only have
+            // happened if the user asked for continuous values but the
+            // selected field doesn't have at least 2 unique numeric
+            // values), then we open a toast message about this error and
+            // use discrete coloring instead.
+            continuous = false;
+            var msg =
+                'Error with assigning colors: the feature metadata field "' +
+                cat +
+                '" has less than 2 unique numeric values, so it cannot be ' +
+                "used for continuous coloring. " +
+                "Using discrete coloring instead.";
+            util.toastMsg("Feature metadata coloring error", msg, 5000);
+            // assign colors to unique values
+            colorer = new Colorer(
+                color,
+                sortedUniqueValues,
+                continuous,
+                undefined,
+                reverse
+            );
+            continousFailedFunc();
+        }
         // colors for drawing the tree
         var cm = colorer.getMapRGB();
 
         // colors for the legend
-        var keyInfo = colorer.getMapHex();
+        var keyInfo;
+        if (continuous) {
+            keyInfo = colorer.getGradientInfo();
+        } else {
+            keyInfo = colorer.getMapHex();
+        }
 
         // if the tree has been sheared then categories in obs maybe empty.
         // getUniqueFeatureMetadataInfo() does not filter out those categories
         // so that the same color can be assigned to each value in obs.
         util.removeEmptyArrayKeys(keyInfo, uniqueValueToFeatures);
 
+        // In the case of continuous coloring, non-numeric values will not be
+        // added to cm and is the only such case where the keys in obs (after
+        // projectObservations has been called) and keys in cm will differ.
+        // Thus, we need to remove the non-numeric keys from obs.
+        obs = _.pick(obs, Object.keys(cm));
+
         // Do upwards propagation only if the coloring method is "tip"
         if (method === "tip") {
             obs = this._projectObservations(obs, false);
@@ -2540,7 +2591,12 @@ define([
         // color tree
         this._colorTree(obs, cm);
 
-        this.updateLegendCategorical(cat, keyInfo);
+        this.resizeLegend();
+        if (continuous) {
+            this._legend.addContinuousKey(cat, keyInfo);
+        } else {
+            this.updateLegendCategorical(cat, keyInfo);
+        }
 
         return keyInfo;
     };
@@ -2554,7 +2610,7 @@ define([
      *
      *      2) Assigns each internal node to a group if all of its children belong
      *         to the same group.
-     *@t
+     *
      *      3) Remove empty groups from return object.
      *
      * Note: All tips that are not passed into obs are considered to belong to
@@ -3030,7 +3086,7 @@ define([
         // project groups up tree
         // Note: if _projectObservations was called, then if an internal node
         // belongs to a group, all of its descendants will belong to the
-        // same group. However, this is not guaranteed if _projectOBservations
+        // same group. However, this is not guaranteed if _projectObservations
         // was not called. Thus, this loop is used to guarantee that if an
         // internal node belongs to a group then all of its descendants belong
         // to the same group.

empress/support_files/js/legend.js

@@ -1,6 +1,7 @@
 define(["jquery", "underscore", "util"], function ($, _, util) {
     /**
      *
+     * @Abstract
      * @class Legend
      *
      * Creates a legend within a given HTML element. (You'll need to call
@@ -11,7 +12,6 @@ define(["jquery", "underscore", "util"], function ($, _, util) {
      *                                will be added.
      *
      * @return {Legend}
-     * @constructs Legend
      */
     function Legend(container) {
         /**
@@ -102,6 +102,25 @@ define(["jquery", "underscore", "util"], function ($, _, util) {
          */
         this._minLengthVal = null;
         this._maxLengthVal = null;
+
+        /**
+         * @type {String}
+         * Text to display at the bottom of the continuous legend when some
+         * values in a field are either missing or non-numeric.
+         */
+        this.continuousMissingNonNumericWarning = null;
+
+        /**
+         * @type {String}
+         * Short version of the above warning, shown for the same legends when
+         * exported to SVG
+         */
+        this.continuousMissingNonNumericWarningShort = null;
+
+        // make Legend an abstract class
+        if (this.constructor === Legend) {
+            throw new Error("Abstract class Legend can not be instantiated.");
+        }
     }
 
     /**
@@ -179,14 +198,28 @@ define(["jquery", "underscore", "util"], function ($, _, util) {
             "svg"
         );
         containerSVG.setAttribute("width", "100%");
-        containerSVG.setAttribute("height", "100%");
+        containerSVG.setAttribute("height", "80%");
         containerSVG.setAttribute("style", "display: block; margin: auto;");
         // just kinda plop the combined SVG code into containerSVG's HTML
         containerSVG.innerHTML = totalHTMLSVG;
-        this._container.appendChild(containerSVG);
+
+        // We need to put the svg container inside a div: otherwise, some unwanted
+        // behavior will occur when users resize the legend.
+        // The gradient bar's height is set to be 80% of the legend's
+        // height. This works for most cases; however, some issues come up when
+        // the user resizes the legend -- the height of the gradient color
+        // bar will continuously be set to 80% of the legend's height, which
+        // can hide the warning message(s) that appear beneath the gradient.
+        // By putting the svg container inside a div, the gradient color bar
+        // will be set to 80% of the initial size of the legend and will remain
+        // fixed when users resize the legend.
+        var fixSizeDiv = document.createElement("div");
+        fixSizeDiv.appendChild(containerSVG);
+        this._container.appendChild(fixSizeDiv);
         if (this._missingNonNumericWarningShown) {
+            var missingText = this.getMissingNonNumericWarning();
             var warningP = document.createElement("p");
-            warningP.innerText = Legend.CONTINUOUS_MISSING_NON_NUMERIC_WARNING;
+            warningP.innerText = missingText.full;
             warningP.classList.add("side-panel-notes");
             // All legends have white-space: nowrap; set to prevent color
             // labels from breaking onto the next line (which would look
@@ -220,6 +253,12 @@ define(["jquery", "underscore", "util"], function ($, _, util) {
      *                      their assigned color, expressed in hex format.
      */
     Legend.prototype.addCategoricalKey = function (name, info) {
+        if (_.isEmpty(info)) {
+            throw new Error(
+                "Can't create a categorical legend when there are no " +
+                    "categories in the info"
+            );
+        }
         this.clear();
         this.addTitle(name);
         this._sortedCategories = util.naturalSort(_.keys(info));
@@ -533,6 +572,7 @@ define(["jquery", "underscore", "util"], function ($, _, util) {
         // But first, let's add a warning about missing / non-numeric values if
         // needed.
         if (this._missingNonNumericWarningShown) {
+            var missingText = this.getMissingNonNumericWarning();
             // We use a hanging baseline to add some extra vertical space
             // between the gradient minimum value and the warning text. This
             // seems to look nice.
@@ -542,9 +582,9 @@ define(["jquery", "underscore", "util"], function ($, _, util) {
                 '" y="' +
                 (gradientTopY + gradientHeight + Legend.HALF_LINE_HEIGHT) +
                 '" dominant-baseline="hanging">' +
-                Legend.CONTINUOUS_MISSING_NON_NUMERIC_WARNING_SHORT +
+                missingText.short +
                 "</text>\n";
-            texts.push(Legend.CONTINUOUS_MISSING_NON_NUMERIC_WARNING_SHORT);
+            texts.push(missingText.short);
         }
         _.each(texts, function (text) {
             maxLineWidth = Math.max(
@@ -733,17 +773,22 @@ define(["jquery", "underscore", "util"], function ($, _, util) {
         };
     };
 
-    // Shown at the bottom of continuous legends in the page when some values
-    // in a continuous field can't be represented on a gradient
-    Legend.CONTINUOUS_MISSING_NON_NUMERIC_WARNING =
-        "Some value(s) in this field were missing and/or not numeric. " +
-        "These value(s) have been left out of the gradient, and no bar(s) " +
-        "have been drawn for them.";
-
-    // Short version of the above warning, shown for the same legends when
-    // exported to SVG
-    Legend.CONTINUOUS_MISSING_NON_NUMERIC_WARNING_SHORT =
-        "Missing / non-numeric value(s) omitted.";
+    /**
+     * Returns the full and short versions of the continuous missing
+     * non-numeric warning messages.
+     *
+     * @return {Object} This object is formatted as follows:
+     * {
+     *      full: messageString,
+     *      short: messageString
+     * }
+     */
+    Legend.prototype.getMissingNonNumericWarning = function () {
+        return {
+            full: this.continuousMissingNonNumericWarning,
+            short: this.continuousMissingNonNumericWarningShort,
+        };
+    };
 
     // Various SVG attributes stored here since they're used every time the
     // export function is called