.. _plotly-dash-apps:

Using Plotly Dash
=================

Faculty supports building `Plotly Dash <https://plot.ly/products/dash/>`_
applications. Plotly Dash offers a flexible interface for building interactive
dashboards entirely in Python (you don't need to write any JavaScript). For
additional examples, check out the `Plotly Dash gallery
<https://plot.ly/dash/gallery>`_ and our own :ref:`examples section
<plotly_dash_examples>`.

.. contents:: Contents
    :local:

.. _developing_plotly_dash_apps:

Developing the application
--------------------------

When you are just starting out, you probably want to develop the application
without exposing it to other people in your project.

The easiest way of doing this is to just create a Jupyter server, open a
terminal in that server and run the following commands:

.. code-block:: bash

    $ conda activate Python3
    $ pip install dash dash-renderer dash-html-components dash-core-components plotly
    $ sudo sv stop jupyter

.. thumbnail:: images/install_dash.png

This has stopped the Jupyter notebook running on that instance, freeing the
port for our application.

Let's start by creating a directory in the project workspace:

.. code-block:: bash

    $ mkdir -p /project/dash-example

Let's now write the code for our application. We will create an application
that predicts whether someone is a cat-person or a dog-person based on their
name. Create a file called ``app.py`` in ``/project/dash-example``, with the
following contents:

.. code-block:: python

    import dash
    import dash_core_components as dcc
    import dash_html_components as html
    from dash.dependencies import Input, Output

    app = dash.Dash(__name__)

    app.layout = html.Div(children=[
        html.H1(children='Are you a cat person?'),
        html.Label('Your name: '),
        dcc.Input(id='input-div'),
        html.Div(id='output-div', children=[])
    ])

    @app.callback(
            Output(component_id='output-div', component_property='children'),
            [Input(component_id='input-div', component_property='value')]
    )
    def update_output(input_value):
        if input_value is None or not input_value:
            return ['You have not typed your name yet.']
        if input_value == 'Heisenberg':
            return ['You are a cat person.']
        else:
            return ['You are a dog person.']

    if __name__ == '__main__':
        app.run_server(host='127.0.0.1', port=8888, debug=True)

This code defines a minimal application that listens on port 8888, the port
that we have freed by stopping Jupyter. Let's now start our app:

.. code-block:: bash

    $ cd /project/dash-example
    $ python app.py

.. note::

    Running the app with ``python app.py`` runs the app with its development
    server in debug mode (see ``app.run_server()`` in the example code above),
    which provides nice features like automatic reloading of the app when the
    code is changed.

    However, this is not suitable for use in deployed applications, where we
    instead use gunicorn, a production-ready Python HTTP server. If you want to
    run the app in the same way as it will be run in production, install
    gunicorn and gevent from pip (``pip install gunicorn gevent``) and run the
    app with:

    .. code-block:: bash

        $ gunicorn --workers 4 --worker-class gevent --bind 127.0.0.1:8888 app:app.server

If you now open your server from the servers section of the workspace:

.. image:: images/open_server.png
   :width: 50%
   :align: center

You will see your application!

.. image:: images/dash_app_example.png

Carry on developing your app. When you save changes to your code, the app will
automatically reload itself (unless you are running it with gunicorn, in which
case you will need to first stop it by typing Ctrl-C in the terminal in which
you started the app, and restart it by running the same command).

Deploying the application
-------------------------

You have now developed a great dashboard, and you want to let other members of
your project access it. Faculty supports hosting Plotly Dash applications.
Head to the `Deployments` page in Faculty, and in the `Apps` tab click
the `+` button above the tab to create a new app. You will be prompted to
enter a name and domain for your app. Select `Plotly Dash` for `Type`.

.. image:: images/new_app_modal.png

Click `Create App`. You will then be taken to the `App Settings` page.

You will need to make the following changes to the application settings:

 - Change the `working directory` to ``/project/dash-example``.
 - Change the `python module` to ``app``. This should be the name of the file
   containing the app, without ``.py``.
 - Change the `python object` to ``app.server``. This should be the name of the
   Python variable that gunicorn will serve.

.. thumbnail:: images/dash_app_settings.png

Save your application by clicking the `Save` button, then click `Start app` to
start your Plotly Dash server. After a few seconds, you will see the
status of your app change to `Running`. At this point, a URL will appear.
Select that URL and place it in your browser search bar.  You will be taken to
the application! Behind the scenes, Faculty verifies that you are at least
an observer in the project that the app belongs to. While your app is
deployed, you can monitor its logs in the `Monitor` tab.

Deploying Flask and Django applications
---------------------------------------

Plotly Dash applications are deployed using `Gunicorn
<http://gunicorn.org/>`_. You can leverage this to deploy any `WSGI
<https://wsgi.readthedocs.io/>`_ web framework. This lets you, in
particular, deploy `Flask <http://flask.pocoo.org/>`_ and `Django
<https://www.djangoproject.com/>`_ applications.

`Flask` applications will work out of the box. Your application
will contain a file with a line like::

  server = Flask(...)

When creating the deployment in Faculty, choose the Python module
containing that line for `python module`. For instance, if that line
is in a file called ``app.py``, the `python module` will be
``app``. Choose ``server`` as the `python object`.

For `Django` applications, you will need to create an environment that
installs ``django`` through `pip`. Your application should have a file
called ``<project_name>/wsgi.py`` containing the following lines::

  from django.core.wsgi import get_wsgi_application
  application = get_wsgi_application()

When creating the deployment through the deployment tab, choose
``<project_name>.wsgi`` as the `python module` and ``application`` as
the `python object`.

See the `Django documentation on WSGI
<https://docs.djangoproject.com/en/2.0/howto/deployment/wsgi/>`_ for
more information.

Sharing your application
------------------------

To share the application with a team member who is an observer in the project,
just give them the URL of the application!

To invite people to your project, go to the `Collaborators` page,
enter their Faculty username or the email that they used to sign up
to Faculty, and assign them observer status.

.. thumbnail:: images/team_page_with_observer.png

.. _plotly_dash_examples:

Examples
--------

For ideas on how to develop a great dashboard with Plotly Dash, check out our
examples:

.. toctree::
   :titlesonly:

   examples/dash_file_upload_download