Pelote

Pelote是一个Python库，包含许多图相关函数，可用于补充networkx以进行高级任务。

它主要帮助以下方面

• 将表格数据转换为图（如Table2Net精神中的二部图、引文等）
• 将图转换为表格数据
• 二部图的单部投影
• 各种图辅助函数（过滤节点、边等）
• 图的稀疏化
• 读取和写入在networkx中找不到的图格式（如graphology JSON）

因此，它是我们的Jupyter小部件ipysigma的完美伴侣，可以直接在您的笔记本中渲染交互式图。

安装

您可以使用以下命令使用pip安装pelote

pip install pelote

如果您想使用pandas库，您也需要安装它

pip install pandas

使用方法

• 表格数据到图
  • table_to_bipartite_graph
  • tables_to_graph
  • edges_table_to_graph
• 图到表格数据
  • graph_to_nodes_dataframe
  • graph_to_edges_dataframe
  • graph_to_dataframes
• 图投影
  • monopartite_projection
• 图稀疏化
  • global_threshold_sparsification
  • multiscale_backbone
• 各种图相关指标
  • edge_disparity
  • triangular_strength
• 图工具
  • union_of_maximum_spanning_trees
  • largest_connected_component
  • crop_to_largest_connected_component
  • 最大的连通分量子图
  • 移除边
  • 过滤边
  • 移除节点
  • 过滤节点
  • 移除叶子节点
  • 过滤叶子节点
• 学习
  • floatsam_threshold_learner
• 读取和写入
  • 读取图论JSON
  • 写入图论JSON

---

表格数据到图

table_to_bipartite_graph

从给定的表格数据创建二分图的函数。

参数

• table 可迭代[可索引]或pd.DataFrame - 输入的表格数据。只要它是可迭代的并且产生可索引值（如字典或列表），它可以是一系列事物。例如，这可以是字典列表，csv.DictReader流等。如果已安装库，它还支持pandas DataFrame。
• first_part_col 可散列 - 包含表示结果图第一部分节点值的列的名称。如果您的行是列表，则可能是索引，如果是字典，则可能是键。
• second_par_col 可散列 - 包含表示结果图第二部分节点值的列的名称。如果您的行是列表，则可能是索引，如果是字典，则可能是键。
• node_part_attr str, 可选 "part" - 包含节点属于的部分的节点属性的名称。
• edge_weight_attr str, 可选 "weight" - 包含其权重的边属性的名称，即它在表中出现的次数。
• first_part_data 序列或可调用或映射，可选 None - 作为图的第一部分的节点属性保留的行中的列的序列（即列表、元组等）。也可以是映射（即字典），从行列到要创建的节点属性名称。也可以是返回包含这些属性的字典的函数。请注意，包含给定节点的第一行将优先于后续行，有关要包含的数据。
• second_part_data 序列或可调用或映射，可选 None - 作为图的第二部分的节点属性保留的行中的列的序列（即列表、元组等）。也可以是映射（即字典），从行列到要创建的节点属性名称。也可以是返回包含这些属性的字典的函数。请注意，包含给定节点的第一行将优先于后续行，有关要包含的数据。
• first_part_name 可散列，可选 None - 可以用来重命名第一部分。
• second_part_name 可散列，可选 None - 可以用来重命名第二部分，以显示为图第二部分名称。
• disjoint_keys bool，可选 False - 如果您知道您的部分键是互斥的，即如果first_part_col中找不到second_part_col的值，则将此设置为True作为优化机制。如果错误地启用此选项，结果可能是不正确的。

返回

nx.AnyGraph - 二分图。

tables_to_graph

从两个表格创建图的函数：节点表和边表。

from pelote import tables_to_graph

table_nodes = [
    {"name": "alice", "age": 50},
    {"name": "bob", "age": 12}
]

table_edges = [
    {"source": "alice", "target": "bob", "weight": 0.8},
    {"source": "bob", "target": "alice", "weight": 0.2}
]

g = tables_to_graph(
    table_nodes, table_edges, node_col="name", node_data=["age"], edge_data=["weight"], directed=True
)

参数

• nodes_table 可迭代[可索引]或pd.DataFrame - 以表格格式输入的节点。只要它是可迭代的并且产生可索引值（如字典或列表），它可以是一系列事物。例如，这可以是字典列表，csv.DictReader流等。如果已安装库，它还支持pandas DataFrame。
• edges_table 可迭代[可索引]或pd.DataFrame - 以表格格式输入的边。
• node_col 可散列，可选 "key" - 包含节点_table中节点的列的名称。如果您的行是列表，则可能是索引，如果是字典，则可能是键。
• edge_source_col 可散列，可选 "source" - 包含边_table中边源节点的列的名称。
• edge_target_col 可哈希的，可选 "target" - 包含边目标节点的edges_table列的名称。
• node_data 序列，可选 [] - 要保留为结果图中节点属性的nodes_table列名称序列（例如列表、元组等）。
• edge_data 序列，可选 [] - 要保留为结果图中边属性的edges_table列名称序列（例如列表、元组等），例如["weight"]。
• count_rows_as_weight 布尔值，可选 False - 将此设置为True，以计算每个边的权重属性，对应其在表中出现的次数。此属性的名称由edge_weight_attr参数定义。如果设置为False，则仅保留每个边的最后出现。
• edge_weight_attr 字符串，可选 "weight" - 包含边权重（即其在表中出现的次数）的边属性名称，如果count_rows_as_weight设置为True。
• add_missing_nodes 布尔值，可选 True - 将此设置为True，以检查edges_table中边的源和目标是否都在nodes_table中定义。
• directed 布尔值，可选 False - 结果图是否必须是有向图。

返回

nx.AnyGraph - 结果图。

edges_table_to_graph

从边表创建图的函数。

参数

• edges_table 可迭代索引或pd.DataFrame - 以表格格式输入的边。只要它是1.可迭代的，2.产生可索引值（如字典或列表），则可以是各种各样的事物。例如，可以是字典列表、csv.DictReader流等。如果已安装库，也支持pandas DataFrame。
• edge_source_col 可散列，可选 "source" - 包含边_table中边源节点的列的名称。
• edge_target_col 可哈希的，可选 "target" - 包含边目标节点的edges_table列的名称。
• edge_data 序列，可选 [] - 要保留为结果图中边属性的edges_table列名称序列（例如列表、元组等），例如["weight"]。
• count_rows_as_weight 布尔值，可选 False - 将此设置为True，以计算每个边的权重属性，对应其在表中出现的次数。此属性的名称由edge_weight_attr参数定义。如果设置为False，则仅保留每个边的最后出现。
• edge_weight_attr 字符串，可选 "weight" - 包含边权重（即其在表中出现的次数）的边属性名称，如果count_rows_as_weight设置为True。
• directed 布尔值，可选 False - 结果图是否必须是有向图。

返回

nx.AnyGraph - 结果图。

---

图到表格数据

graph_to_nodes_dataframe

将给定的networkx图转换为包含其节点的pandas DataFrame的函数。

from pelote import graph_to_nodes_dataframe

df = graph_to_nodes_dataframe(graph)

参数

• nx.AnyGraph - 一个networkx图实例
• node_key_col 字符串，可选 "key" - 包含节点键的DataFrame列的名称。如果为None，则将使用节点键作为DataFrame的索引。

返回

pd.DataFrame - 一个pandas DataFrame

graph_to_edges_dataframe

将给定的networkx图转换为包含其边的pandas DataFrame的函数。

参数

• nx.AnyGraph - 一个networkx图实例
• edge_source_col 字符串，可选 "source" - 包含边源的DataFrame列的名称。
• edge_target_col 字符串，可选 "target" - 包含边目标的DataFrame列的名称。
• source_node_data 可迭代或映射，可选 None - 属性名称的可迭代序列或从属性名称到列名称的映射，用于根据源节点数据添加列到结果dataframe。
• target_node_data 可迭代或映射，可选 None - 属性名称的可迭代序列或从属性名称到列名称的映射，用于根据目标节点数据添加列到结果dataframe。

返回

pd.DataFrame - 一个pandas DataFrame

graph_to_dataframes

将给定的networkx图转换为两个pandas DataFrame：一个用于其节点，一个用于其边。

参数

• nx.AnyGraph - 一个networkx图实例
• node_key_col 字符串，可选 "key" - 包含节点键的节点DataFrame列的名称。如果为None，则将使用节点键作为DataFrame的索引。
• edge_source_col 字符串，可选 "source" - 包含边源的边DataFrame列的名称。
• edge_target_col 字符串，可选 "target" - 包含边目标的边DataFrame列的名称。
• source_node_data 可迭代或映射，可选 None - 属性名称的可迭代序列或从属性名称到列名称的映射，用于根据源节点数据添加列到边dataframe。
• target_node_data 可迭代对象或映射，可选 None - 属性名称的可迭代对象或属性名称到列名称的映射，用于根据目标节点数据向边数据框添加列。

返回

None - (pd.DataFrame, pd.DataFrame)

---

图投影

monopartite_projection

返回给定二分图的单一分区投影的函数。

换句话说，生成的图将保留具有基于它们在二分图中共享的邻居的加权边的单一种类的节点。

import networkx as nx
from pelote import monopartite_projection

bipartite = nx.Graph()
bipartite.add_nodes_from([1, 2, 3], part='account')
bipartite.add_nodes_from([4, 5, 6], part='color')
bipartite.add_edges_from([
    (1, 4),
    (1, 5),
    (2, 6),
    (3, 4),
    (3, 6)
])

# Resulting graph will only contain nodes [1, 2, 3]
# with edges: (1, 3) and (2, 3)
monopartite = monopartite_projection(bipartite, 'account')

参数

• bipartite_graph nx.AnyGraph - 目标图。如果给定的图不是真正的二分图，则函数将引发错误。
• part_to_keep 可哈希或集合 - 要保留在投影图中的分区。它可以是给定图中部分节点属性的值（通常是字符串），也可以是包含组成要保留的部分的节点的集合（集合、列表等）。
• node_part_attr str，可选 "part" - 包含节点所属的部分的节点属性的名称。
• edge_weight_attr str，可选 "weight" - 包含边权重的边属性名称。
• metric str，可选 None - "jaccard"、"overlap"、"cosine"、"dice"、"binary_cosine"、"pmi" 或 "dot_product" 之一。如果没有给出，结果权重将被设置为邻居交集的大小。
• bipartition_check bool，可选 True - 是否检查给定的图是否为真正的二分图。如果您知道自己在做什么，可以禁用此选项作为优化策略。
• weight_threshold float，可选 None - 如果边的权重小于此阈值，则不会将其添加到投影的单分区图中。

返回

nx.Graph - 投影的单分区图。

---

图稀疏化

global_threshold_sparsification

返回给定图的副本，但不包括权重小于给定阈值的边。

参数

• graph nx.AnyGraph - 目标图。
• weight_threshold float - 权重阈值。
• edge_weight_attr str，可选 - 边权重属性的名称。
• reverse bool，可选 - 是否反转阈值条件。也就是说，如果边的权重大于阈值，则将其删除。
• keep_connected bool，可选 False - 是否使用UMST方法保持图连接。

返回

nx.AnyGraph - 稀疏图。

multiscale_backbone

返回给定图的多个尺度骨干，即只保留“相关”边的图的副本，这些边由统计测试定义，其中我们比较加权边存在的可能性与零模型。

文章

Serrano, M. Ángeles, Marián Boguná, and Alessandro Vespignani. "Extracting the multiscale backbone of complex weighted networks." Proceedings of the national academy of sciences 106.16 (2009): 6483-6488.

参考文献

• https://www.pnas.org/content/pnas/106/16/6483.full.pdf
• https://en.wikipedia.org/wiki/Disparity_filter_algorithm_of_weighted_network

参数

• graph nx.AnyGraph - 目标图。
• alpha float，可选 0.05 - 统计测试的 alpha 值。可以直观地将其视为结果图中要保留的边的 p 值分数。
• edge_weight_attr str，可选 "weight" - 包含边权重的边属性名称。
• keep_connected bool，可选 False - 是否使用UMST方法保持图连接。

返回

nx.AnyGraph - 稀疏图。

---

各种图相关指标

edge_disparity

计算给定图中每条边的差异分数的函数。这个分数通常用于提取加权图的多尺度骨干。

来自论文的公式（依赖于积分计算）可以简化为

disparity(u, v) = min(
    (1 - normalizedWeight(u, v)) ^ (degree(u) - 1)),
    (1 - normalizedWeight(v, u)) ^ (degree(v) - 1))
)

其中

normalizedWeight(u, v) = weight(u, v) / weightedDegree(u)
weightedDegree(u) = sum(weight(u, v) for v in neighbors(u))

有时可以找到相反的分数

disparity(u, v) = max(
    1 - (1 - normalizedWeight(u, v)) ^ (degree(u) - 1)),
    1 - (1 - normalizedWeight(v, u)) ^ (degree(v) - 1))
)

因此，更高的分数意味着更好的边。我们选择了与论文相似的度量标准，以保持统计测试的角度。这意味着至少在这个实现中，边的低分数意味着高相关性，并增加了其被保留在骨干中的机会。

请注意，此算法对于有向图没有明确的定义，并且仅在有边权重不同的条件下才有用。换句话说，如果我们放弃最小值部分，仅根据边的方向计算差异分数也是可能的。

文章

Serrano, M. Ángeles, Marián Boguná, and Alessandro Vespignani. "Extracting the multiscale backbone of complex weighted networks." Proceedings of the national academy of sciences 106.16 (2009): 6483-6488.

参考文献

• https://www.pnas.org/content/pnas/106/16/6483.full.pdf
• https://en.wikipedia.org/wiki/Disparity_filter_algorithm_of_weighted_network

参数

• graph nx.AnyGraph - 目标图。
• edge_weight_attr str，可选 "weight" - 包含其权重的边属性名称。
• reverse bool，可选 False - 是否反转度量，即更高的权重意味着更相关的边。

返回

dict - 包含边的字典 - 以（源，目标）元组为键，差异分数为值的字典。

triangular_strength

返回图边三角强度的函数，有时也称为Simmelian强度，即每条边是几个三角形的组成部分。

参数

• graph nx.AnyGraph - 目标图。
• full bool，可选 False - 是否返回每条边的强度，包括强度为0的边。

返回

dict - 边与其三角强度之间的映射。

---

图工具

union_of_maximum_spanning_trees

生成器产生属于给定networkx图的任何最大生成树（MST）的边。

注意，此函数将给没有权重的每条边赋予默认权重1。

文章

Arlind Nocaj，Mark Ortmann，和Ulrik Brandes "解开毛线球。从3到14度的分离。" 计算机与信息科学，康斯坦茨大学，德国，2014年，https://dx.doi.org/10.1007/978-3-662-45803-7_9。

参考文献

• https://kops.uni-konstanz.de/bitstream/handle/123456789/30583/Nocaj_0-284485.pdf

参数

• graph nx.AnyGraph - 目标图。
• edge_weight_attr str，可选 "weight" - 边权重属性名称。

产出

tuple - 源，目标，属性

largest_connected_component

返回给定networkx图的最大连通组件作为节点集合的函数。

注意，此函数将考虑任何给定的图作为无向图，因此在有向情况下将使用弱连通分量。

参数

• graph nx.AnyGraph - 目标图。

返回

set - 代表最大连通组件的节点集合。

crop_to_largest_connected_component

修改给定networkx图，以保留最大的连通组件的函数。

注意，此函数将考虑任何给定的图作为无向图，因此在有向情况下将使用弱连通分量。

参数

• graph nx.AnyGraph - 目标图。

最大的连通分量子图

返回给定networkx图的最大连通组件子图的函数。

注意，此函数将考虑任何给定的图作为无向图，因此在有向情况下将使用弱连通分量。

参数

• graph nx.AnyGraph - 目标图。
• as_view bool，可选 False - 是否以视图返回子图。

返回

nx.AnyGraph - 子图。

移除边

从给定networkx图中删除所有不通过谓词函数的边的函数。

注意，此函数会修改给定的图。

参数

• graph nx.AnyGraph - 一个networkx图。
• predicate callable - 接受每个边源、目标和属性作为参数的函数，如果希望保留该边则返回True，如果希望删除它则返回False。

过滤边

返回给定networkx图的副本，但不包括由给定的谓词函数过滤掉的边。

参数

• graph nx.AnyGraph - 一个networkx图。
• predicate callable - 接受每个边源、目标和属性作为参数的函数，如果希望保留该边则返回True，如果希望删除它则返回False。

返回

nx.AnyGraph - 过滤后的图。

移除节点

从给定networkx图中删除所有不通过谓词函数的节点的函数。

注意，此函数会修改给定的图。

from pelote import remove_nodes

g = nx.Graph()
g.add_node(1, weight=22)
g.add_node(2, weight=4)
g.add_edge(1, 2)

remove_nodes(g, lambda n, a: a["weight"] >= 10)

参数

• graph nx.AnyGraph - 一个networkx图。
• predicate callable - 接受每个节点和节点属性作为参数的函数，如果希望保留该节点则返回True，如果希望删除它则返回False。

过滤节点

返回给定networkx图的副本，但不包括由给定的谓词函数过滤掉的节点。

from pelote import filter_nodes

g = nx.Graph()
g.add_node(1, weight=22)
g.add_node(2, weight=4)
g.add_edge(1, 2)

h = filter_nodes(g, lambda n, a: a["weight"] >= 10)

参数

• graph nx.AnyGraph - 一个networkx图。
• predicate callable - 接受每个节点和节点属性作为参数的函数，如果希望保留该节点则返回True，如果希望删除它则返回False。

返回

nx.AnyGraph - 过滤后的图。

移除叶子节点

删除图中的所有叶子节点，即与单个边相关的节点，即度数为1的节点。

此函数不是递归的，并且只会删除一层叶子节点。

注意，此函数会修改给定的图。

from pelote import remove_leaves

g = nx.Graph()
g.add_edge(1, 2)
g.add_edge(2, 3)

remove_leaves(g)

list(g.nodes)
>>> [2]

参数

• graph nx.AnyGraph - 一个networkx图。

过滤叶子节点

返回给定networkx图的副本，但不包括其叶子节点，即与单个边相关的节点，即度数为1的节点。

此函数不是递归的，并且只会过滤掉一层叶子节点。

from pelote import remove_leaves

g = nx.Graph()
g.add_edge(1, 2)
g.add_edge(2, 3)

h = filter_leaves(g)

list(h.nodes)
>>> [2]

参数

• graph nx.AnyGraph - 一个networkx图。

---

学习

floatsam_threshold_learner

使用迭代算法尝试找到应用于修剪给定图边的同时保留底层社区结构的最佳权重阈值的函数。

它通过迭代增加阈值，一旦一个显著的连通分量开始远离主要的一个，就停止。

这基本上是一个优化算法，它使用一个非常简单的成本启发式方法应用于一个复杂的非线性函数，但对于典型情况来说效果不错，因为它模仿了一些研究者在Gephi上执行此类任务时所使用的手动方法。

当处理越低越好（例如，边差异）的度量时，你可以通过调整starting_threshold和提供负数的learning_rate来反转算法的逻辑。

参数

• graph nx.Graph - 要稀疏化的图。
• starting_threshold float, 可选 0.0 - 开始相似度阈值。
• learning_rate float, 可选 0.05 - 在算法的每一步中增加阈值的程度。
• max_drifter_order int, 可选 - 算法停止之前，从主要组件中分离自身的组件的最大顺序。如果没有提供，则默认为图的最大连通组件的阶数的对数。
• edge_weight_attr str, 可选 "weight" - 权重属性的名称。
• on_epoch callable, 可选 - 在算法的每个时代被调用的函数，带有关于迭代状态的元数据。

返回

float - 找到的阈值

---

读取和写入

读取图论JSON

函数读取并解析表示序列化的graphology图的JSON文件，作为networkx图。

请注意，此函数无法解析真正的混合图，因为networkx不支持。

参数

• target str 或 Path 或文件 或 dict - 要读取和解析的目标。可以是字符串路径、Path实例、文件缓冲区或已解析的JSON数据作为字典。

返回

nx.AnyGraph - 一个networkx图实例。

写入图论JSON

函数将给定的networkx图序列化为JSON，使用graphology格式。

请注意，节点键和属性名称都将被转换为字符串，以便安全地表示为JSON。因此，在某些情况下（如果您的节点键和/或属性名称不是字符串），则在使用read_graphology_json时此函数可能不是双射。

参数

• graph nx.AnyGraph - 要序列化的图。
• allow_mixed_keys bool, 可选 False - 是否允许序列化具有混合节点键类型的图。键始终被转换为字符串，因此键可能冲突并产生无效的序列化。仅在了解自己在做什么的情况下使用此功能。
• allow_invalid_attr_names bool, 可选 False - 是否允许非字符串属性名称。请注意，如果您选择允许它们，其中一些可能冲突并产生无效的序列化。仅在了解自己在做什么的情况下使用此功能。

返回

dict - JSON数据