[MRG] DOC Add example about interpretation of coefficients of linear …

…models (scikit-learn#15706)



Co-authored-by: Nicolas Hug <contact@nicolas-hug.com>
Co-authored-by: Gael Varoquaux <gael.varoquaux@normalesup.org>
Co-authored-by: Joel Nothman <joel.nothman@gmail.com>
Co-authored-by: Guillaume Lemaitre <g.lemaitre58@gmail.com>

README.rst

@@ -58,7 +58,8 @@ scikit-learn 0.23 and later require Python 3.6 or newer.
 Scikit-learn plotting capabilities (i.e., functions start with ``plot_``
 and classes end with "Display") require Matplotlib (>= 2.1.1). For running the
 examples Matplotlib >= 2.1.1 is required. A few examples require
-scikit-image >= 0.13, a few examples require pandas >= 0.18.0.
+scikit-image >= 0.13, a few examples require pandas >= 0.18.0, some examples
+require seaborn >= 0.9.0.
 
 User installation
 ~~~~~~~~~~~~~~~~~

build_tools/circle/build_doc.sh

@@ -169,7 +169,7 @@ conda create -n $CONDA_ENV_NAME --yes --quiet python="${PYTHON_VERSION:-*}" \
   cython="${CYTHON_VERSION:-*}" pytest coverage \
   matplotlib="${MATPLOTLIB_VERSION:-*}" sphinx=2.1.2 pillow \
   scikit-image="${SCIKIT_IMAGE_VERSION:-*}" pandas="${PANDAS_VERSION:-*}" \
-  joblib memory_profiler packaging
+  joblib memory_profiler packaging seaborn
 
 source activate testenv
 pip install sphinx-gallery

doc/conf.py

@@ -250,6 +250,7 @@
     'matplotlib': ('https://matplotlib.org/', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
     'joblib': ('https://joblib.readthedocs.io/en/latest/', None),
+    'seaborn': ('https://seaborn.pydata.org/', None),
 }
 
 v = parse(release)

doc/developers/contributing.rst

@@ -553,7 +553,8 @@ the development version.
 
 Building the documentation requires installing some additional packages::
 
-    pip install sphinx sphinx-gallery numpydoc matplotlib Pillow pandas scikit-image packaging
+    pip install sphinx sphinx-gallery numpydoc matplotlib Pillow pandas \
+                scikit-image packaging seaborn
 
 To build the documentation, you need to be in the ``doc`` folder::
 

doc/inspection.rst

@@ -17,6 +17,10 @@ predictions from a model and what affects them. This can be used to
 evaluate assumptions and biases of a model, design a better model, or
 to diagnose issues with model performance.
 
+.. topic:: Examples:
+
+   * :ref:`sphx_glr_auto_examples_inspection_plot_linear_model_coefficient_interpretation.py`
+
 .. toctree::
 
     modules/partial_dependence

doc/install.rst

@@ -134,7 +134,8 @@ it as ``scikit-learn[alldeps]``.
 Scikit-learn plotting capabilities (i.e., functions start with "plot\_"
 and classes end with "Display") require Matplotlib (>= 2.1.1). For running the
 examples Matplotlib >= 2.1.1 is required. A few examples require
-scikit-image >= 0.13, a few examples require pandas >= 0.18.0.
+scikit-image >= 0.13, a few examples require pandas >= 0.18.0, some examples
+require seaborn >= 0.9.0.
 
 .. warning::
 

doc/modules/linear_model.rst

@@ -146,7 +146,7 @@ a linear kernel.
 
    * :ref:`sphx_glr_auto_examples_linear_model_plot_ridge_path.py`
    * :ref:`sphx_glr_auto_examples_text_plot_document_classification_20newsgroups.py`
-
+   * :ref:`sphx_glr_auto_examples_inspection_plot_linear_model_coefficient_interpretation.py`
 
 Ridge Complexity
 ----------------
@@ -232,6 +232,7 @@ computes the coefficients along the full path of possible values.
 
   * :ref:`sphx_glr_auto_examples_linear_model_plot_lasso_and_elasticnet.py`
   * :ref:`sphx_glr_auto_examples_applications_plot_tomography_l1_reconstruction.py`
+  * :ref:`sphx_glr_auto_examples_inspection_plot_linear_model_coefficient_interpretation.py`
 
 
 .. note:: **Feature selection with Lasso**

doc/themes/scikit-learn-modern/static/css/theme.css

@@ -963,6 +963,44 @@ div.sphx-glr-thumbcontainer {
   }
 }
 
+/* Pandas dataframe css */
+/* Taken from: https://github.com/spatialaudio/nbsphinx/blob/fb3ba670fc1ba5f54d4c487573dbc1b4ecf7e9ff/src/nbsphinx.py#L587-L619 */
+/* FIXME: to be removed when sphinx-gallery >= 5.0 will be released */
+
+table.dataframe {
+  border: none !important;
+  border-collapse: collapse;
+  border-spacing: 0;
+  border-color: transparent;
+  color: black;
+  font-size: 12px;
+  table-layout: fixed;
+}
+table.dataframe thead {
+  border-bottom: 1px solid black;
+  vertical-align: bottom;
+}
+table.dataframe tr,
+table.dataframe th,
+table.dataframe td {
+  text-align: right;
+  vertical-align: middle;
+  padding: 0.5em 0.5em;
+  line-height: normal;
+  white-space: normal;
+  max-width: none;
+  border: none;
+}
+table.dataframe th {
+  font-weight: bold;
+}
+table.dataframe tbody tr:nth-child(odd) {
+  background: #f5f5f5;
+}
+table.dataframe tbody tr:hover {
+  background: rgba(66, 165, 245, 0.2);
+}
+
 /* rellinks */
 
 .sk-btn-rellink {