三元组

一个用于处理三元组的模块。

知识图谱可以被视为一系列事实的集合,其中每个单独的事实被表示为一个三元组,包括头实体 \(h\)、关系 \(r\) 和尾实体 \(t\)。为了高效地操作这些数据,PyKEEN 的大部分功能假设实体集合已经被转换,以便它们通过从 \([0, \ldots, E)\) 的整数来标识,其中 \(E\) 是实体的数量。对于关系,也做出了类似的假设,其索引为 \([0, \ldots, R]\)

该模块包括用于从其他格式加载和转换三元组到基于索引的格式的类和方法,以及用于创建无泄漏的训练和测试分割以及分析数据分布的高级方法。

基本处理

关于知识图谱的最基本信息存储在KGInfo中。它包含了创建知识图谱嵌入所需的最少信息:实体和关系的数量,以及关于使用逆关系的信息(这会人为增加关系的数量)。

为了存储关于三元组的信息,有CoreTriplesFactory。它通过额外存储一组基于索引的三元组(以3列矩阵的形式)扩展了KGInfo。它还允许以(JSON兼容的)字典形式存储任意元数据。它还增加了对序列化的支持,即保存和加载到文件,以及过滤操作和实用方法,以创建用于进一步(外部)处理的数据框。

最后,还有TriplesFactory,它增加了基于字符串的实体和关系名称到ID的映射。该类还提供了丰富的工厂方法,允许仅从基于字符串的三元组创建映射,从足够相似的外部文件格式(如TSV或CSV)加载三元组,并在基于标签和基于索引的格式之间进行转换。它还扩展了序列化,以确保字符串到索引的映射与文件一起包含。

分割

为了评估知识图谱嵌入模型,我们需要训练集、验证集和测试集。 在经典的机器学习设置中,我们通常有大量的独立样本,并且可以使用简单的随机采样。 然而,在图学习设置中,我们关注的是学习关系模式,即不同样本之间的模式。 在这些设置中,我们需要更加小心。

例如,为了在转导设置中评估模型,我们需要确保评估中使用的三元组的所有实体和关系也存在于训练三元组中。 PyKEEN 包含了构建分割的方法,以确保所有实体和关系都存在于训练部分。 这些方法可以在 pykeen.triples.splitting 中找到。

此外,知识图谱可能包含反向关系,例如前驱后继关系。 在这种情况下,粗心的分割可能导致测试泄漏,其中仅检查反向关系是否存在于训练中的模型可以产生显著强大的结果,从而在不学习有意义的关系模式的情况下夸大分数。 PyKEEN 包含检查知识图谱分割泄漏的方法,可以在 pykeen.triples.leakage 中找到。

pykeen.triples.remix中,我们提供了方法来检查特定分割选择的影响。

分析

我们还提供了分析知识图谱的方法。 这些方法包括简单的统计,如实体或关系的数量(在pykeen.triples.stats中), 以及关系模式的高级分析(pykeen.triples.analysis)。

函数

get_mapped_triples([x, mapped_triples, ...])

获取基于ID的三元组,可以直接获取,也可以通过工厂获取。

Instances()

训练实例的基类。

LCWAInstances(*, pairs, compressed)

LCWA的三元组及其索引的映射。

SLCWAInstances(*, mapped_triples[, ...])

sLCWA的训练实例。

KGInfo(num_entities, num_relations, ...)

一个存储有关实体和关系数量信息的对象。

CoreTriplesFactory(mapped_triples, ...[, ...])

从基于ID的三元组创建实例。

TriplesFactory(mapped_triples, entity_to_id, ...)

根据三元组的路径创建实例。

TriplesNumericLiteralsFactory(*, ...)

根据三元组的路径创建多模态实例。

变量

AnyTriples

tuple[str, str, str] | Sequence[tuple[str, str, str]] | ndarray | Tensor | CoreTriplesFactory 的别名

类继承图

Inheritance diagram of pykeen.triples.instances.Instances, pykeen.triples.instances.LCWAInstances, pykeen.triples.instances.SLCWAInstances, pykeen.triples.triples_factory.KGInfo, pykeen.triples.triples_factory.CoreTriplesFactory, pykeen.triples.triples_factory.TriplesFactory, pykeen.triples.triples_numeric_literals_factory.TriplesNumericLiteralsFactory

实用工具

实例创建工具。

compute_compressed_adjacency_list(mapped_triples: Tensor, num_entities: int | None = None) tuple[Tensor, Tensor, Tensor][来源]

计算压缩的无向邻接列表表示,以便进行高效采样。

压缩的邻接表格式受到CSR稀疏矩阵格式的启发。

Parameters:
  • mapped_triples (Tensor) – 基于ID的三元组

  • num_entities (int | None) – 实体的数量。

Returns:

一个元组 (degrees, offsets, compressed_adj_lists) 其中

  • degrees: 形状: (num_entities,)

  • offsets: 形状: (num_entities,)

  • compressed_adj_list: 形状: (2 * num_triples, 2)

其中

adj_list[i] = compressed_adj_list[offsets[i]:offsets[i+1]]

Return type:

tuple[Tensor, Tensor, Tensor]

get_entities(triples: Tensor) set[int][source]

从三元组中获取所有实体。

Parameters:

三元组 (Tensor)

Return type:

set[int]

get_relations(triples: Tensor) set[int][source]

从三元组中获取所有关系。

Parameters:

三元组 (Tensor)

Return type:

set[int]

load_triples(path: str | Path | TextIO, delimiter: str = '\t', encoding: str | None = None, column_remapping: Sequence[int] | None = None) ndarray[source]

加载保存为制表符分隔值的三元组。

Parameters:
  • path (str | Path | TextIO) – 要加载的数据的键。通常,这将是一个以.tsv结尾的文件路径,指向一个包含三列的文件 - 头、关系和尾。这也可以用于调用PyKEEN数据导入器入口点(见下文)。

  • delimiter (str) – 文件中列之间的分隔符

  • encoding (str | None) – 文件的编码。默认为 utf-8。

  • column_remapping (Sequence[int] | None) – 如果三列的顺序不是头-关系-尾,则进行重新映射。 例如,如果顺序是头-尾-关系,传递 (0, 2, 1)

Returns:

一个表示“标记”三元组的numpy数组。

Raises:

ValueError – 如果传递了列重映射,但它不是一个长度为3的序列

Return type:

ndarray

除了TSV处理外,PyKEEN没有预装任何导入器。可以在以下位置找到一些:

tensor_to_df(tensor: Tensor, **kwargs: Tensor | ndarray | Sequence) DataFrame[源代码]

获取一个三元组的张量并创建一个带有标签的pandas数据框。

Parameters:
  • tensor (Tensor) – 形状: (n, 3) 三元组,基于ID,格式为 (head_id, relation_id, tail_id)。

  • kwargs (Tensor | ndarray | Sequence) – 任何额外的列。每列需要是形状为 (n,) 的。保留的列名: {“head_id”, “head_label”, “relation_id”, “relation_label”, “tail_id”, “tail_label”}。

Returns:

一个包含n行和3 + len(kwargs)列的数据框。

Raises:

ValueError – 如果保留的列名出现在kwargs中。

Return type:

数据框

三元组工作流程

分割

实现三元组拆分函数。

函数

split(mapped_triples[, ratios, ...])

将三元组分割成干净的组。

normalize_ratios(ratios[, epsilon])

标准化相对大小。

get_absolute_split_sizes(n_total, ratios)

根据给定的相对大小计算分割的绝对大小。

Cleaner()

一种清理方法,用于确保所有实体都包含在第一个分割部分的三元组中。

RandomizedCleaner()

通过随机选择测试三元组并重新计算以最小化移动来清理三元组数组。

DeterministicCleaner()

清理一个三元组数组(测试)相对于另一个(训练)。

Splitter()

一种用于拆分三元组的方法。

CleanupSplitter([cleaner])

清理分割器首先随机分割三元组,然后进行清理。

CoverageSplitter()

这个分割器贪婪地选择训练三元组,以确保每个实体都被覆盖,然后分割其余部分。

TripleCoverageError(arr[, name])

当并非所有实体/关系都被三元组覆盖时抛出的异常。

类继承图

Inheritance diagram of pykeen.triples.splitting.Cleaner, pykeen.triples.splitting.RandomizedCleaner, pykeen.triples.splitting.DeterministicCleaner, pykeen.triples.splitting.Splitter, pykeen.triples.splitting.CleanupSplitter, pykeen.triples.splitting.CoverageSplitter, pykeen.triples.splitting.TripleCoverageError

混音

混音和数据集距离工具。

大多数数据集都提供了预定义的分割,但通常不会讨论这种分割是如何创建的。此模块包含用于调查重新混合预分割数据集(如:pykeen.datasets.Nations)效果的实用工具。

此外,它定义了一个度量标准,用于衡量给定数据集的两个分割之间的“距离”。 稍后,这将用于映射景观,并查看数据集的分割距离与其最大性能之间是否存在平滑、连续的关系。

函数

remix(*triples_factories, **kwargs)

混合来自训练、测试和验证集的三元组。

退化

退化算法。

函数

deteriorate(reference, *others, n[, ...])

从参考集中移除n个三元组。

生成

用于生成三元组的实用工具。

函数

generate_triples([num_entities, ...])

在torch张量中生成随机三元组。

generate_triples_factory([num_entities, ...])

生成一个包含随机三元组的三元组工厂。

分析

用于(映射的)三元组的分析工具。

add_entity_labels(*, df: DataFrame, add_labels: bool, label_to_id: Mapping[str, int] | None = None, triples_factory: TriplesFactory | None = None) DataFrame[source]

向数据框添加实体标签。

Parameters:
Return type:

数据框

add_relation_labels(df: DataFrame, *, add_labels: bool, label_to_id: Mapping[str, int] | None = None, triples_factory: TriplesFactory | None = None) DataFrame[源代码]

向数据框添加关系标签。

Parameters:
Return type:

数据框

entity_relation_co_occurrence(mapped_triples: Tensor) DataFrame[来源]

计算实体-关系共现。

Parameters:

mapped_triples (Tensor) – 基于ID的三元组。

Returns:

一个包含列(entity_id | relation_id | type | count)的数据框

Return type:

数据框

get_entity_counts(mapped_triples: Tensor) DataFrame[source]

创建一个实体频率的数据框。

Parameters:

mapped_triples (Tensor) – 形状: (num_triples, 3) 映射的三元组。

Returns:

一个包含列(entity_id | type | count)的数据框

Return type:

数据框

get_relation_counts(mapped_triples: Tensor) DataFrame[来源]

创建一个关系频率的数据框。

Parameters:

mapped_triples (Tensor) – 形状: (num_triples, 3) 映射的三元组。

Returns:

一个包含列(relation_id | count)的数据框

Return type:

数据框

get_relation_functionality(mapped_triples: Collection[tuple[int, int, int]], add_labels: bool = True, label_to_id: Mapping[str, int] | None = None) DataFrame[source]

计算关系功能。

Parameters:
  • mapped_triples (Collection[tuple[int, int, int]]) – 基于ID的三元组。

  • add_labels (bool) – 是否应将标签添加到数据框中?

  • label_to_id (Mapping[str, int] | None) – 标签到索引的映射。

Returns:

一个包含列(功能 | 反功能)的数据框

Return type:

数据框

relation_cardinality_types(mapped_triples: Collection[tuple[int, int, int]], add_labels: bool = True, label_to_id: Mapping[str, int] | None = None) DataFrame[source]

确定关系基数类型。

可能的类型在 relation_cardinality_types 中给出。

注意

在当前实现中,我们根据定义有

\[1 = \sum_{type} conf(relation, type)\]

注意

这些关系类型也在[wang2014]中提到。然而,该论文没有提供任何关于它们定义的详细信息,也没有提供任何代码。因此,它们的确切过程是未知的,可能与这个实现不一致。

Parameters:
  • mapped_triples (Collection[tuple[int, int, int]]) – 基于ID的三元组。

  • add_labels (bool) – 是否添加关系标签(如果可用)。

  • label_to_id (Mapping[str, int] | None) – 标签到索引的映射。

Returns:

一个包含列(relation_id | relation_type)的数据框

Return type:

数据框

relation_injectivity(mapped_triples: Collection[tuple[int, int, int]], add_labels: bool = True, label_to_id: Mapping[str, int] | None = None) DataFrame[source]

计算每个关系的“软”注入性分数。

Parameters:
Returns:

一个数据框,每行代表一个关系,其出现次数以及头/尾单射性分数。

Return type:

数据框

relation_pattern_types(mapped_triples: Collection[tuple[int, int, int]]) DataFrame[source]

基于RotatE的模式对关系进行分类[sun2019]

关系分类基于检查相应的规则是否具有足够的支持和置信度。默认情况下,我们不要求最低支持度,但要求相对较高的置信度。

考虑了以下四种非排他性的关系类别:

  • 对称性

  • 反对称

  • 反转

  • 组成

该方法通常遵循关联规则挖掘的术语。模式表示为

\[X_1 \land \cdot \land X_k \implies Y\]

其中 \(X_i\) 的形式为 \(r_i(h_i, t_i)\),并且一些 \(h_i / t_i\) 可能会在其他原子中重复出现。 模式的支持度是左侧所有变量的不同实例化的数量。 置信度是这些实例化中右侧也为真的比例。

Parameters:

mapped_triples (Collection[tuple[int, int, int]]) – 一组基于ID的三元组。

Returns:

关系分类的数据框

Return type:

数据框