DOC documentation improvements: screenshots, better structure, introd…

…uction
eli5-org · Nov 14, 2016 · 1d8659b · 1d8659b
1 parent ea0c36d
commit 1d8659b
Show file tree

Hide file tree

Showing 18 changed files with 99 additions and 25 deletions.
diff --git a/docs/source/api/formatters.rst → docs/source/autodocs/formatters.rst b/docs/source/api/formatters.rst → docs/source/autodocs/formatters.rst
diff --git a/docs/source/api/index.rst → docs/source/autodocs/index.rst b/docs/source/api/index.rst → docs/source/autodocs/index.rst
@@ -1,7 +1,5 @@
-API documentation
-=================
-
-Autogenerated API documentation:
+Autogenerated API docs
+======================
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/api/lightning.rst → docs/source/autodocs/lightning.rst b/docs/source/api/lightning.rst → docs/source/autodocs/lightning.rst
diff --git a/docs/source/api/lime.rst → docs/source/autodocs/lime.rst b/docs/source/api/lime.rst → docs/source/autodocs/lime.rst
diff --git a/docs/source/api/sklearn.rst → docs/source/autodocs/sklearn.rst b/docs/source/api/sklearn.rst → docs/source/autodocs/sklearn.rst
diff --git a/docs/source/api/sklearn_crfsuite.rst → docs/source/autodocs/sklearn_crfsuite.rst b/docs/source/api/sklearn_crfsuite.rst → docs/source/autodocs/sklearn_crfsuite.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -13,24 +13,22 @@ Welcome to ELI5's documentation!
    :target: http://codecov.io/github/TeamHG-Memex/eli5?branch=master
    :alt: Code Coverage
 
-ELI5 is a Python library which allows to visualize and debug
+ELI5_ is a Python library which allows to visualize and debug
 various Machine Learning models using unified API. It has
 built-in support for several ML frameworks and provides a way to
 explain black-box models.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   install
    overview
+   libraries/index
+   lime
    contribute
-   api/index
+   autodocs/index
    changes
 
-Indices and tables
-==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+License is MIT.
 
+.. _ELI5: https://github.com/TeamHG-Memex/eli5
diff --git a/docs/source/install.rst b/docs/source/install.rst
diff --git a/docs/source/libraries/index.rst b/docs/source/libraries/index.rst
@@ -0,0 +1,9 @@
+Supported Libraries
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   ./sklearn
+   ./sklearn_crfsuite
+   ./lightning
diff --git a/docs/source/libraries/lightning.rst b/docs/source/libraries/lightning.rst
@@ -0,0 +1,4 @@
+lightning
+=========
+
+TODO
diff --git a/docs/source/libraries/sklearn.rst b/docs/source/libraries/sklearn.rst
@@ -0,0 +1,4 @@
+scikit-learn
+============
+
+TODO
diff --git a/docs/source/libraries/sklearn_crfsuite.rst b/docs/source/libraries/sklearn_crfsuite.rst
@@ -0,0 +1,4 @@
+sklearn-crfsuite
+================
+
+TODO
diff --git a/docs/source/lime.rst b/docs/source/lime.rst
@@ -0,0 +1,2 @@
+LIME
+====
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
@@ -1,7 +1,20 @@
 Overview
 ========
 
-ELI5 is a Python package which helps to debug machine learning
+Installation
+------------
+
+ELI5 works in Python 2.7 and Python 3.4+. Currently it requires
+scikit-learn 0.18+, so make sure scikit-learn is installed first,
+then install eli5 using pip::
+
+    pip install 'scikit-learn > 0.18'
+    pip install eli5
+
+Features
+--------
+
+ELI5_ is a Python package which helps to debug machine learning
 classifiers and explain their predictions. It provides support for the
 following machine learning frameworks and packages:
 
@@ -31,5 +44,57 @@ rendering and formatting on a client.
 .. _scikit-learn: https://github.com/scikit-learn/scikit-learn
 .. _sklearn-crfsuite: https://github.com/TeamHG-Memex/sklearn-crfsuite
 .. _LIME: http://arxiv.org/abs/1602.04938
+.. _ELI5: https://github.com/TeamHG-Memex/eli5
+
+Basic Usage
+-----------
+
+There are two main ways to look at a classification or a regression model:
+
+1. inspect model parameters and try to figure out how the model works
+   globally;
+2. inspect an individual prediction of a model, try to figure out why
+   the model makes the decision it makes.
+
+For (1) ELI5 provides ``eli5.explain_weights`` function; for (2) it provides
+``eli5.explain_prediction`` function.
+
+If the ML library you're working with is supported then you usually
+can enter the following in IPython Notebook::
+
+    import eli5
+    eli5.explain_weights(clf)
+
+and get an explanation like this:
+
+.. image:: static/weights.png
+
+Supported arguments and the exact way the classifier is visualized depends
+on a library.
+
+To explain an individual prediction (2) use ``eli5.explain_prediction``
+function. Exact parameters depend on a classifier and on input data kind
+(text, tabular, images). For example, you may get text highlighted like this
+if you're using one of the scikit-learn_ vectorizers with char ngrams:
+
+.. image:: static/char-ngrams.png
+
+
+Why?
+----
+
+For some of classifiers inspection and debugging is easy, for others
+this is hard. It is not a rocket science to take coefficients
+of a linear classifier, relate them to feature names and show in
+an HTML table. ELI5 aims to handle not only simple cases,
+but even for simple cases having unified API for inspection has a value:
 
-License is MIT.
+* you can call a ready-made function from ELI5 and get a nicely formatted
+  result immediately;
+* formatting code can be reused between machine learning frameworks;
+* 'drill down' code like feature filtering or text highlighting can be reused;
+* there are lots of gotchas and small differences which ELI5 takes care of;
+* algorithms like LIME_ try to explain a black-box classifier
+  through a locally-fit simple, interpretable classifier. It means that
+  with each additional supported "simple" classifier/regressor
+  algorithms like LIME are getting more options automatically.
diff --git a/docs/source/static/char-ngrams.png b/docs/source/static/char-ngrams.png
diff --git a/docs/source/static/crf.png b/docs/source/static/crf.png
diff --git a/docs/source/static/weights.png b/docs/source/static/weights.png
diff --git a/docs/source/static/word-highlight.png b/docs/source/static/word-highlight.png