Sankey Chart

A Sankey chart is a type of flow diagram in which the width of the arrows is proportional to the flow rate. It is ideal for visualizing energy balances, material flows, or any system with defined quantities moving between nodes.

Example

The following example demonstrates a Sankey chart visualizing energy flows. It uses data loaded from a CSV file.

Usage

To use the Sankey chart, you need to provide a container element and configuration options, including the source of the data. Data can be sourced from:

• a CSV file, via URL or as a string;
• JSON in the VisuallyJsDefaultJSON format via URL;
• A JS object in the VisuallyJsDefaultJSON format;
• a DataSource - some existing instance of the VisuallyJs model.

<script>
import {SankeyComponent} from "@visuallyjs/browser-ui-svelte"

const data = ...

const options = {
  url: "/data/sankey-energy-data.csv",
  linkColorStrategy: "source-target",
  height: 600
}
   
</script>
<template>
        <SankeyComponent className="my-container" :data="data" :options="options"/>        
</template>

CSV Format

The Sankey chart expects data in a CSV format to have source, target, and value columns. For example:

source,target,value
Agricultural 'waste',Bio-conversion,124.729
Bio-conversion,Liquid,0.597
Bio-conversion,Losses,26.862
Bio-conversion,Solid,280.322
Bio-conversion,Gas,81.144
...

The header line should be present.

Loading data

Loading from a URL

The Sankey chart will use the extension of a URL to determine what type it expects the data to be in - .json or .csv.

Loading CSV data directly

Use the csvData option if have CSV as a string that you wish to load:

const myCsvData =...

<script>
import {SankeyComponent} from "@visuallyjs/browser-ui-svelte"

const data = ...

const options = {
  csvData: myCsvData,
  linkColorStrategy: "source-target",
  height: 600
}
   
</script>
<template>
        <SankeyComponent className="my-container" :data="data" :options="options"/>        
</template>

Loading JS data directly

const myJson:VisuallyJsDefaultJSON =...

<script>
import {SankeyComponent} from "@visuallyjs/browser-ui-svelte"

const data = ...

const options = {
  jsonData: myJson,
  linkColorStrategy: "source-target",
  height: 600
}
   
</script>
<template>
        <SankeyComponent className="my-container" :data="data" :options="options"/>        
</template>

Using a DataSource

Sankey diagrams can also be given a dataSource as input, which is of type VisuallyJsModel. This is particularly useful for dashboards where you want to show a flow-based overview of an underlying interactive diagram model.

In Svelte, you can inject a datasource into a Sankey by wrapping everything in a SurfaceProvider:

<script>

    const sankeyOptions = {
		linkColorStrategy: "source"
	}
    
</script>
<SurfaceProvider>
	<div style="display:flex">
		<SurfaceComponent url="/data/my-diagram.json" />
		<SankeyChartComponent :options"sankeyOptions" />
		<InspectorComponent />
	</div>
</SurfaceProvider>

Pivoting

You can pivot a Sankey chart, providing the name of a property that is present on each edge in your data. Pivoting a Sankey diagram means that instead of just showing the direct flows between nodes, the diagram groups the edges by the value of the specified property.

A classic example of this is in the Supply Chain demonstration. In that demo, the Sankey chart can be pivoted on transitMode (e.g., Air, Sea, Road) or carrier (e.g., FedEx, DHL). When pivoted on transitMode, the diagram shows the flow of goods broken down by how they were transported, even if they share the same source and target.

Here we see the default Sankey for the supply chain, in which there's a node for each entity, and edges connecting them showing the flow between them:

Edges in this dataset have this data:

{
  "value": 300,
  "label": "Global Distribution",
  "transitMode": "Air",
  "carrier": "FedEx"
}

We can instruct the Sankey to pivot on an edge value to get a different view of the data. For instance, let's pivot on transitMode:

<script>
import {SankeyComponent} from "@visuallyjs/browser-ui-svelte"

const data = ...

const options = {
  jsonData: myJson,
  linkColorStrategy: "source-target",
  pivot: "transitMode"
}
   
</script>
<template>
        <SankeyComponent className="my-container" :data="data" :options="options"/>        
</template>

Dynamic pivot

TBD

Pivot: No pivotTransit ModeCarrier

Link color

The linkColorStrategy option determines how the links (edges) between nodes are colored. The following strategies are available:

• static: Uses a single color for all links. The color can be specified using the linkColor option, which defaults to #444444.
• source: Links are colored using the color of their source node.
• target: Links are colored using the color of their target node.
• source-target: Links are colored using a gradient that transitions from the source node's color to the target node's color.

CSS Classes

Class	Description
vjs-sankey	Assigned to the sankey chart container
vjs-sankey-edge	Assigned to edges in Sankey chart
vjs-sankey-label	Assigned to labels in a sankey chart
vjs-sankey-node	Assigned to nodes in a sankey chart
vjs-sankey-selected	Assigned to edges/nodes in Sankey chart when the edge/node forms part of the selected path.
vjs-sankey-unselected	Assigned to edges/nodes in Sankey chart when something is selected but this edge/node is not in the selected path