Sankey Diagrams

What are Sankey Diagrams?

Mermaid's Sankey diagrams provide a visual representation of flow and relationships between nodes, showing the proportional values in a process. Commonly used to display resource or energy flow, they highlight the relative sizes of inputs, outputs, and connections, making it easy to analyze and optimize processes.

Creating Your First Sankey Diagram

1. From the Code IDE, click Apps and Agents from the left-hand panel.

2. Select Mermaid. Paradime will automatically start a new Mermaid project.

3. In the terminal that appears, use the arrow keys to select "Sankey Diagram"

4. A new sankey.mmd file will be created in your editor with this starter template:

---
config:
  sankey:
    showValues: false
---
sankey-beta

Agricultural 'waste',Bio-conversion,124.7
Bio-conversion,Liquid,0.6
Bio-conversion,Solid,280.3
Coal reserves,Coal,75.6
Electricity grid,Heating and cooling - homes,113.7
Electricity grid,Industry,342.2
Electricity grid,Road transport,37.8
Gas reserves,Ngas,123.0
H2 conversion,H2,20.9
Liquid,Road transport,135.8
Nuclear,Thermal generation,840.0
Oil reserves,Oil,612.0
Pumped heat,Heating and cooling - homes,193.0
Solar,Solar PV,59.9
Thermal generation,Electricity grid,525.5
Wind,Electricity grid,289.4

1. Click the eye icon (👁️) in the top right corner of your Mermaid file to preview the diagram.

2. Edit and update your .mmd file as needed—the preview will update automatically.

Diagram Syntax Guide

Basic Syntax

• Define the diagram using sankey-beta.

• Each row specifies a source, target, and value, separated by commas.

sankey-beta

Source,Target,Value
Electricity grid,Heating and cooling - homes,113.7
Electricity grid,Industry,342.2

Formatting Rules

1. Empty Lines: You can leave blank lines for better readability.

   sankey-beta
   
   Source,Target,Value
   Bio-conversion,Losses,26.9
   
   Bio-conversion,Solid,280.3

2. Commas: Enclose text with commas in double quotes.

   sankey-beta
   Pumped heat,"Heating and cooling, homes",193.0

3. Double Quotes: Escape double quotes by using two double quotes.

   sankey-beta
   Pumped heat,"Heating and cooling, ""homes""",193.0

Configuration Options

You can customize the diagram’s appearance using configuration settings.

Example Configuration

<script>
  const config = {
    startOnLoad: true,
    securityLevel: 'loose',
    sankey: {
      width: 800,
      height: 400,
      linkColor: 'source',
      nodeAlignment: 'left',
    },
  };
  mermaid.initialize(config);
</script>

Available Settings

• Link Colors: Adjust the link colors.

  • source: Color matches source node.

  • target: Color matches target node.

  • gradient: Smooth transition between source and target colors.

  • #hexcode: Specify a specific hex color.

• Node Alignment: Change alignment using justify, center, left, or right.

Data Team Examples

Resource Flow

sankey-beta

Coal reserves,Coal,75.6
Coal,Thermal generation,400.1
Thermal generation,Electricity grid,525.5
Electricity grid,Industry,342.2

Energy Distribution

---
config:
  sankey:
    showValues: true
---
sankey-beta

Oil reserves,Oil,612.0
Oil,Liquid,611.9
Liquid,Road transport,135.8
Liquid,International aviation,206.3

Best Practices

1. Clearly define nodes and values.

2. Use intuitive labels for source and target nodes.

3. Adjust link colors and node alignments for clarity.

4. Keep the number of nodes manageable for readability.

5. Regularly update diagrams to reflect current data flows.

---

Additional Resources

For more syntax options and advanced features, visit the official Mermaid documentation.