Sankey Diagram

[Configuration manual]

Introduction

Sankey diagrams can be used to display the flow, energy, materials, and other resources or processes in complex systems. They use a directed acyclic graph (DAG) structure, in which each node represents a particular state or event in the system, while the edges represent flows between two nodes (typically quantities or qualities in the system).

In a Sankey diagram, the size and color of the nodes are usually proportional to their importance and values. The width of the edges is also proportional to their associated values and typically has directional arrows. Nodes and edges can provide additional information through labels, legends, tooltips, etc.

Sankey diagrams are used in many fields, such as traffic analysis, energy management, material tracing, etc. They help people understand the complexity of systems, gather data, discover trends, etc.

Chart Components

Sankey diagrams mainly consist of node and edge components, tooltips, and other components.

Node and link components are essential elements of the Sankey diagram, and the relevant drawing configurations are indispensable:

• sankeyChart.type: Chart type. The Sankey diagram type is 'sankey'.
• sankeyChart.data: Data source for chart drawing.
• sankeyChart.categoryField: Classification field, mapping different node components.
• sankeyChart.valueField: Value field, mapping the length of different node components.
• sankeyChart.nodeAlign: Node alignment type configuration.
• sankeyChart.nodeGap: Configuration for the gap size between two nodes at the same level.
• sankeyChart.nodeWidth: The width of each node.
• sankeyChart.minNodeHeight: The minimum size of the node when the data is non-zero or not empty. This configuration can be used to avoid nodes that are too small to be seen when the data is too small, and it's recommended to be less than 5px.

Tooltip and other components that assist in chart display are optional configurations with default effects and functions:

• sankeyChart.tooltip: Tooltip information. Default interaction is displayed. For detailed configuration, see the VChart Tooltip Component Configuration.
• For more component configurations, see VChart sankeyChart Configuration.

Quick Start

Key Configurations

• The categoryField property declares the category field, representing node names.
• The valueField property declares the value field, representing the weight of the relationship between nodes.
• sourceField and targetField properties do not need to be specified and are generated based on the hierarchical structure.
• The nodeKey property declares the resolution of the key value for nodes.

Sankey Diagram Features

Data

Since Sankey diagrams use data structures to represent the relationships between nodes and edges, we defined two ways to declare the data structure of Sankey diagrams in VChart:

• Flat data structure for nodes and edges:

[
  {
    nodes: [{ nodeName: 'A' }, { nodeName: 'B' }, { nodeName: 'C' }],
    links: [
      { source: 0, target: 1, value: 1 },
      { source: 0, target: 2, value: 1 }
    ]
  }
];

• Nested data structure for nodes and edges:

[
  {
    name: 'A',
    children: [
      { name: 'A-a', value: 1 },
      { name: 'A-b', value: 2 }
    ]
  },
  {
    name: 'B',
    children: [
      { name: 'B-a', value: 3 },
      { name: 'B-b', value: 4 }
    ]
  }
];

Flat Data

Nested Data

Chart Layout

The layout of the Sankey diagram is mainly reflected in the positional relationship between nodes. The following configurations can help you freely adjust the layout of the Sankey diagram:

• nodeAlign: Declare the alignment type for nodes. This property can be configured as 'left' | 'right' | 'center' | 'justify' | 'start' | 'end'.
• nodeGap: Declare the gap size between two nodes at the same level.
• nodeWidth: Declare the width of each node. Supports three types of values:

• Percentage string, e.g., { nodeWidth: '12%' }
• Simple number in pixels, e.g., { nodeWidth: 20 }
• Function, specify nodeWidth through custom calculation.

• The minNodeHeight property declares the minimum size of the node when the data is non-zero or not empty. This configuration can be used to avoid nodes that are too small to be seen when the data is too small, and it's recommended to be less than 5px.

Sankey Diagram Labels

In Sankey diagrams, the position of the labels can be configured with sankeyChart.label.position: 'outside' | 'inside-start' | 'inside-middle' | 'inside-end' | 'left' | 'right'.

Sankey Diagram Interaction

In general, the parent-child relationship and hierarchy in Sankey diagrams is represented by the connection of links. However, when the data set is complex and the hierarchy is deep, this method may not be clear enough. Therefore, in such cases, it is necessary to display the relationship between parent and child through clicking to better understand the overall data flow and path information.

In VChart, we can configure interactions with sankeyChart.emphasis.

• sankeyChart.emphasis.trigger: Declare the interaction trigger type. It can be configured as 'click' | 'hover', click or hover to trigger.
• sankeyChart.emphasis.effect: Declare the interaction linkage effect. Sankey diagrams offer three different interaction linkage effects on nodes:

• self: Only highlight the current node;
• adjacency: Highlight the upstream and downstream nodes and associated edges of the current node and fade other graphic elements;
• related: Highlight the nodes and edges on the entire path related to the current node and fade other graphic elements.