Dash para principiantes

Dash es un framework de Python para crear aplicaciones web. Está construido sobre Flask, Plotly.js, React y React Js. Te permite crear paneles usando solo Python. Dash es de código abierto y sus apps se ejecutan en el navegador. En este tutorial, te presentamos los fundamentos de Dash y asumimos que ya tienes experiencia previa con Plotly.

Instalación de Dash

Para empezar a usar Dash, tenemos que instalar varios paquetes.

1. El backend principal de Dash.
2. El front-end de Dash
3. Componentes HTML de Dash
4. Componentes básicos de 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

Diseño de una app de Dash

Una aplicación Dash suele componerse de dos partes. La primera es el layout, que define el aspecto de la app, y la segunda describe su interactividad. Dash ofrece clases HTML que nos permiten generar contenido HTML con Python. Para usarlas, hay que importar dash_core_components y dash_html_components. También puedes crear tus propios componentes con Javascript y React Js.

Para empezar, crearemos un archivo llamado app.py con nuestro editor de texto favorito e importaremos estos paquetes.

import dash
import dash_core_components as dcc
import dash_html_components as html
 

Igual que en Flask, inicializamos Dash llamando a la clase Dash de dash. Una vez hecho, podemos crear el layout de nuestra aplicación. Usamos la clase Div de dash_html_components para crear un Div de HTML. Luego utilizamos los componentes HTML para generar elementos como H1, H2, etc. dash_html_components incluye todas las etiquetas HTML. Para crear un gráfico en nuestro layout, usamos la clase Graph de dash_core_components. Graph representa visualizaciones interactivas con plotly.js. La clase Graph espera un objeto figure con los data a representar y los detalles de layout. Dash también permite aplicar estilos, como cambiar el color de fondo y del texto. Puedes modificar el fondo con el atributo style pasando un diccionario con tu color. En nuestro caso, definimos un diccionario de colores con el fondo y el color del texto que queremos. Del mismo modo, puedes cambiar el fondo del layout con el atributo plot_bgcolor.

En HTML la propiedad style se especifica con punto y coma, pero en Dash se pasa un diccionario. Las claves del diccionario usan camelCase; por ejemplo, text-align es textAlign. En lugar de usar classes como en HTML, en Dash se 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']
                }
            }
        }
    )
])
 

Para ver nuestra visualización, necesitamos ejecutar el servidor web igual que en Flask. Recuerda que Dash está construido sobre Flask. También activamos debug para no tener que reiniciar el servidor cada vez que hagamos cambios.

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

Después, ve al terminal e inicia el servidor escribiendo: python app.py

Esto iniciará un nuevo servidor web en http://127.0.0.1:8050/. Entra y verás tu panel recién creado.

Generar gráficos de dispersión

Para dibujar un scatter plot, importamos los componentes habituales de Dash como antes. También necesitamos importar graph_objs de Plotly para trazar el gráfico de dispersión. Como comentamos, usamos la clase Div y el componente Graph de Dash para conseguirlo. El componente Graph recibe un objeto figure con los datos y la descripción del layout. Representamos el scatter plot usando la propiedad scatter de graph_objs. Para asegurarnos de que el gráfico sea de dispersión, pasamos un atributo mode con valor markers. En caso contrario, veríamos líneas en el gráfico.

 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 veces necesitarás incluir mucho texto en tus paneles. Puedes hacerlo con el atributo Mardown de dash_core_components, como se muestra a continuación.

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

Componentes básicos

Ahora veamos algunos dash_core_components que encontrarás al usar Dash. Puedes generar un menú desplegable como el de abajo. Se hace llamando a Dropdown de dash_core_components y pasando las opciones como una lista de diccionarios. Puedes establecer el valor por defecto con el atributo values pasando la opción predeterminada.

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

Generar un desplegable de selección múltiple es similar. La única diferencia es que estableces el atributo multi en true (por defecto es False). Luego puedes indicar los elementos seleccionados por defecto con el atributo 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
    )

Los botones de opción se pueden generar con el atributo RadioItems. Pasas las opciones como una lista de diccionarios. También puedes establecer un valor por defecto con el atributo 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'
    )

Para generar casillas de verificación, usa el atributo Checklist de dash_core_components. Las opciones y los valores por defecto se pasan como antes.

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

Seguramente necesites campos de texto en tu aplicación. Para generarlos usarás el atributo Input. Con la etiqueta Html Label puedes crear una etiqueta para el campo Input. Con el atributo values puedes especificar texto inicial en el campo y, para indicar el tipo, usa type y define si es texto, número, etc.

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

Usar la ayuda

Dado que los componentes de Dash son declarativos, si llamas a help sobre cualquiera de ellos obtendrás su documentación.

help(dcc.Input)

Interactividad

Vamos a ver cómo hacer que nuestras apps de Dash sean interactivas. Para ello, tenemos que importar Input y Output desde dash.dependencies. No los confundas con el Input de HTML, porque no son lo mismo. El Input de HTML se importa desde los componentes básicos de Dash. Abajo creamos un campo de texto y lo vinculamos a un callback de modo que, cuando escribas algo en esa caja, se actualice my-div en tiempo real. Para habilitarlo, Dash proporciona un decorador @app que permite vincular una función de callback a my-div y al campo de entrada HTML. Fíjate en que usamos el decorador antes de declarar la función 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()

Autenticación

Dash ofrece autenticación mediante un paquete aparte llamado dash-auth. Proporciona dos modos de autenticación: HTTP Basic Auth y Plotly OAuth. En Basic Auth, defines en tu aplicación un conjunto de usuarios y contraseñas. Este método tiene inconvenientes: las personas no pueden cerrar sesión, no pueden crear cuentas ni cambiar contraseñas, y tú eres responsable de almacenar de forma segura esos datos en tu código. Plotly OAuth autentica a través de tu cuenta online de Plotly, y no es gratuito.

Para configurar Basic Auth, sigue estos pasos. Primero, instala los paquetes necesarios.

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

Después, define los pares de usuario y contraseña que quieres en tu aplicación.

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

La utilidad dash_auth.BasicAuth de Dash se encargará de la autenticación una vez que hayas definido los pares de credenciales. Solo tienes que pasarle esos pares y el nombre de tu aplicación a dash_auth.BasicAuth.

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

Alojar paneles en Heroku

Alojar tu panel en Heroku es bastante sencillo, pero requiere varios pasos.

Primero, crea un directorio que contenga todos los archivos del proyecto. En Ubuntu puedes hacerlo con el comando mkdir.

$ mkdir my_dash_app
$ cd my_dash_app

Después, inicializa la carpeta con git y virtualenv. Git es para el control de versiones y virtualenv permite crear un entorno virtual con todas las dependencias de Python. Tras crear el entorno, lo activamos con el comando source.

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

A continuación, instalamos todos los paquetes necesarios para nuestra app de Dash:

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

Para servir nuestra aplicación Dash necesitamos un servidor web de Python. Nunca usamos el servidor de desarrollo de Flask en producción. Para esto usamos el servidor web Gunicorn. Instálalo así:

$ pip install gunicorn

Ahora necesitamos crear algunos archivos en la carpeta:

1. app.py, donde programaremos nuestra aplicación de Dash.
2. Un .gitignore para evitar subir archivos innecesarios a producción.
3. Un requirements.txt con todas las dependencias de Python y sus versiones.
4. Un Procfile para el despliegue.

Añade lo siguiente a app.py. Es solo un ejemplo: puedes usar tu propio panel de 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)

Conviene recordar que, en el fondo, una app de Dash también es una app de Flask. Para desplegar, necesitamos acceder a la instancia de Flask. Dash nos permite hacerlo con 

app.server

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

Añade al archivo .gitignore los ficheros que no quieras subir a producción. En GitHub tienes un buen .gitignore para Python.

Ahora especificamos la información de despliegue en el Procfile. Usamos la variable web para indicar que el servidor es gunicorn. También indicamos los detalles de la app con la variable app. app hace referencia al nombre del archivo app.py y server a la variable server dentro de ese archivo.

web: gunicorn app:server

También necesitamos escribir nuestras dependencias de Python en el archivo requirements. Heroku las instalará durante el despliegue.

pip freeze > requirements.txt

Los siguientes pasos asumen que tienes una cuenta de Heroku y has instalado la CLI de Heroku. Si no, entra en https://www.heroku.com y configúralo.

Ahora crea una app de Heroku desde el terminal y añade todos los archivos de tu aplicación. Cuando hayas hecho commit de los cambios, sube tu aplicación a heroku master. La salida de este comando incluirá un enlace a tu app de Dash en Heroku.

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

Este artículo es una introducción a cómo construir un panel con puro Python usando Dash de Plotly. Para saber más sobre Dash, visita la documentación oficial.

Si te interesa aprender más sobre Python, echa un vistazo a nuestro tutorial de Python para principiantes y al curso de Intermediate Python for Data Science.