.. _hiplot-mlflow-library:

Using HiPlot
============

*Experiment visualisation with high dimensional plotting.*

`HiPlot <https://facebookresearch.github.io/hiplot/index.html>`_ is a
lightweight interactive visualization tool to help AI researchers discover
correlations and patterns in high-dimensional data using parallel plots and
other graphical ways to represent information. Our ``hiplot-mlflow`` library
implements an MLFlow experiment fetcher plugin for HiPlot to enable visualising
:ref:`experiments <experiments-main>`.

To use ``hiplot-mlflow``, :ref:`install it on your server <libraries-main>`,
or add it as a Python 3 package in a :ref:`custom environment <faculty_environments>`.

For details on how to use HiPlot's interactive visualisation, please refer to
`their documentation <https://facebookresearch.github.io/hiplot/index.html>`_.

.. _hiplot-mlflow-notebooks:

Using HiPlot in a notebook
--------------------------

In Jupyter notebooks use the ``hiplot_mlflow.fetch`` function to retrieve
an MLflow experiment :ref:`by name <experiments-multiple>`, and display it with HiPlot:

.. code-block:: python

    import hiplot_mlflow
    experiments = hiplot_mlflow.fetch("my-lovely-experiment")
    experiments.display(force_full_width=True)

By default MLflow tags are not shown (only MLflow metrics and parameters).
To display tags as well, pass ``include_tag=True`` to the fetching functions,
for example:

.. code-block:: python

    experiment = hiplot_mlflow.fetch("my-lovely-experiment", include_tags=True)

.. thumbnail:: images/hiplot-notebook.png

See more about what you can do with the returned ``hiplot.Experiment`` object
in the `HiPlot documentation <https://facebookresearch.github.io/hiplot/experiment_settings.html>`_.

.. _hiplot-mlflow-apps:

Using HiPlot as a stand-alone app
---------------------------------

You can also use `HiPlot's built in webserver <https://facebookresearch.github.io/hiplot/tuto_webserver.html>`_
with hiplot-mlflow as a :ref:`custom app <custom-apps>` on the Platform.

To do this, create a start-up script, here we'll call it ``hiplot_server.sh``
for example, somewhere in your workspace with the following contents.

.. code-block:: shell

    #!/bin/bash

    exec hiplot hiplot_mlflow.fetch_by_uri --port 8888

Then create an :ref:`environment <faculty_environments>` that installs
``hiplot-mlflow`` as a Python 3 package.

Finally, set up the custom script app app to use that environment,
and run the ``hiplot_server.sh`` script.

.. thumbnail:: images/hiplot-custom-app.png

If you the navigate to the app's URL, you can then use the ``mlflow://``
schema to access MLflow experiments in HiPlot by either experiment name or ID,
for example:

.. code-block::

    mlflow://name/experiment-name
    mlflow://id/0

.. thumbnail:: images/hiplot-server-name.png

You can also add tags=yes as a query string parameter to include tags in the output, for example:

.. code-block::

    mlflow://name/experiment-name?tags=yes

You can also use the multiple experiments loading syntax of HiPlot, either
the list format:

.. code-block::

    multi://[
        "mlflow://id/1",
        "mlflow://name/another-experiment?tags=yes"
    ]

or the dictionary format, where you can define your own experiment labels:

.. code-block::

    multi://{
        "first-experiment": "mlflow://id/1",
        "another-experiment": "mlflow://name/another-experiment?tags=yes"
    }

.. thumbnail:: images/hiplot-server-multi.png

If you encounter any issue when plotting, such as a "HTTP error, check server logs /
javascript console" message in the HiPlot interface, you can troubleshoot by navigating
in the app's control interface's Monitor / App Logs view.