Dash

Christopher G. Healey

Introduction

This module will introduce you to Dash, a framework that integrates Python, plotly, and Flask to construct web-based dashboard in Python. We will work through a number of simple examples of loading data, visualizing it with Python's built-in graphics operations, then integrating those visualizations into an interactive Dash web dashboard, which can be viewed online by anyone with a web browser.

In order to fully understand how to use Dash, you need to also understand basic HTML5, plotly, and Python. HTML5 is used to define the layout of the elements in your dashboard. plotly is used to construct graphical components (visualizations) within your dashboard. Finally, Python ties everything together to control used interaction and changes on the dashboard based on the user's interaction choices.

Setup

In order to use the Dash examples in this tutorial, you will need to add the dash Python package. To do this, run the Anaconda Prompt as an administrator, and at the command line enter the following.

HTML5

HTML (Hypertext Markup Language) is used to create the layout (sections, paragraphs, headings, links, and so on) for web pages and web applications. In 1989, Tim Berners-Lee developed the concept for HTML while working in the computer services section of CERN, the European Laboratory for Particle Physics in Geneva. Berners-Lee suggested that, rather than downloading research documents as files from individual computers, you could instead link to the text of the files themselves. This would form a cross-reference system between research documents. From one research paper, you could display the content of another paper that held relevant text or diagrams. The cross-reference system could be seen as a web of information held across computers throughout the world.

Berners-Lee's idea was followed by Hypercard, a filing-card type application for the Apple Macintosh built by Bill Atkinson. The main limitation of this system was that hypertext jumps could only be made on files held on the same computer. In the mid 90s, the Internet developed the Domain Name System (DNS) that mapped easy-to-remember names like www.ncsu.edu to their corresponding IP addresses, a unique locator for a given domain. Berners-Lee built on this to develop the HyperText Transfer Protocol (HTTP) and the HyperText Markup Language (HTML), defining a method to transmit HTML documents between computers using HTTP.

Up to this point, HTML was mostly a research-centered idea. In 1992, the National Center for Supercomputer Applications (NCSA) at the University of Illinois-Urbana Champaign (UIUC) developed the first web browser, Mosaic. Mosaic was released on Sun Microsystems workstations in 1993. This was followed by Netscape in 1994, built by Marc Andreessen and Jim Clark. Next came Internet Explorer in 1995, Google Chrome in 1998, and the Mozilla foundation (the precursor to Firefox) in 2003.

It is beyond the scope of our module to discuss all aspects of HTML, and for Dash, it is not required, since all we're concerned about is how different HTML tags affect the layout of information. To this end, we list below some of the common HTML tags important to Dash and their corresponding purpose. A complete list of tags is available online.

•  div

A section of a document

•  H1, H2, H3, H4, H5, H6

Headers in decreasing priority

•  p

A paragraph

•  span

A block of text, usually with properties different from the surrounding text

•  br

A line break

•  ol

An ordered list

•  ul

An unordered list

•  li

A list item in an ordered or unordered list

•  input

An input component, where the type of input is defined by the input's type attribute: input box, checkboxes, radiobuttons, and so on.

•  table

A table

•  tbody

Definition of where a table's body starts and stops

•  tr

A single table row

•  td

A single table column value (embedded within a table row defined with <tr>)

•  thead

Definition of where a table's header starts and stops

•  th

A single table column value in the table's header (embedded within a table row defined with <tr>)

•  tfoot

Definition of where a table's footer starts and stops

•  tf

A single table column value in the table's footer (embedded within a table row defined with <tr>)

Here is a very simple web page demonstrating some of these tags in use.

plotly

plotly is a Python library designed to provide a wide range of standard charts. plotly is built on the Plotly JavaScript library, and is meant to support creation of interactive web-based visualizations. As an example, here is a plotly program that can be run in a Jupyter notebook.

This produces the following simple bar chart.

Charts

Although plotly can be used directly to create charts, it is generally recommended to start with Plotly Express, which sits on top of plotly and allows entire figures to be created in a more efficient fashion. Plotly Express functions use plotly graph objects internally and return a plotly.graph_object.figure instance. plotly's documentation shows examples of how to build a graph in Plotly Express, followed by code to build the equivalent graph in plotly. Since Plotly Express returns a basic plotly figure instance, modifications of the Plotly Express charts can be done in way that is identical to how plotly's charts are changed. We will use Plotly Express code whenever it is possible.

To provide you with examples of how to build the basic charts and graphs you will want to use in your dashboards, we provide a collection of code and resulting graphs that Plotly Express supports.

Bar Graph

Plotly Express supports bar charts, stacked bar charts, and side-by-side bar charts.

Line Graph

Plotly Express supports line graphs with one or more lines.

Notice the command fig.update_traces( 'markers+lines' ) that adds markers to the traces at each sample point, in addition to the default connected lines. This is an example of a plotly command used to augment a figure returned from Plotly Express. You might wonder what a "trace" is. From the plotly documentation, "a trace is just the name we give a collection of data and the specifications of which we want that data to be plotted." In other words, a trace is a visualization, or a component of a visualization. If you're curious, the same two-trace line chart with markers would be created in plotly as follows.

Pie Chart

Plotly Express supports standard line charts.

The pie chart can be improved using fig.update_traces, for example, to order slices largest-to-smallest clockwise from the top of the chart, and to change the colours to ones more appropriate for a discrete six-value sequence.

Scatterplot

Plotly Express supports scatterplots, including linear and non-linear locally weighted scatterplot smoothing (LOWESS) trendlines.

More sophisticated non-linear trendlines (e.g., a cubic polynomial fit) can be constructed and added using numpy and plotly.

Histogram

Plotly Express supports histograms for both continuous and categorical (discrete) data.

Boxplot

Plotly Express supports boxplots, including outlier visualization and different methods of quartile computation.

Maps

plotly supports maps using Mapbox, a map and location service for developers. Some plotly maps may require a Mapbox account and public Mapbox access token. Others do not. The documentation identifies when a public token is needed.

To start, we show an example of a choropleth map visualizing unemployment rate by continental US county. Choropleth maps require two arguments.

1. A GeoJSON-formatted geometry variable, where each geographic feature has a specific ID field: the field identifier.
2. A list of values to visualize, where each value has a specific field identifier identical to the type used in the GeoJSON data.

The GeoJSON data is passed as a geojson argument, and the data to visualize within the geography is passed as the color argument of a px.choropleth_mapbox object. The geography and value to visualize are mapped to one another using the field identifier, which must exist in both the GeoJSON and data structures. In our example, a county's Federal Information Processing Standards (FIPS) code is used as the field identifier, and exists in both the GeoJSON object and the unemployment data frame.

Mapbox maps do not support changing the map projection. To do this, outline-based Geo maps must be used instead. A Geo map's projection type can be changed with fig.update_geos( projection_type='mercator' ). Numerous projects types are supported.

The example code below creates a population proportional dot map for the United States using a Geo map created with the go.Scattergeo plotly command.

Dash

Finally, we can start our discussion of Dash dashboards. As we initially noted, Dash dashboards are made up of two parts: a layout that defines how elements are position on a web page, and interactivity that defines how users can manipulate elements of the web page to change what it displays.

As a simple example, below is a Dash dashboard that displays a side-by-side bar graph of the number of fruit associated with the cities SF and Montreal. Dash dashboards are normally run as stand-alone python code, and not within a Jupyter notebook.

1. Enter the Python code for the dashboard in an external file.
2. Use python to execute the file.
3. By default, Dash places the dashboard at http://127.0.0.1:8050/, which is shorthand for the computer being used to access the address (i.e., your computer, or localhost in technical terms) over port 8050. By visiting that URL, you can view and interact with the dashboard defined in your Python file.

Running this code, then visiting URL http://127.0.0.1:8050 produces the following (non-interactive) visualization in a web browser.

To end the dashboard, terminate the Python program running dash-app.py. A very simple explanation of the components of this program is as follows.

• app = dash.Dash(…  creates the initial Dash application using the community-recommended styles loaded from plotly,
• df = pd.DataFrame…  creates a pandas dataframe with the data we will visualize,
• fig = px.bar…  creates a plotly bar graph,
• app.layout = html.Div(…  defines the dashboard's layout as an initial HTML div,
• children=[…  places an H1 section title, a div, and a graph element within the parent div,
• html.H1 and html.Div define the title and subtitle of the dashboard,
• dcc.Graph…  displays the plotly bar graph, and assigns it an ID of ex_graph, and
• app.run_server(debug=True) interprets the code to create the dashboard at URL http://127.0.0.1:8050/

One clarifying note about setting debug=True in the run_server function: when debug is False, changes to the Python code will not update the dashboard. When debug is True, changes to the Python code will automatically be detected and used to update the dashboard in real-time. If you are using debug=True you can run your code (based on my testing) from an Anaconda Prompt or the Spyder IDE. We DO NOT recommend running the code in a Jupyter notebook. Although it will run correctly the first time, there is no easy way to terminate the dashboard if you want to re-run it.

Setting debug=True will also add a blue button containing < > at the bottom-right of the screen. Clicking on this button allows you to check the status of the Dash server, view any errors that may have occurred, and visualize the callback graph for the dashboard.

HTML objects have default styles that can be changed in various ways. Dash supports this ability by providing access to a tag's style properties through update_layout() for figures and style for Dash layouts. The following code is a modification of the original example.

Interactive Widgets

As with most applications, Dash provides a set of standard widgets to allow users to interact with an application. The code below shows a sample of Dash's interactive objects, including dropdown and multi-dropdown menus, radiobuttons, checkboxes, input fields, and sliders.

Callbacks

Once interactive widgets are placed on a dashboard, we need a way to recognize when they are changed. This is done using callbacks, a standard method to monitor user interaction in an application. Whenever a widget is manipulated to change its value, a callback is made to the Python program controlling the dashboard. Code in the program captures the callback, so it can examine the new widget value and update the dashboard's content appropriately.

As a very simple example of callbacks, the following Python program creates a Dash dashboard with an input text field, and an output label that displays the current value of the text field.

We have already discussed the code used to create the dashboard and its corresponding widgets. The @app.callback function is where a callback to detect changes to the input textbox and modify the output div is contained.

• @app.callback defines the inputs and outputs of the dashboard.
• @app.callback is described as a decorator in Dash. It tells Dash to call this function whenever the value of an input changes, presumably in order to update the children of an output.
• Input defines the input component and the input's property that contains a new input value. In our example, the input component is the dcc.Input textbox with the ID inp. The new input value is the value property of the textbox.
• Output defines the output recipient and the recipient's property. In our example, the recipient is the component in our layout with the ID out (a div). The recipient's children value will be updated with the new input value.
• Immediately following @app.callback is a function that takes the new input value as an argument, and returns a new output value to store in the recipient's property. Note that the function must be defined immediately after the @app.callback function, with no blank lines or other intervening code.
• The callback function can be named as desired, although it should usually reflect the purpose of the callback. In our code, update_output_div takes input_value, which is the new value of the textbox, and returns a string containing this new value.

Here is another, more realistic, example that uses a slider and a scatterplot to visualize the relationship between GDP per capita and life expectancy, subdivided by continent.

Of course, most dashboards will have multiple inputs and outputs. How is this handled in Dash? For inputs, notice that Input is embedded within a list. You can define multiple Input statements in this list. For each Input statement you add, another input argument is included in your callback function.

In this example, there are five input widgets: two dropdown menus, two radiobutton groups, and a slider. All five are included in the Input list: xaxis-column, yaxis-column, xaxis-type, yaxis-type, and year-slider, respectively. In the update_graph function the values for those five widgets are passed as xaxis_col_nm, yaxis_col_nm, xaxis_type, yaxis_type, and year. Other than this, the function operates identically, returning an updated scatterplot based on the five selected inputs.

Multiple outputs work in a similar way. First, you specify each output as part of the list of Output statements. Then, specify each output element in order in the list returned by the callback function.

This dashboard shows the GDP per capita for countries in a user-chosen continent. Continent selection is performed with a standard dropdown menu. GDP per capita is shown in two visualizations. The first uses a simple bar chart by country. The second uses a treemap, where the size of the rectangle assigned to a country represents its population, and the rectangle's colour represents the GDP per capita from a red–blue double-ended colour scale.

Publishing

Unfortunately, publishing a Dash dashboard is not as straight forward as it is with other environments like R+Shiny. plotly does not maintain a public cloud to upload dashboards. Various options are suggested by different Dash users.

Dash itself suggests the following documentation for deploying Dash applications. Your milage may vary on this, but it is probably the best starting point for attempt to build a Dash appliation that is accessible from the web.