Dash voor beginners

Dash is een Python-framework voor het bouwen van webapps. Het is gebouwd bovenop Flask, Plotly.js, React en React Js. Het stelt je in staat om dashboards te bouwen met puur Python. Dash is open source en de apps draaien in de webbrowser. In deze tutorial introduceren we de basis van Dash en gaan we ervan uit dat je al ervaring hebt met Plotly.

Dash installeren

Om met Dash te werken, moeten we een aantal packages installeren.

1. De core Dash-backend.
2. Dash-frontend
3. Dash HTML components
4. Dash core components
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

Dash-app lay-out

Een Dash-app bestaat meestal uit twee delen. Het eerste deel is de lay-out en beschrijft hoe de app eruitziet, en het tweede deel beschrijft de interactiviteit van de applicatie. Dash biedt HTML-klassen waarmee we HTML-content met Python kunnen genereren. Om deze klassen te gebruiken, moeten we dash_core_components en dash_html_components importeren. Je kunt ook je eigen aangepaste componenten maken met JavaScript en React Js.

Om te beginnen maken we een bestand met de naam app.py met onze favoriete teksteditor en importeren we deze packages.

import dash
import dash_core_components as dcc
import dash_html_components as html
 

Net als in Flask initialiseren we Dash door de Dash-klasse van dash aan te roepen. Zodra dat is gebeurd, kunnen we de lay-out voor onze applicatie maken. We gebruiken de Div-klasse uit dash_html_components om een HTML Div te maken. Vervolgens gebruiken we de HTML-componenten om HTML-elementen zoals H1, H2 enz. te genereren. dash_html_components bevat alle HTML-tags. Om een grafiek in onze lay-out te maken, gebruiken we de Graph-klasse uit dash_core_components. Graph rendert interactieve datavisualisaties met plotly.js. De Graph-klasse verwacht een figure-object met de data die geplot moet worden en de layout-details. Dash laat je ook stijlen toepassen, zoals het wijzigen van de achtergrondkleur en tekstkleur. Je kunt de achtergrond wijzigen met het style-attribuut en een object met je specifieke kleur doorgeven. In ons geval hebben we een kleurendictionary gedefinieerd met de gewenste achtergrond- en tekstkleur. Op dezelfde manier kunnen we de lay-outachtergrond wijzigen met het plot_bgcolor-attribuut.

In HTML wordt de style-eigenschap gespecificeerd met een puntkomma, maar in Dash geef je een dictionary op. De keys in de dictionary zijn in camelCase, bijv. text-align wordt textAlign. In plaats van classes zoals in HTML wordt in Dash className gebruikt.

 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']
                }
            }
        }
    )
])
 

Om onze visualisatie te bekijken, moeten we onze webserver draaien, net als in Flask. Onthoud dat Dash bovenop Flask is gebouwd. We zetten debug ook op true zodat we de server niet telkens hoeven te verversen wanneer we iets wijzigen

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

Ga vervolgens naar de terminal en start de server door de onderstaande code te typen: python app.py

Dit start een nieuwe webserver op http://127.0.0.1:8050/. Ga daarheen en bekijk je zojuist gemaakte dashboard.

Scatterplots genereren

Om een scatterplot te maken, importeren we de gebruikelijke Dash-componenten zoals eerder gedaan. We moeten ook Plotly graph_objs importeren om de scatterplot te tekenen. Zoals eerder vermeld gebruiken we de Div-klasse en Graph-componenten van Dash om dit te realiseren. De Graph-component neemt een figure-object met de data en de lay-outbeschrijving. We plotten de scatterplot met de graph_objs-eigenschap scatter. Om ervoor te zorgen dat de plot een scatterplot is, geven we een mode-attribuut mee en zetten dat op markers. Anders zouden er lijnen in de grafiek staan.

 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

Soms wil je veel tekst in je dashboards opnemen. Dat kan met het Mardown-attribuut van dash_core_components, zoals hieronder getoond.

 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()

Core Components

Laten we vervolgens kijken naar enkele dash_core_components die je tegenkomt wanneer je Dash gebruikt. Je kunt een dropdown genereren zoals hieronder. Dat doe je door Dropdown van dash_core_components aan te roepen en de opties als een lijst met dictionaries door te geven. Je kunt de standaardwaarde instellen met het values-attribuut en de standaardoptie meegeven.

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

Een multi-select dropdown genereren is vergelijkbaar met bovenstaande. Het enige verschil is dat je het multi-attribuut op true zet, omdat dit standaard False is. Je kunt vervolgens de items opgeven die je standaard geselecteerd wilt hebben door het values-attribuut te specificeren.

    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
    )

Radioknoppen kun je genereren met het RadioItems-attribuut. Je geeft vervolgens de opties door als een lijst met dictionaries. Je kunt ook een standaardwaarde instellen door het values-attribuut te specificeren.

 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'
    )

Voor selectievakjes roep je het Checklist-attribuut van dash_core_components aan. De opties en standaardwaarden worden zoals hierboven doorgegeven

  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']
    )

Je hebt vrijwel zeker tekstinvoer nodig in je applicatie. Om die te genereren gebruik je het Input-attribuut. Met de HTML Label-tag kun je een label maken voor het invoerveld. Met het values-attribuut kun je tekst in het veld zetten en met type aangeven of het een tekstveld, nummer, enz. is.

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

Help aanroepen

Omdat Dash-componenten declaratief zijn, geeft het aanroepen van de help-opdracht op een component de help voor die component.

help(dcc.Input)

Interactiviteit

Laten we nu behandelen hoe we onze Dash-apps interactief kunnen maken. Hiervoor moeten we Input en Output importeren uit dash.dependencies. Verwissel deze niet met de HTML Input, want die zijn anders. De HTML Input wordt geïmporteerd uit de dash core components. Hieronder maken we een tekstinvoer en koppelen we die aan een callback zodat, wanneer je iets in dat vak typt, my-div realtime wordt bijgewerkt. Om dit mogelijk te maken biedt Dash een decorator @app die het mogelijk maakt een callbackfunctie te binden aan my-div en het HTML-invoerveld. Let op dat we de decorator gebruiken vóórdat we de functie update_output_div declareren.

 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()

Verificatie

Dash biedt authenticatie via een apart pakket genaamd dash-auth. Het biedt twee vormen van authenticatie: HTTP Basic Auth en Plotly OAuth. Bij Basic Auth hardcodeer je in je applicatie een set gebruikersnamen en wachtwoorden. Deze methode heeft enkele uitdagingen, zoals dat gebruikers niet kunnen uitloggen uit je applicatie, geen accounts kunnen aanmaken of wachtwoorden kunnen wijzigen, en jij verantwoordelijk bent voor het veilig opslaan van de gebruikersnamen en wachtwoorden in je code. Plotly OAuth biedt authenticatie via je online Plotly-account, en is niet gratis.

Om Basic Auth op te zetten, ga je als volgt te werk. Installeer eerst de benodigde packages.

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

Stel daarna de gebruikersnaam- en wachtwoordparen in die je in je applicatie wilt hebben.

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

De utility dash_auth.BasicAuth van Dash regelt de authenticatie voor je zodra de wachtwoordparen zijn ingesteld. Alles wat je hoeft te doen is de wachtwoordparen en je applicatienaam doorgeven aan dash_auth.BasicAuth.

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

Dashboards hosten op Heroku

Je dashboard hosten op Heroku is vrij eenvoudig, maar vereist een paar stappen.

Maak eerst een map die alle bestanden van je project bevat. Op Ubuntu kan dat met het commando mkdir.

$ mkdir my_dash_app
$ cd my_dash_app

Initialiseer vervolgens de map met git en virtualenv. Git is voor versiebeheer en virtualenv stelt ons in staat een virtuele omgeving te creëren voor al onze Python-afhankelijkheden. Nadat we de omgeving hebben gemaakt, activeren we deze met het commando source.

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

Vervolgens installeren we alle packages die we nodig hebben voor onze Dash-applicatie:

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

Om onze Dash-app te serveren, hebben we een Python-webserver nodig. We gebruiken nooit de ontwikkelingsserver van Flask in productie. Voor deze functie gebruiken we de webserver Gunicorn. Installeer deze als volgt:

$ pip install gunicorn

Vervolgens moeten we een paar bestanden in onze map maken:

1. app.py waarin we onze Dash-applicatie coderen.
2. Een .gitignore om ervoor te zorgen dat onnodige bestanden niet naar productie worden gepusht
3. Een requirements.txt-bestand met alle Python-afhankelijkheden en hun versies.
4. Een Procfile voor deployment.

Voeg het volgende toe aan app.py. Dit is slechts een voorbeeld; je kunt je eigen Dash-dashboard gebruiken.

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)

Het is belangrijk om te onthouden dat een Dash-applicatie in de kern ook een Flask-applicatie is. Voor deploymentdoeleinden moeten we toegang hebben tot de Flask-applicatie-instantie. Dash stelt ons in staat dit te doen met 

app.server

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

Voeg de bestanden die je niet naar productie wilt pushen toe aan het .gitignore-bestand. Een goed Python .gitignore-bestand is beschikbaar op Github

Nu specificeren we onze deploymentinformatie in de Procfile. We gebruiken de web-variabele om onze server als gunicorn op te geven. We specificeren ook onze app-details met behulp van de app-variabele. app verwijst naar de bestandsnaam app.py en server verwijst naar de servervariabele in dat bestand.

web: gunicorn app:server

We moeten onze Python-afhankelijkheden ook naar het requirements-bestand schrijven. Heroku installeert ze tijdens deployment.

pip freeze > requirements.txt

De volgende stappen gaan ervan uit dat je een Heroku-account hebt en de Heroku CLI hebt geïnstalleerd. Als je die nog niet hebt, ga dan naar https://www.heroku.com en stel ze in.

De volgende stap is om via de terminal een Heroku-app te maken en al onze applicatiebestanden toe te voegen. Zodra je de wijzigingen hebt gecommit, push je je applicatie naar heroku master. De output van dit commando bevat een link naar je live Dash-applicatie op Heroku.

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

Dit is een introductie tot het bouwen van een dashboard in puur Python met Dash van Plotly. Wil je meer leren over Dash, bekijk dan de officiële docs.

Als je meer over Python wilt leren, bekijk dan onze Python Tutorial voor Beginners en Intermediate Python for Data Science-cursus.