addition of Facet team photos, initial FAQs and git badges (#97)

* updates the Readme with gitbadges. Links will need to be added once things are created (for example packages) and have been left empty to ensure it is obvious they require updating * add the initial FAQs section * adds the BCG Facet team personnel photos to the about us section of the documentation
BCG-X-Official · Oct 13, 2020 · d653487 · d653487
1 parent 6531b07
commit d653487
Show file tree

Hide file tree

Showing 11 changed files with 115 additions and 66 deletions.
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.jpg b/sphinx/source/_static/team_contributors/Florent_Martin.jpg
diff --git a/sphinx/source/_static/team_contributors/Jan_Ittner.jpg b/sphinx/source/_static/team_contributors/Jan_Ittner.jpg
diff --git a/sphinx/source/_static/team_contributors/Jason_Bentley.jpg b/sphinx/source/_static/team_contributors/Jason_Bentley.jpg
diff --git a/sphinx/source/_static/team_contributors/Joerg_Schneider.jpg b/sphinx/source/_static/team_contributors/Joerg_Schneider.jpg
diff --git a/sphinx/source/_static/team_contributors/Konstantin_Hemker.jpg b/sphinx/source/_static/team_contributors/Konstantin_Hemker.jpg
diff --git a/sphinx/source/_static/team_contributors/Malo_Grisard.jpg b/sphinx/source/_static/team_contributors/Malo_Grisard.jpg
diff --git a/sphinx/source/_static/team_contributors/Ricardo_Kennedy.jpg b/sphinx/source/_static/team_contributors/Ricardo_Kennedy.jpg
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.jpg
+    :class: team_pic
 
+.. |MaloG| image:: _static/team_contributors/Malo_Grisard.jpg
+    :class: team_pic
 
+.. |KonstantinH| image:: _static/team_contributors/Konstantin_Hemker.jpg
+    :class: team_pic
 
+.. |JanI| image:: _static/team_contributors/Jan_Ittner.jpg
+    :class: team_pic
 
+.. |RicardoK| image:: _static/team_contributors/Ricardo_Kennedy.jpg
+    :class: team_pic
 
+.. |FlorentM| image:: _static/team_contributors/Florent_Martin.jpg
+    :class: team_pic
 
+.. |JoergS| image:: _static/team_contributors/Joerg_Schneider.jpg
+    :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)
+     }