Sankey Builder

Metabolism of Cities is excited to present the Circular Sankey Builder, a powerful tool designed to help you create captivating Sankey diagrams that illustrates material flows and tells the story of circularity in your urban environment.

Why we built this 🛠️

Sankey diagrams provide a visual representation of material flows, showcasing the circularity status quo of your city which makes it much easier to understand. To simplify the process, we have developed a Google template and Google Colab code file that you can run with your own data.

Previously, there was no open-source code available to generate Sankey diagrams specifically for circularity storytelling, that's why we decided to create it ourselves!

The ideation and research behind the Circular Sankey Builder came from the Metabolism of Cities team, with a special focus on experimenting with different kinds of visualisations. With the assistance of Guus Hoekman and Gerardo Ezequiel Martín Carreño, our technical minds, we were able to bring this innovative tool to life based on the code of Plotly.

How you can use it

You can easily request the builder code and template by filling out this Google Form. We look forward to receiving your request and assisting you in the best possible way. Just click on the link below to access the form:

Metabolism of Cities’ Sankey Builder - Request for Google Colab and Spreadsheet Template

How it works: generating a Sankey diagram

Generating your own circular Sankey diagram is fairly easy with our user-friendly process. Upon requesting the templates, you can use those of the Google sheet and the Google Colab file. To create your own Sankey diagram, please copy these files, and replace the values with your own calculations / values.

There are several ways to do this, our approach is to have a live sheet connected to the UCA analysis sheets (C. UCA - Data analysis) and can be achieved by following the steps in the two following parts:

Part 1: Prepare your google sheet

  1. Copy “S. Sankey - Template” to the relevant folder you are working on.
  2. This template has two tabs; Sheet1 and All_filtered_importrange. At the All_filtered_importrange tab, select cell A2 and change the formula to your own “C. UCA - Data analysis” sheet link with relevant cells.
  3. Now you will have live results from your analysis sheet imported to “S. Sankey - Template” sheet and the All_filtered_importrange tab
  4. From this tab, you can filter which material or flow you need, and copy the values to Sheet1.

Note: Colab file will get the results from the Sheet1 tab and does not work for multiple tabs. In our code, sheet1 is specified as you can see here.

Part 2: Prepare your Colab file

  1. Open the Colab file and copy it. (Our code is an open source code and copyrighted with the MIT Licence that you can use and adjust for free by crediting Metabolism of Cities.)
  2. Replace the link in the code section with your own google sheet link that contains your material flows data. (See template on how it should look like)
  3. Navigate to the Colab file menu and under "runtime" click on "run all.
  4. Google will prompt you for access; click "run anyway" to proceed.
  5. You will then see a message asking for permission to access your Google credentials. It will say "Allow this notebook to access your Google credentials?". You need to click "allow" and choose a google account since "Colaboratory Runtimes wants to access your Google Account" and you press allow again. Click "allow" and select your Google account.
  6. The Colab file will execute / run all components and plot and display the Sankey diagram at the bottom of the page.

Notable features of the Circular Sankey Builder

  • Identify material flow start and end points: The Sankey diagram helps you to visualise various material flows, between nodes such as imports and processed materials, allowing for a comprehensive understanding of resource utilisation.
  • Play with colours: Customise your Sankey diagram by applying different colours, enabling you to create engaging and visually appealing representations.
  • Easy updates via Google Colab: The Circular Sankey Builder is linked to a Google Sheet, allowing you to conveniently update the data and see the changes reflected after pressing a single button.
  • Embed code: Export the Sankey diagram as HTML code and seamlessly embed it on your website, in your reports or presentations, enhancing your communication of circularity insights.
  • Interactive node manipulation: Explore the diagram by dragging and manipulating nodes, giving you a dynamic experience while analysing material flows.

With this intuitive tool at your fingertips, you can effectively disclose and communicate the circularity status within your city and drive sustainable change.

Customisation

The Sankey diagram can be customised. It is possible to position the nodes differently, horizontally and vertically, and the colours of the nodes and the flows can also be changed.

Moreover, the flow and node names can of course also be changed entirely so that a Sankey diagram can also be built for the Sector-wide Circularity Assessment (SCA) or another project.

How to position nodes

The fig.update_traces function is a function that allows you to adjust the positions of the nodes.

To change the position of a node, you will need to specify its x and y coordinates on the graph. These coordinates are expressed as a number between 0 and 1, where 0 represents the left or top of the graph, and 1 represents the right or bottom. For example, a node with an x coordinate of 0.5 will be located in the middle of the graph horizontally.

The node parameter is a dictionary that contains information about each node in the visualisation, including its label and its x and y coordinates. The order of the elements in the node dictionary corresponds to the order in which the nodes are displayed in the visualisation.

The list of elements that correspond to each node are also specified in the node parameter. In the example code you provided, these elements include 'Imports', 'Domestic Extraction', 'Processed materials', 'Energetic use', 'Material use', 'In-use stocks', 'EoL Waste', 'Exports', 'DPO emissions', and 'DPO waste'. These elements are included as a comment for reference.

So, to move a node to a specific position, you need to change its x and y coordinates in the node dictionary. For example, if you want to move the 'Imports' node to the top left of the graph, you would set the first value in the x list to 0 and the first value in the y list to 0.

How to change colours

To modify the colours of the nodes and flows in the visualisation, you can make changes to the E and F columns of the Sankey Google provided. These columns are labelled "flow_color" and "node_color" and contain values that determine the colours of the edges and nodes, respectively.

The colours should be specified in the RGBA format, which stands for "red, green, blue, alpha". The RGBA format allows you to specify the level of each primary colour (red, green, and blue) as well as the level of opacity or transparency. The values for each colour range from 0 to 255, while the opacity value ranges from 0 (completely transparent) to 1 (completely opaque).

For example, to create a red colour with full opacity, you would use the following RGBA value: rgba(255, 0, 0, 1). This specifies that the colour should be composed of maximum red (255), no green (0), no blue (0), and full opacity (1).

How to export the Sankey diagram to embed it (HTML)

To export the HTML file of your Sankey diagram follow the step-by-step instructional screenshots for exporting as HTML

  1. Run the script (see ”How to generate the Sankey”) by clicking on Runtime and Run all.

  1. Navigate to the files in the folder on the left pane. You will see "Sankey - Template.html" after running the code which is saved in the current working directory of your Google Colab notebook.

  1. Hover over the file and click on the three dots button in the top right corner. Select "Download" from the drop-down menu and save your Sankey diagram HTML file to your local machine.

  1. Open the file, with your browser, for example, to ensure that you downloaded it successfully. You can then use the code to embed it elsewhere.

Other resources

There are other ways to build a Sankey diagram that does not require code, but that also is not circular. How this can be done, is explained in the following video: