Dash para iniciantes

Dash é um framework em Python para criar aplicações web. Ele é construído sobre Flask, Plotly.js, React e React Js. Com ele, você cria dashboards usando apenas Python. Dash é open source e seus apps rodam no navegador. Neste tutorial, apresentamos os fundamentos do Dash e partimos do pressuposto de que você já tem experiência com Plotly.

Instalação do Dash

Para começar a usar o Dash, precisamos instalar alguns pacotes.

1. O backend principal do Dash.
2. O front-end do Dash
3. Componentes HTML do Dash
4. Componentes principais do 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 de um app Dash

Uma aplicação Dash geralmente é composta de duas partes. A primeira é o layout, que descreve como o app vai aparecer, e a segunda descreve a interatividade da aplicação. O Dash oferece classes HTML que permitem gerar conteúdo HTML com Python. Para usá-las, precisamos importar dash_core_components e dash_html_components. Você também pode criar componentes personalizados com Javascript e React Js.

Para começar, vamos criar um arquivo chamado app.py no seu editor favorito e então importar esses pacotes.

import dash
import dash_core_components as dcc
import dash_html_components as html
 

Assim como no Flask, inicializamos o Dash chamando a classe Dash do pacote dash. Feito isso, podemos criar o layout da nossa aplicação. Usamos a classe Div do dash_html_components para criar uma Div HTML. Em seguida, usamos componentes HTML para gerar elementos como H1, H2 etc. O dash_html_components tem todas as tags HTML. Para criar um gráfico no nosso layout, usamos a classe Graph do dash_core_components. O Graph renderiza visualizações interativas usando plotly.js. A classe Graph espera um objeto figure com os data a serem plotados e os detalhes de layout. O Dash também permite aplicar estilos, como alterar a cor de fundo e a cor do texto. Você pode mudar o fundo usando o atributo style, passando um dicionário com as cores desejadas. No nosso caso, definimos um dicionário de cores com o fundo e o texto que queremos. Da mesma forma, podemos alterar o fundo do layout usando o atributo plot_bgcolor.

No HTML, a propriedade style é especificada com ponto e vírgula; já no Dash, passamos um dicionário. As chaves do dicionário usam camelCase, por exemplo, text-align vira textAlign. Em vez de usar classes como no HTML, usamos className no Dash.

 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 visualizar nossa aplicação, precisamos rodar o servidor web, assim como no Flask. Lembre-se: o Dash é construído sobre o Flask. Também definimos debug como true para não precisar reiniciar o servidor sempre que fizermos alterações.

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

Depois, vá ao terminal e inicie o servidor com: python app.py

Isso iniciará um novo servidor web em http://127.0.0.1:8050/. Acesse e veja seu dashboard novinho em folha.

Gerando gráficos de dispersão

Para criar um scatter plot, importamos os componentes do Dash como fizemos antes. Também precisamos importar os graph_objs do Plotly para plotar o gráfico de dispersão. Como mencionado, usamos a classe Div e o componente Graph do Dash para isso. O Graph recebe um objeto figure com os dados e a descrição do layout. Plotamos o gráfico de dispersão usando a propriedade scatter de graph_objs. Para garantir que seja um scatter plot, passamos o atributo mode como markers. Caso contrário, teríamos linhas no 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

Às vezes, você vai precisar incluir bastante texto nos seus dashboards. Você pode fazer isso usando o atributo Mardown de dash_core_components, como abaixo.

 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 principais

Agora, vamos ver alguns dash_core_components que você vai encontrar ao usar o Dash. É possível gerar um menu suspenso (drop-down) como no exemplo abaixo. Para isso, chamamos Dropdown de dash_core_components e passamos as opções como uma lista de dicionários. Você pode definir o valor padrão usando o atributo values, passando a opção desejada.

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

Gerar um drop-down multisseleção é parecido com o anterior. A única diferença é definir o atributo multi como true (por padrão é False). Depois, especifique os itens que devem vir selecionados informando o 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
    )

Botões de rádio podem ser gerados com o atributo RadioItems. Passe as opções como uma lista de dicionários. Também dá para definir um valor padrão especificando o 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 criar checkboxes, use o atributo Checklist de dash_core_components. As opções e os valores padrão são passados da mesma forma que acima.

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

Com certeza você vai precisar de campos de entrada de texto na sua aplicação. Para gerá-los, use o atributo Input. Com a tag Html Label, você cria um rótulo para o campo de entrada. Com o atributo values você define um texto padrão, e com type indica se é um campo de texto, número etc.

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

Chamando a ajuda

Como os componentes do Dash são declarativos, chamar o comando de ajuda em qualquer um deles exibe a documentação daquele componente.

help(dcc.Input)

Interatividade

Agora vamos ver como deixar nossos apps Dash interativos. Para isso, precisamos importar Input e Output de dash.dependencies. Não confunda com o HTML Input, pois são coisas diferentes. O Input HTML é importado dos core components do Dash. Abaixo, criamos um campo de texto e o vinculamos a um callback para que, sempre que você digitar algo, o conteúdo de my-div seja atualizado em tempo real. Para habilitar isso, o Dash oferece o decorador @app, que permite associar uma função de callback ao my-div e ao campo de entrada. Note que usamos o decorador antes de declarar a função 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()

Autenticação

O Dash oferece autenticação por meio de um pacote separado chamado dash-auth. Ele fornece dois modos de autenticação: HTTP Basic Auth e Plotly OAuth. No Basic Auth, você fixa no código um conjunto de nomes de usuário e senhas. Esse método tem limitações, como: usuários não conseguem sair da aplicação, não conseguem criar contas ou alterar senhas, e você fica responsável por armazenar credenciais com segurança no seu código. O Plotly OAuth usa sua conta online do Plotly para autenticar e não é gratuito.

Para configurar o Basic Auth, siga os passos. Primeiro, instale os pacotes necessários.

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

Depois, defina os pares de usuário e senha que você quer na sua aplicação.

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

A utilidade dash_auth.BasicAuth do Dash cuida da autenticação para você assim que os pares forem definidos. Tudo que você precisa fazer é passar os pares e o nome da sua aplicação para dash_auth.BasicAuth.

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

Hospedando dashboards no Heroku

Hospedar seu dashboard no Heroku é relativamente simples, mas envolve algumas etapas.

Primeiro, crie um diretório para armazenar os arquivos do seu projeto. No Ubuntu, você pode usar o comando mkdir.

$ mkdir my_dash_app
$ cd my_dash_app

Depois, inicialize a pasta com git e virtualenv. O Git é para controle de versão, e o virtualenv permite criar um ambiente virtual com todas as dependências do Python. Após criar o ambiente, ative-o com o comando source.

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

Em seguida, instale todos os pacotes necessários para a nossa aplicação Dash:

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

Para servir nossa aplicação Dash, precisamos de um servidor web em Python. Nunca usamos o servidor de desenvolvimento do Flask em produção. Para isso, usamos o Gunicorn. Instale-o assim:

$ pip install gunicorn

Agora, precisamos criar alguns arquivos na pasta:

1. app.py, onde vamos codificar nossa aplicação Dash.
2. Um .gitignore para garantir que arquivos desnecessários não sejam enviados para produção
3. Um requirements.txt com todas as dependências do Python e suas versões.
4. Um Procfile para deployment.

Adicione o seguinte ao app.py. É apenas um exemplo — você pode usar o seu próprio dashboard em 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)

Vale lembrar que, no núcleo, um app Dash também é um app Flask. Para fazer o deployment, precisamos acessar a instância da aplicação Flask. O Dash permite isso por meio de

app.server

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

Adicione ao .gitignore os arquivos que você não quer enviar para produção. Um bom .gitignore para Python está disponível no Github.

Agora vamos especificar as informações de deployment no Procfile. Usamos a variável web para indicar que nosso servidor é o gunicorn. Também informamos os detalhes do app usando a variável app. app se refere ao arquivo app.py e server se refere à variável server dentro dele.

web: gunicorn app:server

Também precisamos escrever nossas dependências Python no requirements.txt. O Heroku as instalará durante o deployment.

pip freeze > requirements.txt

Os próximos passos assumem que você tem uma conta no Heroku e instalou o Heroku CLI. Se ainda não tiver, acesse https://www.heroku.com para configurar.

Em seguida, crie um app Heroku no terminal e adicione todos os arquivos da aplicação. Depois de fazer o commit das mudanças, envie sua aplicação para o branch master do Heroku. A saída desse comando terá um link para seu app Dash ao vivo no Heroku.

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

Este foi um guia introdutório para construir um dashboard em Python puro usando o Dash da Plotly. Para saber mais sobre o Dash, visite a documentação oficial.

Se você quer aprender mais sobre Python, confira nosso tutorial de Python para iniciantes e o curso Intermediate Python for Data Science.