AmpliGraph Documentation

AmpliGraph provides a structured API organized into five main submodules that cover the entire lifecycle of Knowledge Graph Embedding (KGE) models. These submodules allow you to load datasets, train models, evaluate performance, and perform downstream tasks like link prediction or entity discovery.

The core submodules are:

• ampligraph.datasets: Tools for loading benchmark datasets or customized user datasets.
• ampligraph.latent_features: Interfaces for working with latent feature representations.
• ampligraph.evaluation: Metrics and tools for evaluating model performance (e.g., MRR, Hits@N).
• ampligraph.discovery: APIs for discovery-related tasks in knowledge graphs.
• ampligraph.utils: General utility functions for model management, such as saving and reloading trained models.
• ampligraph.pretrained_models: Access to pre-trained model weights and architectures.

The ampligraph.discovery module provides high-level functions for performing discovery tasks on a trained AmpliGraph model. It allows you to extract new information, identify patterns, and query the model for specific types of knowledge.

Key capabilities include:

• Fact Discovery: Finding new potential facts (triples) that the model predicts with high confidence.
• Cluster Identification: Finding groups of entities that are closely related in the embedding space.
• Duplicate Detection: Identifying entities that are likely duplicates based on their embeddings.
• Top-N Querying: Retrieving the top $N$ most likely entities for a specific subject-relation pair.

AmpliGraph is a suite of neural machine learning models for relational learning on knowledge graphs. It is built on TensorFlow 2 and uses Keras-style APIs. The library is organized into several functional modules:

• Datasets: Helper functions for loading knowledge graphs.
• Models: Knowledge graph embedding models. AmpliGraph 2 includes TransE, DistMult, ComplEx, and HolE.
• Evaluation: Metrics and protocols to assess model predictive power.
• Discovery: High-level APIs for discovering new facts, clustering entities, and predicting near duplicates.
• Compat: Provides compatibility for users transitioning from AmpliGraph 1.x to 2.x APIs.

AmpliGraph uses a data pipeline designed to handle datasets that are too large to fit in CPU or GPU memory. The pipeline consists of a data handler that leverages the GraphDataLoader to move data from a source into a specific backend.

To handle massive datasets, you must use a disk-based backend instead of the default in-memory storage. This allows data to be persisted on disk and loaded into memory in manageable chunks during training, preventing RAM overload.

In AmpliGraph 2, Knowledge Graph Embedding (KGE) models are implemented using the ScoringBasedEmbeddingModel class. This class inherits from tf.keras.Model, allowing you to use standard Keras features like initializers (e.g., HeNormal, GlorotNormal), regularizers (L1, L2), optimizers (Adam, AdaGrad), and callbacks (e.g., early stopping).

A model's anatomy consists of several layers and components:

• Embedding Generation Layer: Generates embeddings for entities and relations (currently uses EmbeddingLookupLayer).
• Negatives Generation Layer: Generates synthetic negative triples (e.g., CorruptionGenerationLayerTrain).
• Scoring Layer: Applies a scoring function to a triple to represent its plausibility.
• Loss Function: Optimizes the scores (e.g., PairwiseLoss, NLLLoss).
• Optimizer & Regularizer: Standard Keras-compatible components.

AmpliGraph implements various neural architectures to encode entities and relations into low-dimensional vectors. These models use a scoring function $f_{m}(t)$ to assign a score to a triple $t=(sub, pred, obj)$. The goal is to learn embeddings such that positive statements receive high scores and unlikely statements receive low scores.

Key scoring models available in AmpliGraph include:

• TransE: Relies on distances (e.g., $f_{TransE}=-||\mathbf{e}{sub} + \mathbf{e}{pred} - \mathbf{e}_{obj}||_n$).
• DistMult: A bilinear-diagonal model.
• ComplEx: A bilinear-diagonal model.
• RotatE: Models relations as rotations in complex space.
• HolE: Uses circular correlation.
• ConvE: Uses convolutional layers.

AmpliGraph reports predictive power using filtered metrics. When evaluating models on standard datasets like FB15K-237, WN18RR, or YAGO3-10, the following metrics are used:

• MR: Mean Rank
• MRR: Mean Reciprocal Rank
• Hits@1: Hits at rank 1
• Hits@3: Hits at rank 3
• Hits@10: Hits at rank 10

AmpliGraph is organized into several functional submodules to support the full relational learning workflow:

• Datasets: Helper functions for loading knowledge graph datasets.
• Models: Contains knowledge graph embedding models. Supported models include TransE, DistMult, ComplEx, HolE, and RotatE.
• Evaluation: Provides metrics and evaluation protocols to assess model predictive power.
• Discovery: High-level convenience APIs for tasks like discovering new facts, clustering entities, and predicting near-duplicates.
• Compat: Provides compatibility with AmpliGraph 1.x APIs for users migrating from older versions.

When using a disk-based backend, you must define how data is split into chunks that fit in memory. This process is known as graph partitioning. The pipeline splits nodes into $P$ partitions; during training, the model loads one partition, trains on it, unloads it, and then loads the next.

AmpliGraph provides different partitioning strategies, but for optimal runtime performance, it is recommended to use the BucketGraphPartitioner strategy.

Before starting, ensure you have a Python environment with the ampligraph library installed. You can verify the installation and check the version using the following code:

import numpy as np
import pandas as pd
import ampligraph

print(ampligraph.__version__)