updated docs

oegedijk · Sep 27, 2020 · 6eb3a1f · 6eb3a1f
1 parent 6af36e7
commit 6eb3a1f
Show file tree

Hide file tree

Showing 9 changed files with 56 additions and 67 deletions.
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 # explainerdashboard
 by: Oege Dijk
 
-This package makes it convenient to quickly explain the workings of a (scikit-learn compatible)
+This python package makes it convenient to quickly explain the workings of a (scikit-learn compatible)
 fitted machine learning model using either interactive plots in e.g. Jupyter Notebook or 
 deploying an interactive dashboard (based on Flask/Dash) that allows you to quickly explore
 the impact of different features on model predictions. Example deployed at: [titanicexplainer.herokuapp.com](http://titanicexplainer.herokuapp.com), detailed documentation at [explainerdashboard.readthedocs.io](http://explainerdashboard.readthedocs.io), example notebook on how to launch dashboard for different models [here](https://github.com/oegedijk/explainerdashboard/blob/master/dashboard_examples.ipynb), and an example notebook on how to interact with the explainer object [here](https://github.com/oegedijk/explainerdashboard/blob/master/explainer_examples.ipynb).
@@ -26,7 +26,7 @@ The library includes:
 - *Permutation importances* (how much does the model metric deteriorate when you shuffle a feature?)
 - *Partial dependence plots* (how does the model prediction change when you vary a single feature?
 - *Shap interaction values* (decompose the shap value into a direct effect an interaction effects)
-- For Random Forests: what is the prediction of each *individual decision tree*, and what is the path through each tree? (using `dtreeviz`)
+- For Random Forests and xgboost models: what is the prediction of each *individual decision tree*, and what is the path through each tree? (using `dtreeviz`)
 - Plus for classifiers: precision plots, confusion matrix, ROC AUC plot, PR AUC plot, etc
 - For regression models: goodness-of-fit plots, residual plots, etc. 
 
@@ -54,7 +54,7 @@ train_names, test_names = titanic_names()
 model = RandomForestClassifier(n_estimators=50, max_depth=5)
 model.fit(X_train, y_train)
 
-explainer = RandomForestClassifierExplainer(model, X_test, y_test, 
+explainer = ClassifierExplainer(model, X_test, y_test, 
                                 cats=['Sex', 'Deck', 'Embarked'],
                                 idxs=test_names, 
                                 labels=['Not survived', 'Survived'])
@@ -70,8 +70,9 @@ db.run(port=8051)
 
 ```
 
-When working inside jupyter you can use `JupyterExplainerDashboard()` instead
-to use `JupyterDash` instead of `dash.Dash()` to start the app.
+When working inside jupyter or Google Colab you can use `ExplainerDashboard(mode='inline')` 
+or `ExplainerDashboard(mode='external')` instead to use `JupyterDash` instead of 
+`dash.Dash()` to start the app.
 
 You can also use e.g. `InlineExplainer(explainer).tab.dependence()` to see a 
 single specific tab or component inline in your notebook. 
@@ -123,7 +124,7 @@ train_names, test_names = titanic_names()
 model = RandomForestClassifier(n_estimators=50, max_depth=5)
 model.fit(X_train, y_train)
 
-explainer = RandomForestClassifierExplainer(model, X_test, y_test, 
+explainer = ClassifierExplainer(model, X_test, y_test, 
                                 X_background=None, model_output='probability',
                                 cats=['Sex', 'Deck', 'Embarked'],
                                 idxs=test_names, 

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -3,16 +3,22 @@
 ## Version 0.2.3
 
 ### Breaking Changes
-- 
+- RandomForestClassifierExplainer and RandomForestRegressionExplainer will be 
+    deprecated: can now simply use ClassifierExplainer or RegressionExplainer and the
+    mixin class will automatically be loaded.
 - 
 
 ### New Features
-- Now also support for visualizing individual XGBoost trees with the new
-    XGBCLassifierExplainer and XGBRegressionExplainer. 
+- Now also support for visualizing individual trees for XGBoost models!
+    (XGBClassifier and XGBRegressor). The XGBExplainer mixin class will be 
+    automatically loaded and make decisiontree_df(), decision_path() and plot_trees()
+    methods available, Decision Trees tab and components now also work for
+    XGBoost models. 
 - new parameter n_jobs for calculations that can be parallelized (e.g. permutation importances)
 - contrib_df, plot_shap_contributions: can order by global shap feature 
-    'importance' (as well as 'abs', 'high-to-low' and 'low-to-high')
-- added actual outcome to plot_trees
+    importance with sort='importance' (as well as 'abs', 'high-to-low' 
+     'low-to-high')
+- added actual outcome to plot_trees (for both RandomForest and XGB)
 
 ### Bug Fixes
 -

diff --git a/docs/source/deployment.rst b/docs/source/deployment.rst
@@ -27,7 +27,7 @@ The code below is from `the deployed example to heroku <https://github.com/oeged
     model = RandomForestClassifier(n_estimators=50, max_depth=5)
     model.fit(X_train, y_train)
 
-    explainer = RandomForestClassifierExplainer(model, X_test, y_test, 
+    explainer = ClassifierExplainer(model, X_test, y_test, 
                                 cats=['Sex', 'Deck', 'Embarked'],
                                 idxs=test_names, 
                                 labels=['Not survived', 'Survived'])

diff --git a/docs/source/explainers.rst b/docs/source/explainers.rst
@@ -5,15 +5,12 @@ Simple example
 ==============
 
 In order to start an ``ExplainerDashboard`` you first need to construct an 
-``Explainer`` instance. They come in six flavours and at its most basic they 
+``Explainer`` instance. They come in two flavours and at its most basic they 
 only need a model, and a test set X and y::
 
     explainer = ClassifierExplainer(model, X_test, y_test)
     explainer = RegressionExplainer(model, X_test, y_test)
     explainer = RandomForestClassifierExplainer(model, X_test, y_test)
-    explainer = RandomForestRegressionExplainer(model, X_test, y_test)
-    explainer = XGBClassifierExplainer(model, X_test, y_test)
-    explainer = XGBRegressionExplainer(model, X_test, y_test)
 
 This is enough to launch an ExplainerDashboard::
 
@@ -361,14 +358,9 @@ And for dtreeviz visualization of individual decision trees (svg format)::
     explainer.decision_path_file(tree_idx, index)
     explainer.decision_path_encoded(tree_idx, index)
 
-These methods are not available with the standard ``ClassifierExplainer`` and 
-``RegressionExplainer`` classes so you need to instantiate with the specific
-Explainer classes for these models::
-
-    explainer = RandomForestClassifierExplainer(model, X, y)
-    explainer = RandomForestRegressionExplainer(model, X, y)
-    explainer = XGBClassifierExplainer(model, X, y)
-    explainer = XGBRegressionExplainer(model, X, y)
+These methods are part of the ``RandomForestExplainer`` and XGBExplainer`` mixin
+classes that get automatically loaded when you pass either a RandomForest
+or XGBoost model.
 
 
 plot_trees
@@ -514,14 +506,18 @@ random_index
 .. automethod:: explainerdashboard.explainers.RegressionExplainer.random_index
 
 
-RandomForest outputs
---------------------
+RandomForest and XGBoost outputs
+-------------------------------
 
-For ``RandomForestExplainer``::
+For RandomForest and XGBoost models mixin classes that visualize individual 
+decision trees will be loaded: ``RandomForestExplainer`` and ``XGBExplainer``
+with the following additional methods::
 
     decisiontree_df(tree_idx, index, pos_label=None)
     decisiontree_summary_df(tree_idx, index, round=2, pos_label=None)
     decision_path_file(tree_idx, index)
+    decision_path_encoded(tree_idx, index)
+    decision_path(tree_idx, index)
 
 
 decisiontree_df
@@ -539,6 +535,17 @@ decision_path_file
 
 .. automethod:: explainerdashboard.explainers.RandomForestExplainer.decision_path_file
 
+decision_path_encoded
+^^^^^^^^^^^^^^^^^^^^^
+
+.. automethod:: explainerdashboard.explainers.RandomForestExplainer.decision_path_encoded
+
+decision_path
+^^^^^^^^^^^^^
+
+.. automethod:: explainerdashboard.explainers.RandomForestExplainer.decision_path
+
+
 Calculated Properties
 =====================
 
@@ -664,29 +671,16 @@ The ``RandomForestExplainer`` mixin class provides additional functionality
 in order to explore individual decision trees within the RandomForest.
 This can be very useful for showing stakeholders that a RandomForest is
 indeed just a collection of simple decision trees that you then calculate
-the average off. 
+the average off. This Mixin class will be automatically included
+whenever you pass a ``RandomForestClassifier`` or ``RandomForestRegressor`` model.
 
 .. autoclass:: explainerdashboard.explainers.RandomForestExplainer
    :members: decisiontree_df, decisiontree_summary_df, plot_trees, decision_path
    :member-order: bysource
    :exclude-members: 
    :noindex:
 
-RandomForestClassifierExplainer
--------------------------------
 
-.. autoclass:: explainerdashboard.explainers.RandomForestClassifierExplainer
-   :member-order: bysource
-   :exclude-members: __init__
-   :noindex:
-
-RandomForestRegressionExplainer
--------------------------------
-
-.. autoclass:: explainerdashboard.explainers.RandomForestRegressionExplainer
-   :member-order: bysource
-   :exclude-members: __init__
-   :noindex:
 
 
 XGBExplainer
@@ -696,6 +690,8 @@ The ``XGBExplainer`` mixin class provides additional functionality
 in order to explore individual decision trees within an xgboost ensemble model.
 This can be very useful for showing stakeholders that a xgboost is
 indeed just a collection of simple decision trees that get summed together. 
+This Mixin class will be automatically included
+whenever you pass a ``XGBClassifier`` or ``XGBRegressor`` model.
 
 
 .. autoclass:: explainerdashboard.explainers.XGBExplainer
@@ -704,21 +700,7 @@ indeed just a collection of simple decision trees that get summed together.
    :exclude-members: 
    :noindex:
 
-XGBClassifierExplainer
-----------------------
 
-.. autoclass:: explainerdashboard.explainers.XGBClassifierExplainer
-   :member-order: bysource
-   :exclude-members: __init__
-   :noindex:
-
-XGBRegressionExplainer
-----------------------
-
-.. autoclass:: explainerdashboard.explainers.XGBRegressionExplainer
-   :member-order: bysource
-   :exclude-members: __init__
-   :noindex:
 
 
 
diff --git a/docs/source/help.rst b/docs/source/help.rst
@@ -1,3 +1,3 @@
 Help
 ====
-Question? Please contact [email protected]
+Question? Please contact [email protected] or open an issue on github: https://github.com/oegedijk/explainerdashboard/issues
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -58,7 +58,7 @@ pass it on to an ``ExplainerDashboard`` and run the dashboard::
 
     from sklearn.ensemble import RandomForestClassifier
 
-    from explainerdashboard.explainers import RandomForestClassifierExplainer
+    from explainerdashboard.explainers import ClassifierExplainer
     from explainerdashboard.dashboards import ExplainerDashboard
     from explainerdashboard.datasets import titanic_survive, titanic_names
 

diff --git a/tests/test_randomforest.py b/tests/test_randomforest.py
diff --git a/tests/test_randomforest_explainer.py b/tests/test_randomforest_explainer.py
@@ -9,8 +9,8 @@
 import plotly.graph_objects as go
 import dtreeviz 
 
-from explainerdashboard.explainers import RandomForestRegressionExplainer
-from explainerdashboard.explainers import RandomForestClassifierExplainer
+from explainerdashboard.explainers import RegressionExplainer
+from explainerdashboard.explainers import ClassifierExplainer
 from explainerdashboard.datasets import titanic_survive, titanic_fare, titanic_names
 
 
@@ -23,7 +23,7 @@ def setUp(self):
         model = RandomForestClassifier(n_estimators=5, max_depth=2)
         model.fit(X_train, y_train)
 
-        self.explainer = RandomForestClassifierExplainer(
+        self.explainer = ClassifierExplainer(
                             model, X_test, y_test, roc_auc_score, 
                             shap='tree',
                             cats=['Sex', 'Cabin', 'Embarked'],
@@ -70,7 +70,7 @@ def setUp(self):
         model = RandomForestRegressor(n_estimators=5, max_depth=2)
         model.fit(X_train, y_train)
 
-        self.explainer = RandomForestRegressionExplainer(
+        self.explainer = RegressionExplainer(
                             model, X_test, y_test, r2_score, 
                             shap='tree',
                             cats=['Sex', 'Cabin', 'Embarked'],

diff --git a/tests/test_xgboost_explainer.py b/tests/test_xgboost_explainer.py
@@ -8,8 +8,8 @@
 import plotly.graph_objects as go
 import dtreeviz 
 
-from explainerdashboard.explainers import XGBRegressionExplainer
-from explainerdashboard.explainers import XGBClassifierExplainer
+from explainerdashboard.explainers import RegressionExplainer
+from explainerdashboard.explainers import ClassifierExplainer
 from explainerdashboard.datasets import *
 
 
@@ -22,7 +22,7 @@ def setUp(self):
         model = XGBClassifier(n_estimators=5)
         model.fit(X_train, y_train)
 
-        self.explainer = XGBClassifierExplainer(
+        self.explainer = ClassifierExplainer(
                             model, X_test, y_test, 
                             cats=['Sex', 'Cabin', 'Embarked'],
                             idxs=test_names, 
@@ -65,7 +65,7 @@ def setUp(self):
         model = XGBClassifier(n_estimators=5)
         model.fit(X_train, y_train)
 
-        self.explainer = XGBClassifierExplainer(
+        self.explainer = ClassifierExplainer(
                             model, X_test, y_test, model_output='raw',
                             cats=['Sex', 'Cabin', 'Embarked'],
                             idxs=test_names, 
@@ -118,7 +118,7 @@ def setUp(self):
         model = XGBRegressor(n_estimators=5, max_depth=2)
         model.fit(X_train, y_train)
 
-        self.explainer = XGBRegressionExplainer(
+        self.explainer = RegressionExplainer(
                             model, X_test, y_test, 
                             cats=['Sex', 'Cabin', 'Embarked'],
                             idxs=test_names)