document viz module (#168)

* update library reference
* update existing dashboard section
* add images to notebooks
* add text content to viz notebooks

.github/workflows/publish-docs.yml

@@ -22,15 +22,15 @@ jobs:
     - name: Set up Python
       uses: conda-incubator/setup-miniconda@v2
       with:
-        python-version: 3.8
+        python-version: 3.9
         mamba-version: "*"
         channels: conda-forge
         channel-priority: true
         activate-environment: rubicon-ml-docs
         environment-file: docs/docs-environment.yml
     - name: Install rubicon-ml
       run: |
-        pip install --no-deps .
+        pip install --no-deps -e .
     - name: Build
       run: |
         cd docs

docs/Makefile

@@ -17,12 +17,14 @@ clean:
 	rm -rf ./build/html
 	rm -rf ./source/logging-examples
 	rm -rf ./source/integrations
+	rm -rf ./source/visualizations
 
 # Copy over up to date sources from the root of the `rubicon_ml` repo.
 pre-build:
 	mkdir -p ./build/html
 	mkdir -p ./source/logging-examples
 	mkdir -p ./source/integrations
+	mkdir -p ./source/visualizations
 
 	cp ../notebooks/quick-look.ipynb ./source
 	cp ../notebooks/logging-examples/logging-basics.ipynb ./source/logging-examples
@@ -33,9 +35,11 @@ pre-build:
 	cp ../notebooks/integrations/integration-git.ipynb ./source/integrations
 	cp ../notebooks/integrations/integration-prefect-workflows.ipynb ./source/integrations
 	cp ../notebooks/integrations/integration-sklearn.ipynb ./source/integrations
+	cp ../notebooks/viz/*.ipynb ./source/visualizations
 
 	cp ../notebooks/quick-look-dashboard.png ./source
 	cp ../notebooks/integrations/integration-git-dashboard.png ./source/integrations
+	cp ../notebooks/viz/*.png ./source/visualizations
 
 # Run the Sphinx command to build the docs as html.
 build-docs:

docs/docs-environment.yml

@@ -2,7 +2,7 @@ name: rubicon-ml-docs
 channels:
   - conda-forge
 dependencies:
-  - python>=3.7
+  - python=3.9
 
   # for building the docs
   - furo
@@ -13,10 +13,9 @@ dependencies:
   - sphinx-copybutton
 
   # only install necessary rubicon-ml dependencies
-  - dash>=1.14.0
-  - dash-bootstrap-components>=0.10.6
+  - dash>=2.0.0
+  - dash-bootstrap-components>=1.0.0
   - dask>=2.12.0
-  - jupyter-dash
   - pandas>=1.0
   - fsspec>=2021.4.0
   - prefect>=0.12.0

docs/source/index.rst

@@ -62,7 +62,7 @@ context necessary for a complete model review and approval.
    library_reference.rst
    examples.rst
    integrations.rst
-   dashboard.rst
+   visualizations.rst
    faqs.rst
 
 .. toctree::

docs/source/install.rst

@@ -29,7 +29,7 @@ rubicon-ml has a few optional extras if you're installing with ``pip`` (these ex
 installed by default when using ``conda``).
 
 The ``ui`` extra installs the requirements necessary for using the visualization tools.
-For a preview, take a look at the :ref:`dashboard<dashboard>` section of the docs.
+For a preview, take a look at the :ref:`Visualizations<Visualizations>` section of the docs.
 
 .. code-block:: console
 

docs/source/library_reference.rst

@@ -81,7 +81,7 @@ return value.
 
 sklearn
 =======
-``rubicon_ml`` offers direct integration with Scikit-learn via our
+``rubicon_ml`` offers direct integration with **Scikit-learn** via our
 own pipeline object.
 
 .. autoclass:: rubicon_ml.sklearn.RubiconPipeline
@@ -90,15 +90,29 @@ own pipeline object.
 .. autoclass:: rubicon_ml.sklearn.FilterEstimatorLogger
    :members:
 
-.. _library-reference-ui:
+.. _library-reference-viz:
 
-ui
-==
-The ``rubicon_ml`` dashboard can be launched directly from Python code
-or the CLI.
+viz
+===
+``rubicon_ml`` offers visualization leveraging **Dash** and **Plotly**.
+Each of the following classes are standalone widgets.
 
-.. autoclass:: rubicon_ml.ui.Dashboard
-.. autofunction:: rubicon_ml.ui.Dashboard.run_server
+.. autoclass:: rubicon_ml.viz.DataframePlot
+   :members: serve, show
+
+.. autoclass:: rubicon_ml.viz.ExperimentsTable
+   :members: serve, show
+
+.. autoclass:: rubicon_ml.viz.MetricCorrelationPlot
+   :members: serve, show
+
+.. autoclass:: rubicon_ml.viz.MetricListsComparison
+   :members: serve, show
+
+Widgets can be combined into an interactive dashboard.
+
+.. autoclass:: rubicon_ml.viz.Dashboard
+   :members: serve, show
 
 .. _library-reference-workflow:
 

docs/source/visualizations.rst

@@ -0,0 +1,102 @@
+.. _visualizations:
+
+Visualizations
+**************
+
+``rubicon_ml.viz`` contains a number of visualization widgets powered by
+`Dash <https://dash.plotly.com>`_ and `Plotly <https://plotly.com/>`_.
+Each widget provides a unique UI for exploring and visualizing projects and
+experiments stored locally or in S3. The widgets can be compiled into an 
+interactive dashboard. They can also run in the browser or any iPython
+environment like Jupyter Notebook, JupyterLab or JupyterHub. With some
+extra work, they could be deployed to a static URL using Docker.
+
+|
+
+.. figure:: _static/images/dashboard.png
+  :align: center
+  :alt: rubicon-ml dashboard
+
+  A **Dashboard** composed of an **Experiments Table** and a **Metric
+  Correlation Plot**.
+
+Available Widgets
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   visualizations/dataframe-plot
+   visualizations/experiments-table
+   visualizations/metric-correlation-plot
+   visualizations/metric-lists-comparisons
+
+Dashboarding
+============
+
+The widgets detailed in the examples above can also be compiled into an
+interactive dashboard.
+
+.. toctree::
+   :maxdepth: 1
+
+   visualizations/dashboard
+
+Basic Usage
+===========
+
+Each individual widget can be launched directly from Python code. Widgets
+will be hosted locally. You can navigate to the provided link in each widgets'
+output, or visualize the widget in-line if you are running from a Jupyter
+environment.
+
+.. code-block:: python
+
+  from rubicon_ml.viz import ExperimentsTable
+
+  ExperimentsTable(experiments=my_rubicon_project.experiments()).serve()
+
+The above launches the experiments table on ``localhost:8050`` and will run from
+any Python interpreter. If you're working in a Jupyter environment, you can
+launch the dashboard inline in a notebook with ``show``:
+
+.. code-block:: python
+
+  ExperimentsTable(experiments=my_rubicon_project.experiments()).show()
+
+If you need to configure the Dash proxy, that can also be done with a
+few extra parameters:
+
+.. code-block:: python
+
+  dash_kwargs = {
+      "requests_pathname_prefix": "/proxy/8050",
+  }
+  run_server_kwargs = {
+      "proxy": "http://127.0.0.1:8050::https://my-jupyterhub-server.com/",
+  }
+
+  ExperimentsTable(experiments=my_rubicon_project.experiments()).serve(
+      dash_kwargs=dash_options,
+      run_server_kwargs=run_server_kwargs,
+  )
+
+More info on configuring proxies and additional ``dash_kwargs`` can be found in the
+`Dash API Reference <https://dash.plotly.com/reference>`_.
+
+CLI
+===
+
+The ``rubicon_ml`` CLI can lauch a dashboard containing an **Experiments
+Table** stacked on top of a **Metric Correlation Plot**, as shown in the
+figure above.
+
+.. code-block:: shell
+
+  rubicon_ml ui --root-dir /rubicon-root --project-name "My Cool Project"
+
+Use the ``--help`` flag for full usage details:
+
+.. code-block:: shell
+
+  rubicon_ml ui --help