**************
Les dashboards
**************

L'interaction avec les graphiques est possible dans un contexte statique mais limitée car elle n'agit que sur la présentation de données pré chargées dans le fichier JavaScript. C'est là qu'intervient le dashboard, qui est en fait une application client serveur, le client se chargeant de la présentation des données alors que la sélection est gérée côté serveur.

Dans l'éco système Python la technologie Dash/Plotly est utilisée. C'est l'équivalent de `R/Shiny <https://shiny.rstudio.com/>`_.

Dash overview
=============

`Dash <https://dash.plot.ly>`_ est un framework Python permettant de développer des applications web pour la visualisation des données. Il est construit sur des technologies matures et largement déployées:

- `Flask <http://flask.pocoo.org/>`_ est un micro framework web Python
- `Plotly <https://plot.ly/javascript/>`_ est une bibliothèque graphique basée sur `D3.js <https://d3js.org>`_, la référence en matière de data visualisation
- `React <https://reactjs.org/>`_. est une bibliothèque JavaScript développée par Facebook


Architecture
------------

Dash propose une couche d'abstraction au dessus des technologies présentées ci dessus et des protocoles requis pour développer ce type d'application. Les applications sont déployées et partagées à travers un navigateur web.

Chris Parmer, le fondateur de Dash, expose les principales caractéristiques du framework dans `une présentation vidéo YouTube <https://www.youtube.com/watch?time_continue=20&v=5BAthiN0htc>`_.

.. raw:: html
    
    <iframe width="560" height="315" src="https://www.youtube.com/embed/5BAthiN0htc" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>


- Côté front end, Les composants HTML sont générés par React dont l'ensemble des composants est donc disponible pour le design de la page web.
- Côté back end, une application Dash est une instance d'une application Flask dont toutes les propriétés sont configurables. L'ensemble des plugins Flask est donc disponible pour une utilisation avancée. Les composants Dash sont des classes Python permettant de packager les composants React. Ceux ci sont sérialisés au format JSON et transférés au front end via des requêtes HTTP.

Un premier dashboard
====================

Un dashboard Dash est une application Flask. Le code ci dessous permet de produire un graphique élémentaire. Il est écrit avec la version ``1.13.3`` de Dash.

.. code-block:: python
    :linenos:

    # filename = 'dash-01.py'

    #
    # Imports
    #

    import plotly_express as px

    import dash
    import dash_core_components as dcc
    import dash_html_components as html

    #
    # Data
    #

    year = 2002

    gapminder = px.data.gapminder() # (1)
    years = gapminder["year"].unique()
    data = { year:gapminder.query("year == @year") for year in years} # (2)

    #
    # Main
    #

    if __name__ == '__main__':

        app = dash.Dash(__name__) # (3)

        fig = px.scatter(data[year], x="gdpPercap", y="lifeExp", 
                            color="continent", 
                            size="pop", 
                            hover_name="country") # (4)


        app.layout = html.Div(children=[

                                html.H1(children=f'Life expectancy vs GDP per capita ({year})', 
                                            style={'textAlign': 'center', 'color': '#7FDBFF'}), # (5)

                                dcc.Graph(
                                    id='graph1',
                                    figure=fig
                                ), # (6)

                                html.Div(children=f'''
                                    The graph above shows relationship between life expectancy and 
                                    GDP per capita for year {year}. Each continent data has its own 
                                    colour and symbol size is proportionnal to country population. 
                                    Mouse over for details.
                                '''), # (7)

        ]
        )

        #
        # RUN APP
        #

        app.run_server(debug=True) # (8)

- On collecte les données (1)
- On crée un dictionnaire dont les clés sont les années et les valeurs, les données de l'année concernée (2)
- On crée une instance de la classe Dash (3)
- on crée la figure destinée à être affichée dans le dashboard (4)
- la page est composée d'éléments HTML standard (5)(7) 
- la bibliothèque Dash Core Components fournit l'élément Graph qui permet d'inclure un graphique Plotly/Plotly Express (6) 
- lancement de l'application (8) 

Cette application est lancée dans une console::


    $ python3 dash-01.py 
    Dash is running on http://127.0.0.1:8050/

    Warning: This is a development server. Do not use app.run_server
    in production, use a production WSGI server like gunicorn instead.

    * Serving Flask app "dash-01" (lazy loading)
    * Environment: production
    WARNING: This is a development server. Do not use it in a production deployment.
    Use a production WSGI server instead.
    * Debug mode: on

Et le résultat s'observe dans la fenêtre d'un navigateur à l'adresse indiquée dans la console (ici ``http://127.0.0.1:8050/``)

.. image:: images/03-fig01.png
    :scale: 75 %
    :align: center

Le code source de la page est simple et structuré. Le rendu est confié aux fonctions JavaScript encapsulées dans le ``<footer>``.

.. code-block:: html

    <!DOCTYPE html>
    <html>
        <head>
            <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta charset="UTF-8">
            <title>Dash</title>
            <link rel="icon" type="image/x-icon" href="/_favicon.ico?v=1.13.3">
            
        </head>
        <body>
            
    <div id="react-entry-point">
        <div class="_dash-loading">
            Loading...
        </div>
    </div>

            <footer>
                <script id="_dash-config" type="application/json">{"url_base_pathname": null, "requests_pathname_prefix": "/", "ui": true, "props_check": true, "show_undo_redo": false, "suppress_callback_exceptions": false, "hot_reload": {"interval": 3000, "max_retry": 8}}</script>
                <script src="/_dash-component-suites/dash_renderer/polyfill@7.v1_5_0m1592837063.8.7.min.js"></script>
    <script src="/_dash-component-suites/dash_renderer/react@16.v1_5_0m1592837063.13.0.js"></script>
    <script src="/_dash-component-suites/dash_renderer/react-dom@16.v1_5_0m1592837063.13.0.js"></script>
    <script src="/_dash-component-suites/dash_renderer/prop-types@15.v1_5_0m1592837063.7.2.js"></script>
    <script src="/_dash-component-suites/dash_core_components/dash_core_components.v1_10_1m1592837063.min.js"></script>
    <script src="/_dash-component-suites/dash_core_components/dash_core_components-shared.v1_10_1m1592837063.js"></script>
    <script src="/_dash-component-suites/dash_html_components/dash_html_components.v1_0_3m1592837063.min.js"></script>
    <script src="/_dash-component-suites/dash_renderer/dash_renderer.v1_5_0m1592837063.dev.js"></script>
                <script id="_dash-renderer" type="application/javascript">var renderer = new DashRenderer();</script>
            </footer>
        </body>
    </html>

La capture d'écran ci dessus est statique et ne rend donc pas compte des capacités dynamiques apportées par le framework Dash/Plotly. Dans le navigateur local de votre machine, vérifier que les possibilités de sélection, de zoom et d'affichage des données au survol (hover) sont opérationnelles.


Interaction simple
==================

Le dashboard précédent est totalement statique et n'apporte pas de valeur ajoutée par rapport à un graphique Plotly/Plotly Express. Nous allons remédier à ça en ajoutant un widget de sélection de l'année sur le front end.

.. code-block:: python

    html.Label('Year'),
    dcc.Dropdown(
        id="year-dropdown",
        options=[
            {'label': '1952', 'value': 1952},
            {'label': '1957', 'value': 1957},
            {'label': '1962', 'value': 1962},
            {'label': '1967', 'value': 1967},
            {'label': '1972', 'value': 1972},
            {'label': '1977', 'value': 1977},
            {'label': '1982', 'value': 1982},
            {'label': '1987', 'value': 1987},
            {'label': '1992', 'value': 1992},
            {'label': '1997', 'value': 1997},
            {'label': '2002', 'value': 2002},
            {'label': '2007', 'value': 2007},
        ],
        value=2007,
    ),

Il faut ensuite écrire la fonction permettant de modifier la figure affichée en fonction de l'année sélectionnée. Dash fonctionne avec un système de décorateur qui doit être défini **après** le layout du graphique:

- les paramètres du décorateur :func:`@app.callback()` font le lien entre les composants HTML du front end à lire/modifier
- côté back end, la fonction décorée construit la figure à partir du paramètre passé en argument et la retourne 

.. code-block:: python

    @app.callback(
        Output(component_id='graph1', component_property='figure'), # (1)
        [Input(component_id='year-dropdown', component_property='value')] # (2)
    )
    def update_figure(input_value): # (3)
        return px.scatter(data[input_value], x="gdpPercap", y="lifeExp", 
                        color="continent", 
                        size="pop", 
                        hover_name="country") # (4)

- (1) : l'objet' :class:`Output` passé en paramètre au décorateur désigne le composant HTML (``component_id``) que l'application va modifier dynamiquement et la propriété mise en jeu (``component_property``).
- (2) : l'objet :class:`Input` désigne le composant HTML (``component_id``) via lequel l'utilisateur va interagir et sa propriété (``component_property``).
- (3) : le paramètre ``input_value`` passé à la fonction de modification est lié dynamiquement à la propriété passée en paramètre à :class:`Input`. L'appel de la fonction est déclenché par une modification de la propriété du widget déclaré dans :class:`Input`. Le nom de la fonction est arbitraire.
- (4) : la valeur de retour de la fonction est affectée à la propriété du widget déclaré dans :class:`Output` et le graphique est mis à jour en conséquence.
- (5) : les objets :class:`Input` et :class:`Output` doivent être importés depuis le module `dash.dependencies`.


Modifier plusieurs éléments
===========================

Le dashboard précédent est fonctionnel mais le titre et la légende ne reflètent pas le changement dynamique de l'année. 

Dash permet de modifier plusieurs composants HTML, en passant ceux ci en argument du décorateur sous forme d'une :class:`list` ``l`` d'objets :class:`Output`. 

La fonction décorée doit alors retourner une :class:`list` de même taille, dont chacun des éléments sera passé aux composants de ``l``. L'ordre et le nombre des valeurs de retour doit être en bijection avec ``l``.

.. topic:: Exercice

    Modifier les paramètres du décorateur et la fonction décorée pour mettre à jour dynamiquement le titre et la légende. Il fauudra ajouter un ``id`` aux éléments à modifier pour pouvoir les référencer.

.. examples/dash-03.py
.. @app.callback(
    [   Output(component_id='graph1', component_property='figure'),
        Output(component_id='title', component_property='children'),
        Output(component_id='legend', component_property='children')
    ], # (1)
    [Input(component_id='year-dropdown', component_property='value')] # (2)
    )
    def update_figure(input_value): # (3)
        fig = px.scatter(data[input_value], x="gdpPercap", y="lifeExp", 
                        color="continent", 
                        size="pop", 
                        hover_name="country") # (4)
        title = f'Life expectancy vs GDP per capita ({input_value})'
        legend = f'''The graph above shows relationship between life expectancy and 
                GDP per capita for year {input_value}. Each continent data has its own 
                colour and symbol size is proportionnal to country population. 
                Mouse over for details.'''
        return [ fig, title, legend]

Le résultat doit être similaire au dashboard ci dessous.

.. image:: images/03-fig02.png
    :scale: 75 %
    :align: center

.. topic:: Exercice

    La définition de l'élément :class:`dcc.Dropdown` est statique. Utiliser les années présentes dans la dataframe pour renseigner les propriétés.

.. examples/dash-04.py
.. years = gapminder["year"].unique()
    # dropdown properties
    dd_options = [ {'label':str(year), 'value':year} for year in years]
    dd_value = max(years)
    dcc.Dropdown(id="year-dropdown",
                    options=dd_options,
                    value=dd_value,
                ),

.. topic:: Exercice

    L'utilisation d'un widget :class:`dcc.Dropdown` n'est peut être pas optimale en terme d'ergonomie. Utiliser plutôt le widget :class:`dcc.Slider` pour sélectionner dynamiquement l'année.

.. examples/dash-05.py
    dcc.Slider(min=min(years),
                max=max(years),
                step=5,
                value=max(years),
                marks = { int(y):str(y) for y in years},
                id="year-slider",
                dots=True
                # style={'margin-right': '20px', 'margin-left': '20px'},
            ),                       
    html.Br(),             
    #           
    @app.callback(
        [   Output(component_id='graph', component_property='figure'),
            Output(component_id='title', component_property='children'),
            Output(component_id='legend', component_property='children')
        ], # (1)
        [Input(component_id='year-slider', component_property='value')] # (2)
    )

Cet exemple illustre le principe utilisé par Dash pour construire des dashboards interactifs.

- Il est également possible de construire des widgets dynamiques tel que décrit dans le paragraphe "Dash App With Chained Callbacks" du document `Basic Dash Callbacks <https://dash.plotly.com/basic-callbacks>`_ 
- ou encore d'utiliser les informations de survol pour modifier dynamiquement un graphe tel que décrit dans le paragraphe "Update Graphs on Hover" du document `Interactive Visualizations <https://dash.plot.ly/interactive-graphing>`_. 
- On peut également conditionner l'exécution des callbacks à l'état d'un widget. Ceci est décrit dans le paragraphe "Dash App With State" du document `Basic Dash Callbacks <https://dash.plotly.com/basic-callbacks>`_.
- D'autres exemples avancés sont décrits dans le chapitre `Sharing Data Between Callbacks <https://dash.plotly.com/sharing-data-between-callbacks>`_.

Animations
==========

Le principe des callbacks est puissant mais nécessite une interaction pour rafraichir la page.

Le composant :class:`dcc.Interval` permet un rafraichissement automatique, ce qui autorise la création d'animations.


.. note::

    :class:`dcc.Interval` is a component that will fire a callback periodically. Use :class:`dcc.Interval` to update your app in realtime without needing to refresh the page or click on any buttons. Voir `la documentation <https://dash.plotly.com/dash-core-components/interval>`_.


Ce compteur peut modifier cycliquement le paramètre ``value`` du :class:`dcc.Slider` qui modifie dynamiquement le graphique. Classiquement, on rajoute ce composant dans le layout de la page ::

    dcc.Interval(   id='interval',
                    interval=1*1000, # in milliseconds
                    n_intervals=0),

Et on établit la relation entre le compteur et la valeur du :class:`dcc.Slider` avec un callback::

    @app.callback(  Output('year-slider', 'value'),
                    [Input('interval', 'n_intervals')])
    def on_tick(n_intervals):
        if n_intervals is None: return 0
        return years[(n_intervals+1)%len(years)]

Le dashboard est fonctionnel mais l'animation est automatique et est joué cycliquement dès le démarrage de l'application. On peut améliorer l'interactivité en rajoutant des éléments de contrôle.

.. topic:: Exercice

    Ajouter deux composants :class:`dcc.Button` Play/Pause pour démarrer/stopper l'animation. On utilisera la propriété ``disabled`` du composant :class:`dcc.Interval`. On peut également ajouter un contrôle dynamique de la vitesse de défilement en utilisant la propriété ``interval``.

.. #layout
    html.Button('Play', id='play'),
    html.Button('Pause', id='pause'),
    # callback
    @app.callback(
        Output('interval', 'disabled'),
        [Input('play', 'n_clicks_timestamp'), Input('pause', 'n_clicks_timestamp')])
    def is_playing(t_play, t_pause):
        if any( [t_play is None, t_pause is None] ) : return False
        if t_play < t_pause: return True
        return False

Le résultat doit être similaire au dashboard ci dessous.

.. image:: images/03-fig03.png
    :scale: 75 %
    :align: center

Aller plus loin
===============

Le principe des dashboard a été présenté, ainsi que quelques possibilités d'interactions. Il sera très utile de porter un oeil attentif sur le `User Guide <https://dash.plot.ly/>`_ qui contient quelques tutorials et des notions plus avancées...