Back to Details

sankey-diagram-creator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sankey Diagram Creator

Sankey图创建器

Create interactive Sankey diagrams to visualize flows, transfers, and relationships between categories. Perfect for budget flows, energy transfers, user journeys, and data pipelines.
创建交互式Sankey图，用于可视化各类别之间的流量、转移和关系，非常适合预算流向、能源传输、用户旅程和数据管道等场景。

Quick Start

快速开始

python
from scripts.sankey_creator import SankeyCreator
python
from scripts.sankey_creator import SankeyCreator

From dictionary

From dictionary

sankey = SankeyCreator() sankey.from_dict({ 'source': ['A', 'A', 'B', 'B'], 'target': ['C', 'D', 'C', 'D'], 'value': [10, 20, 15, 25] }) sankey.generate().save_html("flow.html")
sankey = SankeyCreator() sankey.from_dict({ 'source': ['A', 'A', 'B', 'B'], 'target': ['C', 'D', 'C', 'D'], 'value': [10, 20, 15, 25] }) sankey.generate().save_html("flow.html")

From CSV

From CSV

sankey = SankeyCreator() sankey.from_csv("flows.csv", source="from", target="to", value="amount") sankey.title("Budget Flow").generate().save_html("budget.html")
undefined
sankey = SankeyCreator() sankey.from_csv("flows.csv", source="from", target="to", value="amount") sankey.title("Budget Flow").generate().save_html("budget.html")
undefined

Features

功能特性

  • Multiple Input Sources: Dict, DataFrame, or CSV files
  • Interactive Output: Hover tooltips with flow details
  • Node Customization: Colors, labels, positions
  • Link Styling: Colors, opacity, labels
  • Export Formats: HTML (interactive), PNG, SVG
  • Auto-Coloring: Automatic color assignment or custom schemes
  • 多输入源支持：字典、DataFrame或CSV文件
  • 交互式输出：带流量详情的悬浮提示框
  • 节点自定义：颜色、标签、位置
  • 链接样式：颜色、透明度、标签
  • 导出格式：HTML（交互式）、PNG、SVG
  • 自动配色：自动分配颜色或使用自定义配色方案

API Reference

API参考

Initialization

初始化

python
sankey = SankeyCreator()
python
sankey = SankeyCreator()

Data Input Methods

数据输入方法

python
undefined
python
undefined

From dictionary

From dictionary

sankey.from_dict({ 'source': ['A', 'A', 'B'], 'target': ['X', 'Y', 'X'], 'value': [10, 20, 15] })
sankey.from_dict({ 'source': ['A', 'A', 'B'], 'target': ['X', 'Y', 'X'], 'value': [10, 20, 15] })

From CSV file

From CSV file

sankey.from_csv( filepath="data.csv", source="source_col", target="target_col", value="value_col", label=None # Optional: column for link labels )
sankey.from_csv( filepath="data.csv", source="source_col", target="target_col", value="value_col", label=None # Optional: column for link labels )

From pandas DataFrame

From pandas DataFrame

import pandas as pd df = pd.DataFrame({ 'from': ['A', 'B'], 'to': ['C', 'C'], 'amount': [100, 200] }) sankey.from_dataframe(df, source="from", target="to", value="amount")
import pandas as pd df = pd.DataFrame({ 'from': ['A', 'B'], 'to': ['C', 'C'], 'amount': [100, 200] }) sankey.from_dataframe(df, source="from", target="to", value="amount")

Add individual flows

Add individual flows

sankey.add_flow("Source", "Target", 50) sankey.add_flow("Source", "Other", 30, label="30 units")
undefined
sankey.add_flow("Source", "Target", 50) sankey.add_flow("Source", "Other", 30, label="30 units")
undefined

Styling Methods

样式设置方法

All methods return 
self
for chaining.
python
undefined
所有方法均返回
self
以支持链式调用。
python
undefined

Node colors

Node colors

sankey.node_colors({ 'Income': '#2ecc71', 'Expenses': '#e74c3c', 'Savings': '#3498db' })
sankey.node_colors({ 'Income': '#2ecc71', 'Expenses': '#e74c3c', 'Savings': '#3498db' })

Use colormap for automatic colors

Use colormap for automatic colors

sankey.node_colors(colormap='Pastel1')
sankey.node_colors(colormap='Pastel1')

Link colors (by source, target, or custom)

Link colors (by source, target, or custom)

sankey.link_colors(by='source') # Color by source node sankey.link_colors(by='target') # Color by target node sankey.link_colors(opacity=0.6) # Set link opacity
sankey.link_colors(by='source') # Color by source node sankey.link_colors(by='target') # Color by target node sankey.link_colors(opacity=0.6) # Set link opacity

Custom link colors

Custom link colors

sankey.link_colors(colors={ ('Income', 'Expenses'): '#ff6b6b', ('Income', 'Savings'): '#4ecdc4' })
sankey.link_colors(colors={ ('Income', 'Expenses'): '#ff6b6b', ('Income', 'Savings'): '#4ecdc4' })

Title

Title

sankey.title("My Flow Diagram") sankey.title("Budget Overview", font_size=20)
sankey.title("My Flow Diagram") sankey.title("Budget Overview", font_size=20)

Layout

Layout

sankey.layout(orientation='h') # Horizontal (default) sankey.layout(orientation='v') # Vertical sankey.layout(pad=20) # Node padding
undefined
sankey.layout(orientation='h') # Horizontal (default) sankey.layout(orientation='v') # Vertical sankey.layout(pad=20) # Node padding
undefined

Generation and Export

生成与导出

python
undefined
python
undefined

Generate the diagram

Generate the diagram

sankey.generate()
sankey.generate()

Save as interactive HTML

Save as interactive HTML

sankey.save_html("diagram.html") sankey.save_html("diagram.html", auto_open=True) # Open in browser
sankey.save_html("diagram.html") sankey.save_html("diagram.html", auto_open=True) # Open in browser

Save as static image

Save as static image

sankey.save_image("diagram.png") sankey.save_image("diagram.svg", format='svg') sankey.save_image("diagram.png", width=1200, height=800)
sankey.save_image("diagram.png") sankey.save_image("diagram.svg", format='svg') sankey.save_image("diagram.png", width=1200, height=800)

Get Plotly figure object for customization

Get Plotly figure object for customization

fig = sankey.get_figure() fig.update_layout(...)
fig = sankey.get_figure() fig.update_layout(...)

Show in notebook/browser

Show in notebook/browser

sankey.show()
undefined
sankey.show()
undefined

Data Format

数据格式

CSV Format

CSV格式

csv
source,target,value,label
Income,Housing,1500,Rent
Income,Food,600,Groceries
Income,Transport,400,Car
Income,Savings,500,Emergency Fund
Savings,Investments,300,Stocks
csv
source,target,value,label
Income,Housing,1500,Rent
Income,Food,600,Groceries
Income,Transport,400,Car
Income,Savings,500,Emergency Fund
Savings,Investments,300,Stocks

Dictionary Format

字典格式

python
data = {
    'source': ['Income', 'Income', 'Income', 'Expenses'],
    'target': ['Rent', 'Food', 'Savings', 'Tax'],
    'value': [1500, 600, 500, 400],
    'label': ['Housing', 'Groceries', 'Emergency', 'Federal']  # Optional
}
python
data = {
    'source': ['Income', 'Income', 'Income', 'Expenses'],
    'target': ['Rent', 'Food', 'Savings', 'Tax'],
    'value': [1500, 600, 500, 400],
    'label': ['Housing', 'Groceries', 'Emergency', 'Federal']  # Optional
}

DataFrame Format

DataFrame格式

python
import pandas as pd
df = pd.DataFrame({
    'from_node': ['A', 'A', 'B', 'C'],
    'to_node': ['B', 'C', 'D', 'D'],
    'flow_value': [100, 200, 150, 180]
})
python
import pandas as pd
df = pd.DataFrame({
    'from_node': ['A', 'A', 'B', 'C'],
    'to_node': ['B', 'C', 'D', 'D'],
    'flow_value': [100, 200, 150, 180]
})

Color Schemes

配色方案

Available Colormaps

可用配色映射

NameDescription
Pastel1
Soft pastel colors
Pastel2
Muted pastels
Set1
Bold distinct colors
Set2
Muted distinct colors
Set3
Light distinct colors
Paired
Paired color scheme
viridis
Blue-green-yellow
plasma
Purple-orange-yellow
名称描述
Pastel1
柔和淡彩
Pastel2
低饱和度淡彩
Set1
鲜明区分色
Set2
低饱和度区分色
Set3
浅色调区分色
Paired
配对配色方案
viridis
蓝-绿-黄渐变
plasma
紫-橙-黄渐变

Custom Colors

自定义颜色

python
undefined
python
undefined

Hex colors

Hex colors

sankey.node_colors({ 'Category A': '#1abc9c', 'Category B': '#3498db', 'Category C': '#9b59b6' })
sankey.node_colors({ 'Category A': '#1abc9c', 'Category B': '#3498db', 'Category C': '#9b59b6' })

Named colors

Named colors

sankey.node_colors({ 'Revenue': 'green', 'Costs': 'red', 'Profit': 'blue' })
undefined
sankey.node_colors({ 'Revenue': 'green', 'Costs': 'red', 'Profit': 'blue' })
undefined

CLI Usage

CLI使用方法

bash
undefined
bash
undefined

Basic usage

Basic usage

python sankey_creator.py --input flows.csv
--source from --target to --value amount
--output flow.html
python sankey_creator.py --input flows.csv
--source from --target to --value amount
--output flow.html

With title and colors

With title and colors

python sankey_creator.py --input budget.csv
--source category --target subcategory --value amount
--title "Budget Breakdown"
--colormap Pastel1
--output budget.html
python sankey_creator.py --input budget.csv
--source category --target subcategory --value amount
--title "Budget Breakdown"
--colormap Pastel1
--output budget.html

PNG output

PNG output

python sankey_creator.py --input data.csv
--source src --target dst --value val
--output diagram.png
--width 1200 --height 800
undefined
python sankey_creator.py --input data.csv
--source src --target dst --value val
--output diagram.png
--width 1200 --height 800
undefined

CLI Arguments

CLI参数

ArgumentDescriptionDefault
--input
Input CSV fileRequired
--source
Source column nameRequired
--target
Target column nameRequired
--value
Value column nameRequired
--output
Output file path
sankey.html
--title
Diagram titleNone
--colormap
Color scheme
Pastel1
--link-opacity
Link opacity (0-1)0.5
--orientation
'h' or 'v'
h
--width
Image width (PNG/SVG)1000
--height
Image height (PNG/SVG)600
参数描述默认值
--input
输入CSV文件必填
--source
源列名称必填
--target
目标列名称必填
--value
数值列名称必填
--output
输出文件路径
sankey.html
--title
图表标题无
--colormap
配色方案
Pastel1
--link-opacity
链接透明度（0-1）0.5
--orientation
方向：'h'（水平）或'v'（垂直）
h
--width
图片宽度（PNG/SVG格式）1000
--height
图片高度（PNG/SVG格式）600

Examples

示例

Budget Flow

预算流向

python
sankey = SankeyCreator()
sankey.from_dict({
    'source': ['Salary', 'Salary', 'Salary', 'Salary', 'Savings', 'Investments'],
    'target': ['Housing', 'Food', 'Transport', 'Savings', 'Investments', 'Stocks'],
    'value': [2000, 800, 500, 1000, 700, 700]
})
sankey.title("Monthly Budget Flow")
sankey.node_colors({
    'Salary': '#27ae60',
    'Housing': '#e74c3c',
    'Food': '#f39c12',
    'Transport': '#3498db',
    'Savings': '#9b59b6',
    'Investments': '#1abc9c',
    'Stocks': '#34495e'
})
sankey.generate().save_html("budget_flow.html")
python
sankey = SankeyCreator()
sankey.from_dict({
    'source': ['Salary', 'Salary', 'Salary', 'Salary', 'Savings', 'Investments'],
    'target': ['Housing', 'Food', 'Transport', 'Savings', 'Investments', 'Stocks'],
    'value': [2000, 800, 500, 1000, 700, 700]
})
sankey.title("Monthly Budget Flow")
sankey.node_colors({
    'Salary': '#27ae60',
    'Housing': '#e74c3c',
    'Food': '#f39c12',
    'Transport': '#3498db',
    'Savings': '#9b59b6',
    'Investments': '#1abc9c',
    'Stocks': '#34495e'
})
sankey.generate().save_html("budget_flow.html")

Energy Flow

能源流向

python
sankey = SankeyCreator()
sankey.add_flow("Coal", "Electricity", 100)
sankey.add_flow("Gas", "Electricity", 80)
sankey.add_flow("Solar", "Electricity", 30)
sankey.add_flow("Electricity", "Industry", 120)
sankey.add_flow("Electricity", "Residential", 60)
sankey.add_flow("Electricity", "Commercial", 30)

sankey.title("Energy Flow")
sankey.node_colors(colormap='Set2')
sankey.link_colors(by='source', opacity=0.4)
sankey.generate().save_html("energy.html")
python
sankey = SankeyCreator()
sankey.add_flow("Coal", "Electricity", 100)
sankey.add_flow("Gas", "Electricity", 80)
sankey.add_flow("Solar", "Electricity", 30)
sankey.add_flow("Electricity", "Industry", 120)
sankey.add_flow("Electricity", "Residential", 60)
sankey.add_flow("Electricity", "Commercial", 30)

sankey.title("Energy Flow")
sankey.node_colors(colormap='Set2')
sankey.link_colors(by='source', opacity=0.4)
sankey.generate().save_html("energy.html")

User Journey

用户旅程

python
sankey = SankeyCreator()
sankey.from_dict({
    'source': ['Landing', 'Landing', 'Product', 'Product', 'Cart', 'Cart'],
    'target': ['Product', 'Exit', 'Cart', 'Exit', 'Checkout', 'Exit'],
    'value': [1000, 200, 600, 200, 400, 100]
})
sankey.title("User Journey")
sankey.node_colors({
    'Landing': '#3498db',
    'Product': '#2ecc71',
    'Cart': '#f1c40f',
    'Checkout': '#27ae60',
    'Exit': '#e74c3c'
})
sankey.generate().save_html("journey.html")
python
sankey = SankeyCreator()
sankey.from_dict({
    'source': ['Landing', 'Landing', 'Product', 'Product', 'Cart', 'Cart'],
    'target': ['Product', 'Exit', 'Cart', 'Exit', 'Checkout', 'Exit'],
    'value': [1000, 200, 600, 200, 400, 100]
})
sankey.title("User Journey")
sankey.node_colors({
    'Landing': '#3498db',
    'Product': '#2ecc71',
    'Cart': '#f1c40f',
    'Checkout': '#27ae60',
    'Exit': '#e74c3c'
})
sankey.generate().save_html("journey.html")

Multi-Level Flow

多层级流向

python
undefined
python
undefined

Three-level hierarchy

Three-level hierarchy

data = { 'source': [ # Level 1 -> Level 2 'Revenue', 'Revenue', 'Revenue', # Level 2 -> Level 3 'Products', 'Products', 'Services', 'Services' ], 'target': [ 'Products', 'Services', 'Other', 'Electronics', 'Software', 'Consulting', 'Support' ], 'value': [500, 300, 50, 300, 200, 200, 100] }
sankey = SankeyCreator() sankey.from_dict(data) sankey.title("Revenue Breakdown") sankey.generate().save_html("revenue.html")
undefined
data = { 'source': [ # Level 1 -> Level 2 'Revenue', 'Revenue', 'Revenue', # Level 2 -> Level 3 'Products', 'Products', 'Services', 'Services' ], 'target': [ 'Products', 'Services', 'Other', 'Electronics', 'Software', 'Consulting', 'Support' ], 'value': [500, 300, 50, 300, 200, 200, 100] }
sankey = SankeyCreator() sankey.from_dict(data) sankey.title("Revenue Breakdown") sankey.generate().save_html("revenue.html")
undefined

Dependencies

依赖项

plotly>=5.15.0
pandas>=2.0.0
kaleido>=0.2.0
plotly>=5.15.0
pandas>=2.0.0
kaleido>=0.2.0

Limitations

限制说明

  • Static image export (PNG/SVG) requires 
    kaleido
    package
  • Very complex diagrams with many nodes may be hard to read
  • Node positions are auto-calculated (limited manual control)
  • Link colors can only be uniform or by source/target
  • 静态图片导出（PNG/SVG）需要安装
    kaleido
    包
  • 包含大量节点的复杂图表可能难以阅读
  • 节点位置为自动计算（手动控制有限）
  • 链接颜色仅支持统一配色或按源/目标节点配色