pygraphistry-visualization

PyGraphistry 可视化

文档路由（本地 + 规范链接）

• 首先通过 ../pygraphistry/references/pygraphistry-readthedocs-toc.md 路由。
• 使用 ../pygraphistry/references/pygraphistry-readthedocs-top-level.tsv 查找章节级快捷入口。
• 仅在所需页面缺失时，才扫描 ../pygraphistry/references/pygraphistry-readthedocs-sitemap.xml。
• 深入读取页面前，先进行一次批量发现读取；避免使用 cat * 和串行的微小读取。
• 使用本地的图标查找说明 references/fa-icons.md。
• 面向用户的回答中，优先使用规范的 https://pygraphistry.readthedocs.io/en/latest/... 链接。

核心模式

g2 = (
    # Keep a plain 'type' column on both nodes and edges for legend-friendly defaults
    g.bind(point_label='label', point_color='type', edge_color='type')
     .encode_point_color('type', categorical_mapping={'agent': '#3b82f6'}, default_mapping='#94a3b8')
     # Optional: default node sizing is often degree for exploratory passes
     .encode_point_size('degree')
     .settings(url_params={'play': 3000, 'info': True})
)
g2.plot()

外部布局模式

# nodes_df contains x/y layout columns
g2 = graphistry.edges(edges_df, 'src', 'dst').nodes(nodes_df, 'id').bind(point_x='x', point_y='y').settings(url_params={'play': 0})
g2.plot()

URL 参数参考

使用 settings(url_params={...}) 控制可视化行为。完整参考：https://hub.graphistry.com/docs/api/1/rest/url/#urloptions

布局

参数	类型	默认值	范围	描述
play	int	5000	0-10000 (0, 1000, 2000, 5000)	布局时长（毫秒）。0 = 固定
lockedX	bool	false		锁定 X 轴（配合 bind(point_x=...) 使用）
lockedY	bool	false		锁定 Y 轴（配合 bind(point_y=...) 使用）
lockedR	bool	false		锁定径向位置
linLog	bool	false		强力分离；适用于少于 1000 个节点
scalingRatio	float	1.0	0.1-10 (0.5, 1, 2, 5)	扩展比例。与 linLog 结合使用
strongGravity	bool	false		紧凑布局，将节点拉向中心
dissuadeHubs	bool	false		降低枢纽节点对布局的主导影响
gravity	float	1.0	0.1-10 (0.1, 1, 2, 10)	向中心的拉力
edgeInfluence	float	1.0	0-10 (0, 0.7, 1, 2, 5, 7)	边权重对布局的影响
precisionVsSpeed	float	1.0	0.1-10 (0.1, 1, 10)	值越高越精确，但速度越慢
left/right/top/bottom	int	auto		加载时手动设置摄像机边界

场景 / 渲染

参数	类型	默认值	范围	描述
pointSize	float	1.0	0.1-10 (0.3, 0.5, 1, 2, 3)	点大小倍数（非编码值）
pointOpacity	float	1.0	0-1 (0.3, 0.5, 0.8, 1)	节点透明度
pointStrokeWidth	float	0	0-5 (0, 1, 2)	节点边框宽度
edgeCurvature	float	0	0-1 (0, 0.5, 1)	边的弯曲程度
edgeOpacity	float	1.0	0-1 (0.3, 0.5, 0.8, 1)	边的透明度
showArrows	bool	true		显示边的方向箭头
neighborhoodHighlight	str	both	incoming/outgoing/both/node	悬停高亮模式
neighborhoodHighlightHops	int	1	1-5 (1, 2, 3)	悬停高亮的跳数

标签 / 兴趣点

参数	类型	默认值	范围	描述
showLabels	bool	true		切换所有标签的可见性
showLabelOnHover	bool	true		仅在悬停时显示标签
showPointsOfInterest	bool	true		将关键节点标记为兴趣点（POI）
showPointsOfInterestLabel	bool	true		显示兴趣点节点的标签
pointsOfInterestMax	int	5	0-100 (0, 5, 10, 20)	兴趣点上限。0 = 禁用
shortenLabels	bool	true		截断较长的标签
showLabelPropertiesOnHover	bool	false		悬停时显示额外属性
labelOpacity	float	1.0	0-1 (0.5, 0.8, 1)	标签透明度
labelColor	str		hex no # (000000, FFFFFF)	标签文字颜色
labelBackground	str		hex no # (000000, FFFFFF)	标签背景颜色

注意：URL 参数使用不带 # 的十六进制值。Python API（encode_*、palette）使用带 # 前缀的值。

UI 控件

参数	类型	默认值	描述
menu	bool	true	显示所有菜单
info	bool	true	显示图大小统计信息
showHistograms	bool	true	显示直方图面板
showInspector	bool	true	显示实体检查器
showCollections	bool	false	显示集合面板

示例

# Ring layout with strong separation for small graphs (<1000 nodes)
g2 = g.settings(url_params={'play': 3000, 'linLog': True, 'scalingRatio': 2.0})

# Fixed position layout (external coordinates)
g2 = g.bind(point_x='x', point_y='y').settings(url_params={'play': 0, 'lockedX': True, 'lockedY': True})

# Disable POI labels entirely
g2 = g.settings(url_params={'showLabels': False, 'pointsOfInterestMax': 0})

# Larger points, more transparent edges
g2 = g.settings(url_params={'pointSize': 3.0, 'edgeOpacity': 0.3})

# Minimal UI for embedding
g2 = g.settings(url_params={'menu': False, 'info': False, 'showHistograms': False, 'showInspector': False})

图标/徽章模式

g2 = (
    g.encode_point_icon('type', categorical_mapping={'person': 'user', 'org': 'building'})
     .encode_point_badge('risk', categorical_mapping={'high': 'exclamation-triangle'})
)
g2.plot()

使用有效的 Font Awesome 名称，并根据 type 对图标进行分类映射。 查阅 references/fa-icons.md，获取查询链接和示例。

连续色模式（超越分类映射）

g2 = g.encode_edge_color('amount', palette=['#46327e', '#1fa187', '#fde724'], as_continuous=True)
g2.plot()

聚焦子图视图（类似集合的工作流）

# Use GFQL slices to publish multiple focused views from one base graph (use .gfql(), not deprecated .chain())
high_risk = g.gfql([...]).name('high-risk-slice')
partner_flow = g.gfql([...]).name('partner-flow-slice')
urls = [high_risk.plot(render=False), partner_flow.plot(render=False)]

隐私安全的分享模式

graphistry.privacy(mode='private')
plot_url = g.plot(render=False)

• 分享链接前，使用明确的 graphistry.privacy(mode='private'|'organization'|'public')。
• 不要将 plot() 的参数（如 as_files 或 memoize）视为隐私控制项。

常见任务

• 编码：encode_point_color、encode_edge_color、encode_point_size、encode_point_icon、encode_point_badge。
• 布局：运行时力导向布局设置、环形/GIB/模块度布局、graphviz/igraph/cugraph 插件布局。
• 静态输出：使用 plot_static() 生成 SVG/PNG，以及 graphviz-dot/mermaid-code 等文本引擎。
• 分享控制：graphistry.privacy(mode='private'|'organization'|'public')。
• 若要使用高级渐变，请在 encode_point_color/encode_edge_color 中使用 palette=[...] 和 as_continuous=True。
• 对于大型调查，请生成多个聚焦的 GFQL 切片，而不是生成一个负载过重的绘图。

大型图的默认做法

• 绘图前先进行筛选和聚合。
• 仅保留必要的列（除非需要，否则删除大型文本块）。
• 使用聚焦子图（时间切片、单跳邻域、top-k 信号）。
• 节点和边都优先使用普通的 type 列，以保持图例和默认分类编码稳定。
• 避免使用 node.type / edge.type 等带点号的列名；优先使用普通名称。
• 时间编码和分时段比较应使用原生 datetime 类型。

权威文档

• 可视化中心：https://pygraphistry.readthedocs.io/en/latest/visualization/index.html
• 10 分钟可视化：https://pygraphistry.readthedocs.io/en/latest/visualization/10min.html
• 布局指南：https://pygraphistry.readthedocs.io/en/latest/visualization/layout/intro.html
• 布局目录：https://pygraphistry.readthedocs.io/en/latest/visualization/layout/catalog.html
• URL 参数参考：https://hub.graphistry.com/docs/api/1/rest/url/#urloptions
• 隐私/分享：https://pygraphistry.readthedocs.io/en/latest/server/privacy.html
• 可视化笔记本索引：https://pygraphistry.readthedocs.io/en/latest/notebooks/visualization.html
• 图标查询参考：references/fa-icons.md