Parcoords (#60)

* version-zero

* notebook

* update

* black

* parcoords

* moar

* moar

* docs

* version-update

* black

Author: koaning

docs/api/interactive-charts.md

@@ -1,3 +1,7 @@
 # `InteractiveCharts`
 
 ::: hulearn.experimental.InteractiveCharts
+
+# `parallel_coordinates`
+
+::: hulearn.experimental.parallel_coordinates

docs/guide/function-classifier/function-classifier.md

@@ -138,10 +138,69 @@ grid = GridSearchCV(mod,
 grid.fit(X, y)
 ```
 
+## Guidance
+
+Human Learn doesn't just allow you to turn functions into classifiers. It also tries
+to help you find rules that could be useful. In particular, an interactive parallel
+coordinates chart could be very helpful here.
+
+You can create a parallel coordinates chart directly inside of jupyter.
+
+```python
+from hulearn.experimental.interactive import parallel_coordinates
+parallel_coordinates(df, label="survived", height=200)
+```
+
+What follows next are some explorations of the dataset. They are based on the scene
+from the titanic movie where they yell "Woman and Children First!". So let's see if
+we can confirm if this holds true.
+
+### Explore
+
+![](parcoords1.gif)
+
+It indeed seems that women in 1st/2nd class have a high chance of surviving.
+
+![](parcoords2.gif)
+
+It also seems that male children have an increased change of survival, but only
+if they were travelling 1st/2nd class.
+
+### Grid
+
+Here's a lovely observation. By doing exploratory analysis we not only understand the
+data better but we can now also turn the patterns that we've observed into a model!
+
+```python
+def make_prediction(dataf, age=15):
+    women_rule = (dataf['pclass'] < 3.0) & (dataf['sex'] == "female")
+    children_rule = (dataf['pclass'] < 3.0) & (dataf['age'] <= age)
+    return women_rule | children_rule
+
+mod = FunctionClassifier(make_prediction)
+```
+
+We're even able to use grid-search again to find the optimal threshold for `"age"`.
+
+### Comparison
+
+To compare our results we've also trained a `RandomForestClassifier`.
+Here's how the models compare;
+
+|Model | accuracy | precision  | recall|
+---    | ---      | ---        | ---
+|Women & Children Rule |0.808157	| 0.952168 | 0.558621
+|RandomForestClassifier|0.813869	| 0.785059 | 0.751724
+
+It seems like our rule based model is quite reasonable. A great follow-up exercise
+would be to try and understand when the random forest model disagrees with the rule
+based system. This could lead us to understand more patterns in the data.
+
 ## Conclusion
 
-In this guide we've seen the `FunctionClassifier`. It is one of the many models in this
-library that will help you construct more "human" models.
+In this guide we've seen the `FunctionClassifier` in action. It is one of the many
+models in this  library that will help you construct more "human" models. This component
+is very effective when it is combined with exploratory data analysis techniques.
 
 ### Notebook
 

docs/guide/function-classifier/parcoords1.gif

@@ -1 +1 @@
-[{"chart_id": "397ffa01-1", "x": "bill_length_mm", "y": "bill_depth_mm", "polygons": {"Adelie": {"bill_length_mm": [], "bill_depth_mm": []}, "Gentoo": {"bill_length_mm": [], "bill_depth_mm": []}, "Chinstrap": {"bill_length_mm": [], "bill_depth_mm": []}}}, {"chart_id": "71f2c74d-0", "x": "flipper_length_mm", "y": "body_mass_g", "polygons": {"Adelie": {"flipper_length_mm": [], "body_mass_g": []}, "Gentoo": {"flipper_length_mm": [], "body_mass_g": []}, "Chinstrap": {"flipper_length_mm": [], "body_mass_g": []}}}]
+[{"chart_id": "3fe365af-2", "x": "bill_length_mm", "y": "bill_depth_mm", "polygons": {"Adelie": {"bill_length_mm": [], "bill_depth_mm": []}, "Gentoo": {"bill_length_mm": [], "bill_depth_mm": []}, "Chinstrap": {"bill_length_mm": [], "bill_depth_mm": []}}}, {"chart_id": "d89db41b-0", "x": "flipper_length_mm", "y": "body_mass_g", "polygons": {"Adelie": {"flipper_length_mm": [], "body_mass_g": []}, "Gentoo": {"flipper_length_mm": [], "body_mass_g": []}, "Chinstrap": {"flipper_length_mm": [], "body_mass_g": []}}}]

docs/guide/function-classifier/parcoords2.gif

@@ -1 +1 @@
-__version__ = "0.2.5"
+__version__ = "0.3.0"

docs/guide/notebooks/01-function-classifier.ipynb

@@ -66,11 +66,11 @@ def predict(self, X):
         return self.func(X, **self.kwargs)
 
     def get_params(self, deep=True):
-        """"""
+        """ """
         return {**self.kwargs, "func": self.func}
 
     def set_params(self, **params):
-        """"""
+        """ """
         for k, v in params.items():
             if k == "func":
                 self.func = v

docs/guide/notebooks/demo_data.json

@@ -1,3 +1,3 @@
-from .interactive import InteractiveCharts
+from .interactive import InteractiveCharts, parallel_coordinates
 
-__all__ = ["InteractiveCharts"]
+__all__ = ["InteractiveCharts", "parallel_coordinates"]

hulearn/__init__.py

@@ -1,7 +1,12 @@
+import os
 import uuid
+import random
+import pathlib
+from string import Template
 from pkg_resources import resource_filename
 
 from clumper import Clumper
+from IPython.core.display import HTML
 from bokeh.models import ColumnDataSource
 from bokeh.plotting import figure, show
 from bokeh.models import PolyDrawTool, PolyEditTool
@@ -217,3 +222,58 @@ def data(self):
                 for k, v in self.poly_patches.items()
             },
         }
+
+
+def _random_string():
+    """Generates a random HTML id for d3 charts."""
+    return "".join([random.choice("qwertyuiopasdfghjklzxcvbnm") for _ in range(6)])
+
+
+def parallel_coordinates(dataf, label, height=200):
+    """
+    Creates an interactive parallel coordinates chart to help with classification tasks.
+
+    Arguments:
+        dataf: the dataframe to render
+        label: the column that represents the label, will be used for coloring
+        height: the height of the chart, in pixels
+
+    Usage:
+
+    ```python
+    from hulearn.datasets import load_titanic
+    from hulearn.experimental.interactive import parallel_coordinates
+
+    df = load_titanic(as_frame=True)
+    parallel_coordinates(df, label="survived", height=200)
+    ```
+    """
+    t = Template(
+        pathlib.Path(
+            resource_filename(
+                "hulearn", os.path.join("static", "parcoords", "template.html")
+            )
+        ).read_text()
+    )
+    d3_blob_path = resource_filename(
+        "hulearn", os.path.join("static", "parcoords", "d3.min.js")
+    )
+    css_blob_path = resource_filename(
+        "hulearn", os.path.join("static", "parcoords", "d3.parcoords.css")
+    )
+    js_blob_path = resource_filename(
+        "hulearn", os.path.join("static", "parcoords", "d3.parcoords.js")
+    )
+
+    json_data = dataf.rename(columns={label: "label"}).to_json(orient="records")
+    rendered = t.substitute(
+        {
+            "data": json_data,
+            "id": _random_string(),
+            "style": pathlib.Path(css_blob_path).read_text(),
+            "d3_blob": pathlib.Path(d3_blob_path).read_text(),
+            "parcoords_stuff": pathlib.Path(js_blob_path).read_text(),
+            "height": f"{height}px",
+        }
+    )
+    return HTML(rendered)

hulearn/classification/functionclassifier.py

@@ -45,11 +45,11 @@ def predict(self, X):
         return self.func(X, **self.kwargs)
 
     def get_params(self, deep=True):
-        """"""
+        """ """
         return {**self.kwargs, "func": self.func}
 
     def set_params(self, **params):
-        """"""
+        """ """
         for k, v in params.items():
             if k == "func":
                 self.func = v

hulearn/experimental/__init__.py

@@ -92,11 +92,11 @@ def transform(self, X):
         return self.func(X, **self.kwargs)
 
     def get_params(self, deep=True):
-        """"""
+        """ """
         return {**self.kwargs, "func": self.func}
 
     def set_params(self, **params):
-        """"""
+        """ """
         for k, v in params.items():
             if k == "func":
                 self.func = v

hulearn/experimental/interactive.py

@@ -43,11 +43,11 @@ def predict(self, X):
         return self.func(X, **self.kwargs)
 
     def get_params(self, deep=True):
-        """"""
+        """ """
         return {**self.kwargs, "func": self.func}
 
     def set_params(self, **params):
-        """"""
+        """ """
         for k, v in params.items():
             if k == "func":
                 self.func = v

hulearn/outlier/functionoutlier.py

@@ -0,0 +1,26 @@
+Copyright (c) 2012, Kai Chang
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* The name Kai Chang may not be used to endorse or promote products
+  derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL MICHAEL BOSTOCK BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

hulearn/preprocessing/pipetransformer.py

@@ -0,0 +1,32 @@
+.parcoords > canvas {
+  font: 14px sans-serif;
+  position: absolute;
+}
+.parcoords > canvas {
+  pointer-events: none;
+}
+.parcoords text.label {
+  cursor: default;
+}
+.parcoords rect.background:hover {
+  fill: rgba(120,120,120,0.2);
+}
+.parcoords canvas {
+  opacity: 1;
+  transition: opacity 0.3s;
+  -moz-transition: opacity 0.3s;
+  -webkit-transition: opacity 0.3s;
+  -o-transition: opacity 0.3s;
+}
+.parcoords canvas.faded {
+  opacity: 0.25;
+}
+.parcoords {
+  -webkit-touch-callout: none;
+  -webkit-user-select: none;
+  -khtml-user-select: none;
+  -moz-user-select: none;
+  -ms-user-select: none;
+  user-select: none;
+  background-color: white;
+}