Dash per Principianti

Dash è un framework Python per creare applicazioni web. È costruito sopra Flask, Plotly.js, React e React Js. Ti permette di creare dashboard usando puro Python. Dash è open source e le sue app girano nel browser. In questo tutorial presentiamo le basi di Dash e diamo per scontato che tu abbia già esperienza con Plotly.

Installazione di Dash

Per iniziare a usare Dash, dobbiamo installare diversi pacchetti.

1. Il backend core di dash.
2. Il front-end di Dash
3. Componenti HTML di Dash
4. Componenti core di Dash
5. Plotly

pip install dash==0.21.1  
pip install dash-renderer==0.13.0  
pip install dash-html-components==0.11.0
pip install dash-core-components==0.23.0  
pip install plotly --upgrade

Layout di un'app Dash

Un'applicazione Dash è solitamente composta da due parti. La prima è il layout e descrive l'aspetto dell'app; la seconda descrive l'interattività dell'applicazione. Dash fornisce classi HTML che ci permettono di generare contenuti HTML con Python. Per usarle, dobbiamo importare dash_core_components e dash_html_components. Puoi anche creare componenti personalizzati con Javascript e React Js.

Per iniziare, creiamo un file chiamato app.py con il nostro editor di testo preferito e importiamo questi pacchetti.

import dash
import dash_core_components as dcc
import dash_html_components as html
 

Proprio come in Flask, inizializziamo Dash chiamando la classe Dash di dash. Fatto questo, possiamo creare il layout della nostra applicazione. Usiamo la classe Div da dash_html_components per creare un Div HTML. Poi usiamo i componenti HTML per generare elementi come H1, H2 ecc. dash_html_components contiene tutti i tag HTML. Per creare un grafico nel nostro layout, usiamo la classe Graph da dash_core_components. Graph renderizza visualizzazioni dati interattive usando plotly.js. La classe Graph si aspetta un oggetto figure con i data da tracciare e i dettagli di layout. Dash ti permette anche di applicare stili come cambiare il colore di sfondo e del testo. Puoi modificare lo sfondo usando l'attributo style passando un oggetto con il colore desiderato. Nel nostro caso abbiamo definito un dizionario colors con il colore di sfondo e del testo. Allo stesso modo, possiamo cambiare lo sfondo del layout usando l'attributo plot_bgcolor.

In HTML la proprietà style è specificata con i punti e virgola, ma in Dash si fornisce un dizionario. Le chiavi del dizionario sono in camelCase, ad es. text-align diventa textAlign. Invece di usare class come in HTML, in Dash si usa className.

 app = dash.Dash()
colors = {
    'background': '#111111',
    'text': '#7FDBFF'
}
app.layout = html.Div(style={'backgroundColor': colors['background']}, children=[
    html.H1(
        children='Hello Dash',
        style={
            'textAlign': 'center',
            'color': colors['text']
        }
    ),
    html.Div(children='Dash: A web application framework for Python.', style={
        'textAlign': 'center',
        'color': colors['text']
    }),
    dcc.Graph(
        id='Graph1',
        figure={
            'data': [
                {'x': [1, 2, 3], 'y': [4, 1, 2], 'type': 'bar', 'name': 'SF'},
                {'x': [1, 2, 3], 'y': [2, 4, 5], 'type': 'bar', 'name': u'Montréal'},
            ],
            'layout': {
                'plot_bgcolor': colors['background'],
                'paper_bgcolor': colors['background'],
                'font': {
                    'color': colors['text']
                }
            }
        }
    )
])
 

Per visualizzare la nostra grafica, dobbiamo avviare il server web proprio come in Flask. Ricorda che Dash è costruito sopra Flask. Impostiamo anche debug su true per evitare di dover aggiornare il server ogni volta che apportiamo modifiche

 if __name__ == '__main__':
    app.run_server(debug=True)

Poi passa al terminale e avvia il server digitando il codice seguente: python app.py

Questo avvierà un nuovo server web su http://127.0.0.1:8050/. Vai lì e guarda il tuo dashboard appena creato.

Generare grafici a dispersione

Per tracciare uno scatter plot, importiamo i normali componenti dash come fatto in precedenza. Dobbiamo anche importare i graph_objs di Plotly per creare lo scatter plot. Come detto, usiamo la classe Div e i componenti Graph di Dash per ottenere questo risultato. Il componente Graph accetta un oggetto figure che contiene i dati e la descrizione del layout. Tracciamo lo scatter plot usando la proprietà scatter di graph_objs. Per assicurarci che il grafico sia uno scatter, passiamo un attributo mode impostato su markers. Altrimenti avremmo delle linee sul grafico.

 import dash
import dash_core_components as dcc
import dash_html_components as html
import pandas as pd
import plotly.graph_objs as go

app = dash.Dash()

df = pd.read_csv(
    'https://gist.githubusercontent.com/chriddyp/' +
    '5d1ea79569ed194d432e56108a04d188/raw/' +
    'a9f9e8076b837d541398e999dcbac2b2826a81f8/'+
    'gdp-life-exp-2007.csv')


app.layout = html.Div([
    dcc.Graph(
        id='life-exp-vs-gdp',
        figure={
            'data': [
                go.Scatter(
                    x=df[df['continent'] == i]['gdp per capita'],
                    y=df[df['continent'] == i]['life expectancy'],
                    text=df[df['continent'] == i]['country'],
                    mode='markers',
                    opacity=0.8,
                    marker={
                        'size': 15,
                        'line': {'width': 0.5, 'color': 'white'}
                    },
                    name=i
                ) for i in df.continent.unique()
            ],
            'layout': go.Layout(
                xaxis={'type': 'log', 'title': 'GDP Per Capita'},
                yaxis={'title': 'Life Expectancy'},
                margin={'l': 40, 'b': 40, 't': 10, 'r': 10},
                legend={'x': 0, 'y': 1},
                hovermode='closest'
            )
        }
    )
])

if __name__ == '__main__':
    app.run_server()
 

Markdown

A volte potresti aver bisogno di includere molto testo nei tuoi dashboard. Puoi farlo usando l'attributo Mardown di dash_core_components come mostrato sotto.

 import dash
import dash_core_components as dcc
import dash_html_components as html

app = dash.Dash()

markdown_text = '''
### Dash and Markdown
A lot of text
'''

app.layout = html.Div([
    dcc.Markdown(children=markdown_text)
])

if __name__ == '__main__':
    app.run_server()

Componenti core

Ora vediamo alcuni dash_core_components che incontrerai usando Dash. Puoi generare un menu a tendina come mostrato sotto. Lo fai chiamando Dropdown da dash_core_components e passando le opzioni come lista di dizionari. Puoi impostare il valore predefinito usando l'attributo values passando l'opzione di default.

  dcc.Dropdown(
        options=[
            {'label': 'New York City', 'value': 'NYC'},
            {'label': u'Montréal', 'value': 'MTL'},
            {'label': 'San Francisco', 'value': 'SF'}
        ],
        value='MTL'
    )

Generare un menu a tendina multi-selezione è simile a sopra. L'unica differenza è che imposti l'attributo multi su true dato che di default è False. Puoi quindi specificare gli elementi che vuoi selezionati di default indicando l'attributo values.

    html.Label('Multi-Select Dropdown'),
    dcc.Dropdown(
        options=[
            {'label': 'New York City', 'value': 'NYC'},
            {'label': u'Montréal', 'value': 'MTL'},
            {'label': 'San Francisco', 'value': 'SF'}
        ],
        value=['MTL', 'SF'],
        multi=True
    )

I pulsanti di scelta possono essere generati usando l'attributo RadioItems. Poi passi le opzioni come lista di dizionari. Puoi anche impostare un valore predefinito specificando l'attributo values.

 html.Label('Radio Items'),
    dcc.RadioItems(
        options=[
            {'label': 'New York City', 'value': 'NYC'},
            {'label': u'Montréal', 'value': 'MTL'},
            {'label': 'San Francisco', 'value': 'SF'}
        ],
        value='MTL'
    )

Per generare caselle di controllo, richiami l'attributo Checklist da dash_core_components. Le opzioni e i valori predefiniti si passano come sopra

  html.Label('Checkboxes'),
    dcc.Checklist(
        options=[
            {'label': 'New York City', 'value': 'NYC'},
            {'label': u'Montréal', 'value': 'MTL'},
            {'label': 'San Francisco', 'value': 'SF'}
        ],
        values=['MTL', 'SF']
    )

Avrai quasi certamente bisogno di campi di input nella tua applicazione. Per generarli userai l'attributo Input. Usando il tag Html Label, puoi creare un'etichetta per il campo Input. Con l'attributo values puoi specificare del testo nel campo e con type indicare se è un campo di testo, numero, ecc.

 html.Label('Text Box'),
    dcc.Input(value='MTL', type='text')

Richiamare l'aiuto

Poiché i componenti Dash sono dichiarativi, chiamare il comando help su uno di essi genererà l'aiuto per quel componente.

help(dcc.Input)

Interattività

Vediamo ora come rendere interattive le nostre app Dash. Per farlo, dobbiamo importare Input e Output da dash.dependencies. Non confonderli con l'Input HTML perché sono diversi. L'Input HTML è importato dai componenti core di Dash. Sotto creiamo un input di testo e lo leghiamo a una callback in modo che ogni volta che digiti qualcosa in quella casella, my-div si aggiorni in tempo reale. Per abilitarlo, Dash fornisce un decorator @app che consente di collegare una funzione di callback a my-div e al campo di input HTML. Nota che usiamo il decorator prima di dichiarare la funzione update_output_div.

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

app = dash.Dash()

app.layout = html.Div([
    dcc.Input(id='my-id', value='Dash App', type='text'),
    html.Div(id='my-div')
])


@app.callback(
    Output(component_id='my-div', component_property='children'),
    [Input(component_id='my-id', component_property='value')]
)
def update_output_div(input_value):
    return 'You\'ve entered "{}"'.format(input_value)


if __name__ == '__main__':
    app.run_server()

Autenticazione

Dash fornisce l'autenticazione tramite un pacchetto separato chiamato dash-auth. Offre due modalità di autenticazione: HTTP Basic Auth e Plotly OAuth. Nel Basic Auth, codifichi a mano un set di username e password nella tua applicazione. Questo metodo presenta alcune criticità: gli utenti non possono disconnettersi dalla tua applicazione, non possono creare account o cambiare password, e sei tu responsabile di archiviare in modo sicuro username e password nel codice. Plotly OAuth fornisce l'autenticazione tramite il tuo account Plotly online ed è a pagamento.

Per configurare il Basic Auth procedi così. Per prima cosa, installa i pacchetti necessari.

 pip install dash==0.21.1
pip install dash-auth==1.0.0

Dopo questo imposta le coppie di username e password che vuoi avere nella tua applicazione.

 VALID_USERNAME_PASSWORD_PAIRS = [
    ['hello', 'world']
]

L'utility dash_auth.BasicAuth di Dash si occuperà dell'autenticazione una volta impostate le coppie di password. Tutto ciò che devi fare è passare le coppie di password e il nome della tua applicazione a dash_auth.BasicAuth.

 app = dash.Dash('auth')
auth = dash_auth.BasicAuth(
    app,
    VALID_USERNAME_PASSWORD_PAIRS
)

Hosting di dashboard su Heroku

Ospitare il tuo dashboard su Heroku è piuttosto semplice ma richiede alcuni passaggi.

Per prima cosa, crea una cartella che conterrà tutti i file del progetto. Su Ubuntu puoi farlo con il comando mkdir.

$ mkdir my_dash_app
$ cd my_dash_app

Poi inizializza la cartella con git e virtualenv. Git serve per il controllo versione e virtualenv permette di creare un ambiente virtuale per contenere tutte le dipendenze Python. Dopo aver creato l'ambiente, lo attiviamo con il comando source.

$ git init
$ virtualenv venv
$ source venv/bin/activate

Successivamente, installiamo tutti i pacchetti necessari per la nostra applicazione Dash:

$ pip install dash
$ pip install dash-renderer
$ pip install dash-core-components
$ pip install dash-html-components
$ pip install plotly

Per servire la nostra applicazione Dash, ci serve un web server Python. Non si usa mai il server di sviluppo di Flask in produzione. Per questo usiamo il web server Gunicorn. Installalo come mostrato sotto:

$ pip install gunicorn

Ora dobbiamo creare alcuni file nella nostra cartella:

1. app.py dove scriveremo la nostra applicazione dash.
2. Un .gitignore per assicurarci che i file non necessari non vengano inviati in produzione
3. Un file requirements.txt che conterrà tutte le dipendenze Python e le loro versioni.
4. Un Procfile per il deployment.

Aggiungi quanto segue ad app.py. È solo un esempio, quindi puoi usare il tuo dashboard Dash.

import os
import dash
import dash_core_components as dcc
import dash_html_components as html
app = dash.Dash(__name__)
server = app.server
app.layout = html.Div([
    html.H2('Hello World'),
    dcc.Dropdown(
        id='dropdown',
        options=[{'label': i, 'value': i} for i in ['LA', 'NYC', 'MTL']],
        value='LA'
    ),
    html.Div(id='display-value')
])
@app.callback(dash.dependencies.Output('display-value', 'children'),
              [dash.dependencies.Input('dropdown', 'value')])
def display_value(value):
    return 'You have selected "{}"'.format(value)
if __name__ == '__main__':
    app.run_server(debug=True)

È importante ricordare che alla base un'applicazione Dash è anche un'app Flask. Per il deployment, dobbiamo accedere all'istanza dell'app Flask. Dash ci permette di farlo usando 

app.server

app = dash.Dash(__name__)
server = app.server

Aggiungi i file che non vuoi inviare in produzione nel file .gitignore. Un buon .gitignore per Python è disponibile su Github

Ora specifichiamo le informazioni di deployment nel Procfile. Usiamo la variabile web per specificare il nostro server come gunicorn. Indichiamo anche i dettagli dell'app usando la variabile app. app si riferisce al nome del file app.py e server si riferisce alla variabile server all'interno di quel file.

web: gunicorn app:server

Dobbiamo anche scrivere le dipendenze Python nel file requirements. Heroku le installerà durante il deployment.

pip freeze > requirements.txt

I passaggi successivi presuppongono che tu abbia un account Heroku e abbia installato la CLI di Heroku. Se non li hai, vai su https://www.heroku.com e configurali.

Il passo successivo è creare un'app Heroku da terminale e aggiungere tutti i pacchetti della nostra applicazione. Una volta effettuato il commit delle modifiche, invia la tua applicazione al branch master di heroku. L'output di questo comando conterrà un link alla tua app Dash live su Heroku.

$ heroku create your-app-name
$ git add .
$ git commit -m 'Your-commit-message'
$ git push heroku master

Questo è un'introduzione alla creazione di un dashboard in puro Python usando Dash di Plotly. Per saperne di più su Dash visita la documentazione ufficiale.

Se ti interessa approfondire Python, dai un'occhiata al nostro Tutorial Python per Principianti e al corso Intermediate Python for Data Science.