better doc

AUTHORS.rst

@@ -10,4 +10,7 @@ Development Lead
 Contributors
 ------------
 
-None yet. Why not be the first?
+* Ludmila Exbrayat
+* Amelie Meurer
+* Antoine Redier
+* Ines Vanagt

README.rst

@@ -13,20 +13,85 @@ trelawney
         :target: https://trelawney.readthedocs.io/en/latest/?badge=latest
         :alt: Documentation Status
 
+.. image:: https://img.shields.io/github/license/skanderkam/trelawney
+        :alt: MIT License
 
 
 
-Generic Interpretability package
+Trelawney is a general interpretability package that aims at providing a common api to use most of the modern
+interpretability methods to shed light on sklearn compatible models (support for Keras and XGBoost are tested).
 
+Trelawney will try to provide you with two kind of explanation when possible:
 
-* Free software: MIT license
-* Documentation: https://trelawney.readthedocs.io.
+- global explanation of the model that highlights the most importance features the model uses to make its
+  predictions globally
+- local explanation of the model that will try to shed light on why a specific model made a specific prediction
 
+The Trelawney package is build around:
 
-Features
---------
+- some model specific explainers that use the inner workings of some types of models to explain them:
+   - `LogRegExplainer` that uses the weights of the your logistic regression to produce global and local explanations of
+     your model
+   - `TreeExplainer` that uses the path of your tree (single tree model only) to produce explanations of the model
+
+- Some model agnostic explainers that should work with all models:
+   - `LimeExplainer` that uses the Lime_ package to create local explanations only (the local nature of Lime prohibits
+     it from generating global explanations of a model
+   - `ShapExplainer` that uses the SHAP_ package to create local and global explanations of your model
+   - `SurrogateExplainer` that creates a general surogate of your model (fitted on the output of your model) using an
+     explainable model (`DecisionTreeClassifier`,`LogisticRegression` for now). The explainer will then use the
+     internals of the surrogate model to explain your black box model as well as informing you on how well the surrogate
+     model explains the black box one
+
+Quick Tutorial (30s to Trelawney):
+__________________________________
+
+Here is an example of how to use a Trelawney explainer
+
+    >>> model = LogisticRegression().fit(X, y)
+    >>> # creating and fiting the explainer
+    >>> explainer = ShapExplainer()
+    >>> explainer.fit(model, X, y)
+    >>> # explaining observation
+    >>> explanation =  explainer.explain_local(X_expain)
+    [
+        {'var_1': 0.1, 'var_2': -0.07, ...},
+        ...
+        {'var_1': 0.23, 'var_2': -0.15, ...} ,
+    ]
+    >>> explanation =  explainer.graph_local_explanation(X_expain.iloc[:1, :])
+
+.. image:: http://drive.google.com/uc?export=view&id=1a1kdH8mjGdKiiF_JHR56L2-JeaRStwr2
+   :width: 400
+   :alt: Local Explanation Graph
+
+To do local explanations
+
+    >>> explanation =  explainer.feature_importance(X_expain)
+    {'var_1': 0.5, 'var_2': 0.2, ...} ,
+    >>> explanation =  explainer.graph_feature_importance(X_expain)
+
+
+.. image:: http://drive.google.com/uc?export=view&id=1R2NFEU0bcZYpeiFsLZDKYfPkjHz-cHJ_
+   :width: 400
+   :alt: Local Explanation Graph
+
+FAQ
+___
+
+   Why should I use Trelawney rather than Lime_ and SHAP_
+
+while you can definitally use the Lime and SHAP packages directly (they will give you more control over how to use their
+packages), they are very specialized packages with different APIs, graphs and vocabulary. Trelawnaey offers you a
+unified API, representation and vocabulary for all state of the art explanation methods so that you don't lose time
+adapting to each new method but just change a class and Trelawney will adapt to you.
+
+Comming Soon
+------------
+
+* Regressor Support (PR welcome)
+* Image and text Support (PR welcome)
 
-* TODO
 
 Credits
 -------
@@ -35,3 +100,5 @@ This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypack
 
 .. _Cookiecutter: https://github.com/audreyr/cookiecutter
 .. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
+.. _SHAP: https://github.com/slundberg/shap
+.. _Lime: https://github.com/marcotcr/lime

docs/index.rst

@@ -5,14 +5,14 @@ Welcome to trelawney's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   readme
    installation
-   usage
    modules
    contributing
    authors
    history
 
+.. include:: ../README.rst
+
 Indices and tables
 ==================
 * :ref:`genindex`

docs/trelawney.rst

@@ -12,6 +12,14 @@ trelawney.base\_explainer module
     :undoc-members:
     :show-inheritance:
 
+trelawney.colors module
+-----------------------
+
+.. automodule:: trelawney.colors
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 trelawney.lime\_explainer module
 --------------------------------
 
@@ -20,6 +28,14 @@ trelawney.lime\_explainer module
     :undoc-members:
     :show-inheritance:
 
+trelawney.logreg\_explainer module
+----------------------------------
+
+.. automodule:: trelawney.logreg_explainer
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 trelawney.shap\_explainer module
 --------------------------------
 
@@ -28,6 +44,14 @@ trelawney.shap\_explainer module
     :undoc-members:
     :show-inheritance:
 
+trelawney.surrogate\_explainer module
+-------------------------------------
+
+.. automodule:: trelawney.surrogate_explainer
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 trelawney.tree\_explainer module
 --------------------------------