Enter: The dip

A first observation to make from the graph above is the peculiar dip in the number of registrations for the vaccinations by the end of January. Yet looking at how the trend is reversed right after the beginning of the vaccination campaign, it seems to me that an explanation, and an answer, arise. With 52 days between the launch of EVAX and the first day of the vaccination campaign, registration efforts were bound to fizzle out with no immediate or foreseeable outcome in sight. More importantly, a variety of phenomena can explain the registration rate of Tunisians following the beginning of the vaccination campaign. Firstly, the economic crisis and the inconsistent signals provided by the government regarding their ability to purchase the necessary vaccine quantities are certainly a hindrance for any effort to onboard people on EVAX. Secondly, a notable failure of the COVID-19 national strategy was the lack of communication on the safety of the vaccines. The void left by this absence left room for a variety of rumors and misinformation / disinformation to plague the public discourse about vaccines.

The crestfallen bunch

Right before Eid al-Adha, a Facebook post on the Health ministry’s page announced Vaccination Open Days on the 19^th of July, at 3:21 PM, for anyone older than 18. The announcement caused a lot of confusion and excitement. A registration frenzy ensued: 45 566 people between the ages 18 and 30 registered on the 19^th. That’s 17 211 more registrations than the next day with the most registrations for that age group. The interest of the young groups, however, precedes this event. The graph below shows that the 30-40 had climbed two positions to become the second most registering age group by the 12^th of July. As well as the 18-30 group that became the highest ranking group on the 16^th of July. Thus dispelling the last drop of doubt that Tunisians are ‘unaware’ of the importance of vaccinations. Instead, what Tunisians needed was .. vaccines.

Crestfallen : disappointed and sad because of having failed unexpectedly. – Cambridge Dictionary

The disappointment followed the Eid al-Adha’s episode is one to be remembered, hopefully long enough to punish those responsible. A simple look at the data readily available on EVAX would have made is sufficiently clear that calling upon every Tunisian old enough to be vaccinated within two days was an exercise in stupidity and tomfoolery. With the absence of common sense that is.

Reactivity and Callbacks

Even if you don’t know what reactive programming means you’ve most likely used it in … Excel.

In Excel, when we use a formula to compute the sum of two cells, as soon as a value in the summation changes, the formula cell recomputes its value in reaction.

The equivalent idea to an Excel formula for Dash is a callback function.

@app.callback(
    output=Output("ouput-cell", "value"),
    inputs=[Input("cell-1", "value"), Input("cell-2", "value")],
)
def sum_of_cell1_and_cell2(value_of_cell1, value_of_cell2):
    return value_of_cell1 + value_of_cell2

In the highlighted lines 1-4, we are saying that the attribute value of an object with and ID of output-cell should react to changes in the value attribute of the objects with ID cell-1 and cell-2.

@app.callback(
    output=Output("ouput-cell", "value"),
    inputs=[Input("cell-1", "value"), Input("cell-2", "value")],
)
def sum_of_cell1_and_cell2(value_of_cell1, value_of_cell2):
    return value_of_cell1 + value_of_cell2

In the function definition we describe how the value attribute of output-cell should react to a change in the value attribute of cell-1 and / or cell-2. In our case that would be to return the sum of the values.

It is not important to focus on the syntax for now, we are simply building a conceptual model of how Dash works. One question that arises from the snippet we have just seen is what are output-cell, cell-1 and cell-2 ?

Layout

To continue our Excel simile, let us think of an Excel cell as a special kind of user interface components. In essence, a cell in a spredsheet is not that much different from an input box, a checkbox, or a dropdown list. These user interface elements can hold various attributes of their own, including a value attribute, and allow the user to trigger callbacks which ultimately allows our dashboard to react to user input.

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

app = dash.Dash(__name__)

app.layout = html.Div(
    children=[
        dcc.Input(id="cell-1", type="number", value=30),
        dcc.Input(id="cell-2", type="number", value=4),
        html.H1(id="output-cell"),
    ]
)

@app.callback(
    output=Output("output-cell", "children"),
    inputs=[Input("cell-1", "value"), Input("cell-2", "value")],
)
def sum_of_cell1_and_cell2(value_of_cell1, value_of_cell2):
    return int(value_of_cell1) + int(value_of_cell2)

if __name__ == "__main__":
    app.run_server(host="localhost", debug=True)

With the addition of a layout as described in the lines 8 through 14, our dashboard can now display a user interface, and react to changes triggered by user input. Running the code above results in the following “dashboard”

Virtual environment and dependencies installation

For this project we will need to install the following dependencies:

• dash is the library that will provide two components for our project: the dashboarding and the plotting through plotly-express which we will introduce as we go.
• dash-bootstrap-components will allow us to theme our app using Bootstrap which provides useful layout capabilities and interesting components. For this tutorial we will limit ourselves to using the Grid
• pandas which we will use for the data manipulation part.
• geopandas will be of use when plotting data on a map.
• pyprojroot is a small utility library that allows us to reference files inside our project using paths relative the root of our project instead of absolute long paths.

You can install them using the following command

pip install dash==1.11.0 dash-bootstrap-components pandas geopandas requests pyprojroot

It is recommended that you create a virtual environment for your project. That can be done easily (assuming you’re running a Unix based system):

md covid_dash
cd covid_dash
python -m venv .venv
source .venv/bin/activate

Directory structure

The directory structure that we will need looks as follows

.
├── data
│  └── raw
└── src
   ├── __init__.py
   ├── app.py
   ├── callbacks.py
   ├── cli.py
   ├── data.py
   ├── index.py
   ├── layouts.py
   └── plots.py

To create it you can run the following commands

md -p plotly_dash_tutorial/{data/raw,src}
cd plotly_dash_tutorial
touch src/__init__.py # Making a python package named src
touch src/{app.py,index.py} # General application / dashboard code
touch src/{callbacks.py,layouts.py} # Plotly dash specific code
touch src/{plots.py,data.py} # The model part of our application

Application setup

To setup our app, we need to create an app object. This object is central to our application in the sense that it acts as the orchestrator of the interaction between our layout components through the callbacks we define.

In addition to creating a Dash app object, we pass style information through the external_stylesheets key word.

app.py

import dash

import dash_bootstrap_components as dbc

app = dash.Dash(__name__, external_stylesheets=[dbc.themes.YETI, "custom.css"])

index.py will act as the entry point to our dashboard. The lines 7-8 allow python to call the run_server method from our Dash app object if index.py is called from the command line. The key word debug provides us with autoreload and more expressive UI side error, therefore when developing a dashboard it is recommended that it be set to True.

You may notice that we’ve only used two of our imports in the body of index.py. We used the app to start a server for our dashboard, and use the layout import to attach it to our app object, what about callbacks ? One may be inclined to remove the line importing callbacks but that would mean that our app will not have access to any logic we define in our callbacks.

index.py

from . import callbacks
from .app import app
from .layouts import layout

app.layout = layout

if __name__ == "__main__":
    app.run_server(host="localhost", debug=True)

Creating the layout

layouts.py

import dash_bootstrap_components as dbc
import dash_core_components as dcc
import dash_html_components as html

Let’s begin by discussing the imported modules for layouts.py. dash_bootstrap_components, dash_core_components and dash_html_components contain components which correspond to HTML elements. These are what largely liberates the developers from actually writing HTML, CSS which are responsible for the View layer of our dashboard. The components provided by these modules can vary in complexity from being a mere text container such as html.H1 to a full interactive table such as dcc.DataTable. It is generally useful to keep the documentation from theses modules open in a side tab while creating the dashboard.

The general layout of our page is composed of two major containers, a sidebar and a main content area.

Our main container uses the self-descriptive component bcc.Container. It is, however, important that we understand that despite this component and similar layout components, do not translate directly into visible elements on our page, they modify the position of elements on the page. In addition, the Container component comes with the added benefit of adding responsivity to our page thanks to being based on Bootstrap, which further improves the usability of our dashboard.

As a rule of thumb, components from dash_html_components correspond to HTML elements, and they are named as such. For instance, an h1 element in raw HTML corresponds to html.H1 (notice the capitalization). By contrast, components from dash_core_components contain components with interactivity baked into them such as tabs, dropdown lists and data tables.

layouts.py

SIDEBAR_STYLE = {
    "position": "fixed",
    "top": 0,
    "left": 0,
    "bottom": 0,
    "width": "18rem",
    "padding": "2rem 1rem",
    "background-color": "#f8f9fa",
}

MAIN_CONTAINER_STYLE = {
    "margin-left": "18rem",
    "margin-right": "2rem",
    "padding": "2rem 1rem",
    "height": "100vh",
}

sidebar = html.Div(
    [
        html.H3("COVID19 dashboard for cases in Tunisia"),
        html.Hr(),
    ],
    style=SIDEBAR_STYLE,
)

main_container = dbc.Container(
    [
        dcc.Loading(
            dcc.Graph(
                id="main_graph",
                figure=figure,
            )
        ),
    ],
    style=MAIN_CONTAINER_STYLE,
    id="main_container",
)

layout = dbc.Container([sidebar, main_container], fluid=True)

As for the dictionaries SIDEBAR_STYLE and MAIN_CONTENT_STYLE they are used to show that there are multiple ways to define the style and layout of our components. In both cases, we must provide valid CSS rules. Dictionaries of style may be useful when we have a style rule specific to a component or simply as a shorthand for writing an external CSS stylesheet.

It is also worth noting that we must assign and id to each component we will interact with later on in our callbacks.

layouts.py

id="main_container"

Finally, we define our root container and simply set sidebar and main_container as its children.

Now we will go over the specific components that we will use in this dashboard:

view_selector = html.Div(
    [
        html.H4("Dashboard view"),
        dcc.RadioItems(
            id="content_view_selector",
            options=[
                {"label": "Map view", "value": "map"},
                {"label": "Line chart view", "value": "line"},
                {"label": "Bar race chart view", "value": "bar_race"},
            ],
            value="map",
            labelStyle={"display": "block"},
        ),
    ]
)

indicator_selector = html.Div(
    [
        html.H4("Indicator"),
        dcc.Dropdown(
            id="indicator_selector",
            options=[
                {"label": indicator, "value": indicator}
                for indicator in by_gov_indicators
            ],
            value=by_gov_indicators[0],
            clearable=False,
        ),
    ]
)

dcc.Graph(
    id="main_graph",
    figure=figure,
)

from dash.dependencies import Input, Output
from .app import app

from .plots import (
    plot_daily_cumulative_active_cases,
    plot_part_of_daily_active_cases,
    plot_race_plot_of_cumulative_daily_active_cases,
)
from .data import geo_targa_covid_df


@app.callback(
    Output("main_graph", "figure"),
    [Input("content_view_selector", "value"), Input("indicator_selector", "value")],
)
def update_main_content(view, indicator):
    if view == "map" or view is None:
        return plot_part_of_daily_active_cases(geo_targa_covid_df, indicator)
    elif view == "line":
        return plot_daily_cumulative_active_cases(geo_targa_covid_df, indicator)
    else:
        return plot_race_plot_of_cumulative_daily_active_cases(
            geo_targa_covid_df, indicator
        )

from dash.dependencies import Input, Output
from .app import app

@app.callback(
    Output("main_graph", "figure"),
    [Input("content_view_selector", "value"), Input("indicator_selector", "value")],
)
def update_main_content(view, indicator):
    if view == "map" or view is None:
        return plot_part_of_daily_active_cases(geo_targa_covid_df, indicator)
    elif view == "line":
        return plot_daily_cumulative_active_cases(geo_targa_covid_df, indicator)
    else:
        return plot_race_plot_of_cumulative_daily_active_cases(
            geo_targa_covid_df, indicator
        )