BCG-X-Official · jason-bentley · Oct 13, 2020 · Oct 12, 2020 · Oct 12, 2020 · Oct 12, 2020
diff --git a/README.rst b/README.rst
@@ -6,7 +6,9 @@
 model inspection and model-based simulation to enable better explanations of your
 machine learning models.
 
-TODO - add git badges as substitutions
+|azure_pypi| |azure_conda| |azure_devops_master_ci| |code_cov|
+|python_versions| |code_style| |documentation_status|
+|made_with_sphinx_doc| |License_badge|
 
 Installation
 ---------------------
@@ -233,3 +235,23 @@ The `shap <https://github.com/slundberg/shap>`_ implementation is used to estima
 shapley vectors which are being decomposed into the synergy, redundancy, and
 independence vectors.
 
+.. |azure_conda| image::
+    :target:
+.. |azure_pypi| image::
+    :target:
+.. |azure_devops_master_ci| image::
+    :target:
+.. |code_cov| image::
+    :target:
+.. |documentation_status| image::
+    :target:
+
+.. |python_versions| image:: https://img.shields.io/badge/python-3.7|3.8-blue.svg
+    :target: https://www.python.org/downloads/release/python-380/
+
+.. |code_style| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+.. |made_with_sphinx_doc| image:: https://img.shields.io/badge/Made%20with-Sphinx-1f425f.svg
+    :target: https://www.sphinx-doc.org/
+.. |license_badge| image:: https://img.shields.io/badge/License-Apache%202.0-olivegreen.svg
+    :target: https://opensource.org/licenses/Apache-2.0
diff --git a/_static/facet_banner.png b/_static/facet_banner.png
diff --git a/sphinx/source/_static/team_contributors/Florent_Martin.svg b/sphinx/source/_static/team_contributors/Florent_Martin.svg
diff --git a/sphinx/source/_static/team_contributors/Jan_Ittner.svg b/sphinx/source/_static/team_contributors/Jan_Ittner.svg
diff --git a/sphinx/source/_static/team_contributors/Jason_Bentley.svg b/sphinx/source/_static/team_contributors/Jason_Bentley.svg
diff --git a/sphinx/source/_static/team_contributors/Joerg_Schneider.svg b/sphinx/source/_static/team_contributors/Joerg_Schneider.svg
diff --git a/sphinx/source/_static/team_contributors/Konstantin_Hemker.svg b/sphinx/source/_static/team_contributors/Konstantin_Hemker.svg
diff --git a/sphinx/source/_static/team_contributors/Malo_Grisard.svg b/sphinx/source/_static/team_contributors/Malo_Grisard.svg
diff --git a/sphinx/source/_static/team_contributors/Ricardo_Kennedy.svg b/sphinx/source/_static/team_contributors/Ricardo_Kennedy.svg
diff --git a/sphinx/source/about_us.rst b/sphinx/source/about_us.rst
@@ -16,7 +16,7 @@ Our Story
 
 Industry standard packages for machine learning (scikit-learn) and model inspection
 (shap) are critical for best practice Data Science. However, combining these into
-an efficient and reproducible process the yields deep insights into industrial and
+an efficient and reproducible process that yields deep insights for industrial and
 business processes can be challenging and time consuming. We found this to be a common
 challenge for our global data science teams across 100s of projects every year.
 
@@ -31,7 +31,7 @@ get FACET! Little geometry humour there, we apologise. FACET implements a newly
 developed algorithm to explain how variables of a
 predictive model collaborate to predict outcomes by identifying patterns across the
 explanations of many individual predictions. This advanced model inspection allows
-strong independent factors to be identified and the explored via simulation to
+strong independent factors to be identified and then explored via simulation to
 understand optimal values for the predictive target of interest.
 
 Our Team
@@ -43,72 +43,33 @@ okay that was the last geometry pun we promise.
 
 **FACET Team at BCG Gamma**
 
-.. raw:: html
++-------------------+-------------------+-------------------+-------------------+
+| |JasonB|          | |MaloG|           | |KonstantinH|     | |JanI|            |
+| Jason Bentley     | Malo Grisard      | Konstantin Hemker | Jan Ittner        |
++-------------------+-------------------+-------------------+-------------------+
+| |RicardoK|        | |FlorentM|        | |JoergS|          |                   |
+| Ricardo Kennedy   | Florent Martin    | Joerg Schneider   |                   |
++-------------------+-------------------+-------------------+-------------------+
++-------------------+-------------------+-------------------+-------------------+
 
-    <style>
-    * {
-      box-sizing: border-box;
-    }
-
-    .column {
-      float: left;
-      width: 25%;
-      padding: 15px;
-    }
-
-    /* Clearfix (clear floats) */
-    .row::after {
-      content: "";
-      clear: both;
-      display: table;
-    }
-    </style>
-    </head>
-    <body>
-
-    <div class="row">
-      <div class="column">
-        <img src="_static/JBentley.jpg" style="width:100%">
-        <p>Jason Bentley</p>
-      </div>
-      <div class="column">
-        <img src="_static/MGrisard.jpg" style="width:100%">
-        <p>Malo Grisard</p>
-      </div>
-      <div class="column">
-        <img src="_static/KHemker.jpg" style="width:100%">
-        <p>Konstantin Hemker</p>
-      </div>
-      <div class="column">
-        <img src="_static/JIttner.jpg" style="width:100%">
-        <p>Jan Ittner</p>
-      </div>
-    </div>
-
-    <div class="row">
-      <div class="column">
-        <img src="_static/RKennedy.jpg" style="width:100%">
-        <p>Ricardo Kennedy</p>
-      </div>
-      <div class="column">
-        <img src="_static/FMartin.jpg" style="width:100%">
-        <p>Florent Martin</p>
-      </div>
-      <div class="column">
-        <img src="_static/JSchneider.jpg" style="width:100%">
-        <p>Joerg Schneider</p>
-      </div>
-      <div class="column">
-        <img src="" style="width:100%">
-        <p></p>
-      </div>
-    </div>
-
-    </body>
+.. |JasonB| image:: _static/team_contributors/Jason_Bentley.svg
+    :class: team_pic
 
+.. |MaloG| image:: _static/team_contributors/Malo_Grisard.svg
+    :class: team_pic
 
+.. |KonstantinH| image:: _static/team_contributors/Konstantin_Hemker.svg
+    :class: team_pic
 
+.. |JanI| image:: _static/team_contributors/Jan_Ittner.svg
+    :class: team_pic
 
+.. |RicardoK| image:: _static/team_contributors/Ricardo_Kennedy.svg
+    :class: team_pic
 
+.. |FlorentM| image:: _static/team_contributors/Florent_Martin.svg
+    :class: team_pic
 
+.. |JoergS| image:: _static/team_contributors/Joerg_Schneider.svg
+    :class: team_pic
 
diff --git a/sphinx/source/faqs.rst b/sphinx/source/faqs.rst
@@ -1,4 +1,70 @@
 .. _faqs:
 
-FAQs
-===========
+FAQ
+===
+
+Below you can find answers to commonly asked questions. If you don't see your answer
+there you could also try posting on `stackoverflow <https://stackoverflow.com/>`_.
+
+1. **What if I find a bug or have an idea for a new feature?**
+
+    For bug reports or feature requests please use our
+    `GitHub issue tracker <https://github.com/BCG-Gamma/facet/issues>`_.
+    For any other enquiries please feel free to contact us at our mailing list (add link).
+
+2. **How does FACET's novel algorithm calculate feature redundancy and synergy?**
+
+    Please keep an eye out for our publication coming soon. In the meantime please feel
+    free to explore the GammaScope article (add link) to get a good introduction to
+    using the algorithm.
+
+3. **How can I contribute?**
+
+    We welcome contributors! If you have minor changes in mind that would like to
+    contribute, please feel free to create a pull request and be sure to follow the
+    developer guidelines. For large or extensive changes please feel free to open an
+    issue, or reach out to us at our mailing list (add link) first to discuss.
+
+4. **How can I perform standard plotting of SHAP values as done in the**
+   `shap <https://github.com/slundberg/shap>`_ **library?**
+
+    You can do this by creating an output of SHAP values from the fit LearnerInspector
+    as in the example shown below.
+
+    .. code-block:: Python
+
+        # run inspector
+        inspector = LearnerInspector(
+            n_jobs=-3,
+            verbose=False,
+        ).fit(crossfit=ranker.best_model_crossfit)
+
+        # get shap values and associated data
+        shap_data = inspector.shap_plot_data()
+        shap.summary_plot(shap_values=shap_data.shap_values, features=shap_data.features)
+
+
+
+5. **How can I extract CV performance metrics from the LearnerRanker to create my
+   own summaries or figures?**
+
+    You can extract the desired information as a data frame from the fitted
+    LearnerRanker object.
+
+    .. code-block:: Python
+
+        # after fitting a ranker
+        cv_result_df = ranker.summary_report()
+
+Citation
+--------
+If you use FACET in your work please cite us as follows:
+
+Bibtex entry::
+
+     @manual{
+     title={FACET},
+     author={FACET Team at BCG Gamma},
+     year={2020},
+     note={Python package version 1.0.0)
+     }