Dashboarding with Plotly

The primary method for running the application is via the docker-compose.yml file. Ensure that the following section is not commented (i.e. there are no # before any of the lines highlighted below):

and run in the terminal:

followed by:

Also recall from the Docker Guidance page that you can run it in the background with:

Note: once you've built the dashboard once (with docker compose build) you don't need to do this again. This is because the code workspace (on your PC) is mounted as a volume to the working directory of your docker container in the docker-compose.yml file. Re-running docker compose up (or making use of the hot-reload function of the Dash Dev Tools).

The dashboard should now be accessible in the browser on localhost:8050 

The Python files for creating the dashboard are organised in the dashboard directory, as follows: 

The example.py provides a core structure with some reasonably advanced Dash functionality, which you can use as a starting point to build your own custom dashboard. It will likely be worth experimenting with commenting out different components in the layout or callback functions and observing the changes, to gain an understanding of how it all fits together. Once you feel comfortable with the example features and have started customising your own dashboards, refer to the Plotly documentation to see what it is capable of (spoiler: a lot!). 

Setting Debug=True in run.py will give you access to the Dash Dev Tools:

• Callback Graph - Dash displays a visual representation of your callbacks: which order they are fired in, how long they take, and what data is passed back and forth between the Dash app in the web browser and your Python code.

• Code Reloading - Dash restarts your app when you change code in your project.

• Hot Reloading - Dash automatically refreshes the web browser and your CSS files when you make a code change so that you don't need to manually refresh your browser.

• In-App Error Reporting - Dash reports error messages in the browser instead of your terminal so that you can stay focussed on your app and your code.

• Component Validation - Dash will display error messages if you pass malformed data to your components.

• Better Error Messages - Dash prunes certain stack traces from Flask & Dash internals and logs from Flask, Dash's underlying web server.

• Serving Dev Bundles & Source Maps - For component authors, you can serve a different JavaScript bundle during development.

Setting Debug=False will remove these features, but provide a cleaner/more stable experience for displaying the dashboard.

The Home page is defined in the script home.py; this is the first page a user will see when opening localhost:8050. The default template supports a dcc.Markdown component which you can use to provide an overview of the project or the contents of the dashboard. There is also a html.Img component, which reads an image from the directory at assets/home_page and displays it. To display your own project specific image, remove the default image of Factory 2050 and replace it with your chosen image. The default template code will only read one image from the folder, and it should be able to read any of the standard image formats.

You can of course add more images, text components, buttons/links, graphs etc. by modifying the layout object in the script.

The example.py script controls what you see on the Example page of the dashboard app. Start by experimenting with this page to understand the components and what happens when you make changes in the code (you can always Discard Changes in your git source control if you break it and can't get it back to workging again). This should give you a good starting point for building your own custom dashboard app, whilst maintaining a degree of standardisation across other AMRC projects.

Comprehensive documentation on Dash callbacks can be found here and here.

The Script is organised into four sections:

Callback functions allow you to change properties in the components, by taking an Input() from one component and using that to trigger or influence and Output() in another. The example.py script contains two example callbacks: 

Callback 1

This function updates the figure titled 'Line 2 - Random Signal' with a new random signal once per second. Additionally, each click of the big green button at the top increases the number of points that are generated in the signal.

Takes 2 inputs:

Runs the function and returns one output:

Callback 2

This function updates the two scatter plots once per second, both from the same function call with a single input. 'Scatter 1 - Random Signal' is randomly generated, and 'Scatter 2 - Increasing Signal' shows a signal which increases linearly for as long as the page runs. Colours on both charts are controlled by the value of the 'Increasing Signal' data.

Takes 1 input:

Runs the function and returns two outputs: 

Mounting ./code/dashboard to /dashboard allows us to edit the code without needing to re-build the docker container after every change. /dashboard is the working directory in the container.

Mounting ./data to /data allows us to access data stored in the data directory from within the container. In the example.py script, an example_data.csv file is read and visualised in the Line 1 - Static Signal graph.

The mounted directories are organised in the file system as follows:

In order to access the data from within the dashboard script, prefix the file path with ../data/, e.g.: 

Adding new pages to the dashboard is quite straightforward and (mostly) automated.

The core mechanism involves adding a new script to the pages directory, with the same syntax as provided in example.py. A second, empty layout is provided in example_2.py as an example of what you might start building from after copying.

Ensure you aren't duplicating any component names (see note below) and give your new script a sensible name. The name of the script will be the URL tagline that the page will be accessed at.

Note - Dash reads the component names from all pages in the app, not just the page the user is currently on. As such each component name must be unique, so if you copy a page with already established components to build a new one ensure that you rename (or remove) the components on the new page.

The code in index.py should now read the pages directory for all valid page layouts and generate them automatically (you'll have to save the script and restart the container of course, unless using hot-reloading with the debug mode). You can now build the new dashboard page as you see fit.

The one manual step required at this stage is to add the page to navbar.py. In the following section of the generate_navbar() function, the dbc.NavLink button needs to be appended to the list children.

   ### add new pages manually here with this syntax

    children.append(dbc.NavItem(dbc.NavLink("Example", href="/example")))

    # children.append(dbc.NavItem(dbc.NavLink("Example 2", href="/example_2"))) # uncomment this line to add the example_2 page to the navbar

In this example, you can un-comment the line children.append(dbc.NavItem(dbc.NavLink("Example 2", href="/example_2"))) to make the page example_2 accessible, by clicking on the text Example 2 in the navbar. To add a new custom script, replicate this process on a new line with the name of your script and the text you want to appear on the navbar.