Allow different sorters to work with Vis Object

doc/index.rst

@@ -47,6 +47,7 @@ This website contains pages that overview of the basic and advanced functionalit
    source/advanced/architecture
    source/advanced/executor
    source/advanced/interestingness
+   source/advanced/sorting
 
 
 

doc/source/advanced/sorting.rst

@@ -0,0 +1,67 @@
+***********************************
+Ordering Outputs
+***********************************
+
+By default, Lux is trying to maximize the `interestingness function <interestingness.html>`_.
+However, in some cases, perhaps you would like to sort by a different feature or attribute.
+Here are some default sorters available to use:
+
+Supported Orderings
+====================
+
+
+1. `"interestingness"`: This is the default sorter selected in Lux. It scores by the `interestingness function <interestingness.html>`_.
+
+2. `"alphabetical_by_title"`: This sorter allows for alphabetical sorting based on the title.
+
+3. `"alphabetical_by_x"` : This sorter allows for alphabetical sorting based on the attribute featured on the x-axis.
+
+4. `"alphabetical_by_y"` : This sorter allows for alphabetical sorting based on the attribute featured on the y-axis.
+
+Custom Orderings
+====================
+
+You can also add a custom sorter by creating a function that takes in a collection and a direction (ascending or descending)
+and returns the sorted collection.
+
+For example,
+
+.. code-block:: python
+
+    def sort_by_multiple(collection, desc):
+        collection.sort(key=lambda x: (x.get_attr_by_channel("x")[0].attribute, x.get_attr_by_channel("y")[0].attribute), reverse=False)
+    lux.config.ordering = sort_by_multiple
+
+In this example, instead of sorting by just the x attribute or y attribute, we'd like to sort first by the x attribute and then sort by the y attribute.
+The last line sets this to the globally defined ordering, which means that all actions will be ordered using this function.
+
+Action-Dependent Orderings
+==========================
+There are some cases where we'd like to sort the outputs of different actions differently.
+To do so, you can add to the :code:`lux.config.ordering_actions` dictionary. To set an action's ordering,
+you can do the following, for example:
+
+.. code-block:: python
+
+    lux.config.ordering_actions["correlation"] = "alphabetical_by_x"
+
+To remove the ordering for the action, simply reset the dictionary's entry to an empty string, like so:
+
+.. code-block:: python
+
+    lux.config.ordering_actions["correlation"] = ""
+
+Changing the sorting direction
+==============================
+
+By default, Lux is trying to `maximize` an objective function, whether that be `interestingness` or some other custom function you define.
+Thus, the default sorting direction is :code:`"descending"`. In order to toggle it, you can use:
+
+.. code-block:: python
+
+    lux.config.sort = "ascending" # or "descending" or "None" for no sorting order
+
+This is a globally defined sort order.
+
+
+

doc/source/reference/gen/lux._config.config.Config.rst

@@ -30,6 +30,8 @@
       ~Config.default_display
       ~Config.heatmap
       ~Config.interestingness_fallback
+      ~Config.ordering
+      ~Config.ordering_actions
       ~Config.label_len
       ~Config.number_of_bars
       ~Config.pandas_fallback

lux/_config/config.py

@@ -6,6 +6,7 @@
 from typing import Any, Callable, Dict, Iterable, List, Optional, Union
 import lux
 import warnings
+from lux.utils.orderings import Ordering, OrderingDict, resolve_value
 from lux.utils.tracing_utils import LuxTracer
 import os
 from lux._config.template import postgres_template, mysql_template
@@ -31,9 +32,12 @@ def __init__(self):
         self._plotting_backend = "vegalite"
         self._plotting_scale = 1
         self._topk = 15
+        self._sort = True
+        self._ordering = Ordering.interestingness
+        self._ordering_actions = OrderingDict({})
         self._number_of_bars = 10  # max no of bars displayed (rest shown as "+ k more")
         self._label_len = 25  # max length of x and y axis labels
-        self._sort = "descending"
+        self._sort = True
         self._pandas_fallback = True
         self._interestingness_fallback = True
         self.heatmap_bin_size = 40
@@ -127,8 +131,6 @@ def sort(self):
     @sort.setter
     def sort(self, flag: Union[str]):
         """
-        Setting parameter to determine sort order of each action
-
         Parameters
         ----------
         flag : Union[str]
@@ -137,13 +139,37 @@ def sort(self, flag: Union[str]):
         """
         flag = flag.lower()
         if isinstance(flag, str) and flag in ["none", "ascending", "descending"]:
-            self._sort = flag
+            if flag == "none":
+                self._sort = None
+            elif flag == "ascending":
+                self._sort = False
+            else:
+                self._sort = True
         else:
             warnings.warn(
                 "Parameter to lux.config.sort must be one of the following: 'none', 'ascending', or 'descending'.",
                 stacklevel=2,
             )
 
+    @property
+    def ordering(self):
+        return self._ordering
+
+    @ordering.setter
+    def ordering(self, value):
+        """
+        Parameters
+        ----------
+        value : Union[str, Callable]
+                "interestingness", “alphabetical_by_title”, “alphabetical_by_x”, “alphabetical_by_y” , or Callable
+                Default available sorters or custom sorter
+        """
+        self._ordering = resolve_value(value)
+
+    @property
+    def ordering_actions(self):
+        return self._ordering_actions
+
     @property
     def pandas_fallback(self):
         return self._pandas_fallback

lux/action/correlation.py

@@ -47,7 +47,7 @@ def correlation(ldf: LuxDataFrame, ignore_transpose: bool = True):
         lux.Clause("?", data_model="measure"),
     ]
     intent.extend(filter_specs)
-    vlist = VisList(intent, ldf)
+    vlist = VisList(intent, ldf, action="correlation")
     examples = ""
     if len(vlist) > 1:
         measures = vlist[0].get_attr_by_data_model("measure")

lux/action/enhance.py

@@ -62,7 +62,7 @@ def enhance(ldf):
         clause.channel = ""
     intent = filters + attr_specs
     intent.append("?")
-    vlist = lux.vis.VisList.VisList(intent, ldf)
+    vlist = lux.vis.VisList.VisList(intent, ldf, action="Enhance")
 
     # Then use the data populated in the vis list to compute score
     for vis in vlist:

lux/action/filter.py

@@ -132,8 +132,8 @@ def get_complementary_ops(fltr_op):
         # array of possible values for attribute
         arr = ldf[last.attribute].unique().tolist()
         output.append(lux.Clause(last.attribute, last.attribute, arr))
-    vlist = lux.vis.VisList.VisList(output, ldf)
-    vlist_copy = lux.vis.VisList.VisList(output, ldf)
+    vlist = lux.vis.VisList.VisList(output, ldf, action="Filter")
+    vlist_copy = lux.vis.VisList.VisList(output, ldf, action="Filter")
     for i in range(len(vlist_copy)):
         vlist[i].score = interestingness(vlist_copy[i], ldf)
     vlist.sort()

lux/action/temporal.py

@@ -51,11 +51,11 @@ def temporal(ldf):
     if len(vlist) == 0:
         intent = [lux.Clause("?", data_type="temporal")]
         intent.extend(utils.get_filter_specs(ldf._intent))
-        vlist = VisList(intent, ldf)
+        vlist = VisList(intent, ldf, action="temporal")
         for vis in vlist:
             vis.score = interestingness(vis, ldf)
     else:
-        vlist = VisList(vlist)
+        vlist = VisList(vlist, action="temporal")
         recommendation["long_description"] += (
             " Lux displays the overall temporal trend first,"
             + " followed by trends across other timescales (e.g., year, month, week, day)."

lux/action/univariate.py

@@ -92,7 +92,7 @@ def univariate(ldf, *args):
     if ignore_rec_flag:
         recommendation["collection"] = []
         return recommendation
-    vlist = VisList(intent, ldf)
+    vlist = VisList(intent, ldf, recommendation["action"].lower())
     for vis in vlist:
         vis.score = interestingness(vis, ldf)
     vlist.sort()

lux/utils/orderings.py

@@ -0,0 +1,76 @@
+#  Copyright 2019-2020 The Lux Authors.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+import collections
+import warnings
+
+import lux
+
+
+class Ordering:
+    @staticmethod
+    def interestingness(collection, desc):
+        collection.sort(key=lambda x: x.score, reverse=desc)
+
+    @staticmethod
+    def title(collection, desc):
+        collection.sort(key=lambda x: x.title, reverse=desc)
+
+    @staticmethod
+    def x_alpha(collection, desc):
+        collection.sort(key=lambda x: x.get_attr_by_channel("x")[0].attribute, reverse=desc)
+
+    @staticmethod
+    def y_alpha(collection, desc):
+        collection.sort(key=lambda x: x.get_attr_by_channel("y")[0].attribute, reverse=desc)
+
+
+def resolve_value(value):
+    if type(value) is str:
+        if value == "interestingness":
+            return Ordering.interestingness
+        elif value == "alphabetical_by_title":
+            return Ordering.title
+        elif value == "alphabetical_by_x":
+            return Ordering.x_alpha
+        elif value == "alphabetical_by_y":
+            return Ordering.y_alpha
+    else:
+        assert callable(value), "You must pass in a default string or a custom function."
+        return value
+
+
+class OrderingDict(collections.MutableMapping, dict):
+    def __getitem__(self, key):
+        return dict.__getitem__(self, key)
+
+    def __setitem__(self, key, value):
+        if key in lux.config.actions or key == "global":
+            dict.__setitem__(self, key, resolve_value(value))
+        else:
+            warnings.warn(
+                f"Key is not a valid action; must be one of the following: {self.actions.keys()}.",
+                stacklevel=2,
+            )
+
+    def __delitem__(self, key):
+        dict.__delitem__(self, key)
+
+    def __iter__(self):
+        return dict.__iter__(self)
+
+    def __len__(self):
+        return dict.__len__(self)
+
+    def __contains__(self, x):
+        return dict.__contains__(self, x)

lux/vis/VisList.py

@@ -25,10 +25,11 @@
 class VisList:
     """VisList is a list of Vis objects."""
 
-    def __init__(self, input_lst: Union[List[Vis], List[Clause]], source=None):
+    def __init__(self, input_lst: Union[List[Vis], List[Clause]], source=None, action=None):
         # Overloaded Constructor
         self._source = source
         self._input_lst = input_lst
+        self._action = action
         if len(input_lst) > 0:
             if self._is_vis_input():
                 self._collection = input_lst
@@ -229,18 +230,17 @@ def get_field(d_obj):
     def set(self, field_name, field_val):
         return NotImplemented
 
-    def sort(self, remove_invalid=True, descending=True):
+    def sort(self, remove_invalid=True):
         # remove the items that have invalid (-1) score
         if remove_invalid:
             self._collection = list(filter(lambda x: x.score != -1, self._collection))
-        if lux.config.sort == "none":
-            return
-        elif lux.config.sort == "ascending":
-            descending = False
-        elif lux.config.sort == "descending":
-            descending = True
-        # sort in-place by “score” by default if available, otherwise user-specified field to sort by
-        self._collection.sort(key=lambda x: x.score, reverse=descending)
+        if lux.config.sort is not None:
+            if self._action is None or lux.config.ordering_actions.get(self._action) is None:
+                ordering_function = lux.config.ordering
+            else:
+                ordering_function = lux.config.ordering_actions.get(self._action)
+            # sort in-place by “score” by default if available, otherwise user-specified field to sort by
+            ordering_function(self._collection, lux.config.sort)
 
     def showK(self):
         k = lux.config.topk