eduzrh/HyDRA
Public
Star 历史趋势
数据来源: GitHub API · 生成自 Stargazers.cn
README.md

✨ Towards Temporal Knowledge Graph Alignment in the Wild ✨

📰 Introduction | 🏗️ Architecture | ⚙️ Installation | 🚀 Quick Start
📦 Datasets | 📖 Usage | 🔬 Reproducibility | 📜 License | 📬 Contact 📑 Citation

📰 Latest News

🆕 Updates📅 Date📝 Description
🎉 Code Release-HyDRA codebase and datasets now available

Before running: After cloning, unzip the bundled archives in the repo root and under data/ (at minimum encoding_and_integration.zip; optionally Preprocess.zip for large-scale experiments).

📰 Introduction

Temporal Knowledge Graph Alignment in the Wild (TKGA-Wild) addresses a critical challenge in temporal knowledge graph integration. To the best of our knowledge, this is the first work to formally formulate and solve this problem, which we term TKGA-Wild. This task presents unique challenges due to Multi-Scale Temporal Elements (i.e., multi-granular temporal coexistence and temporal span disparity) and Asymmetric Temporal Structures (i.e., heterogeneous temporal structures and temporal structural incompleteness) that are common in real-world scenarios.

We have officially introduced complete and high-quality TKGA-Wild benchmarks and proposed HyDRA, a new paradigm based on multi-scale hypergraph retrieval-augmented generation to systematically address the unique challenges of TKGA-Wild. HyDRA effectively captures complex structural dependencies, models multi-granular temporal features, mitigates temporal disparities, and introduces a new scale-weave synergy mechanism to coordinate information across different temporal scales.

🔥 Key Features

FeatureIconDescription
Multi-Granularity Temporal Encoding🔄Captures temporal information at different scales (year, month, day)
Scale-Adaptive Entity Projection📐Adaptive entity projection across different graph scales and dimensions
Multi-Scale Hypergraph Retrieval🔍Efficient neural retrieval for hypergraph-based search
Scale-Weave Synergy🔗Coordinates information across different temporal scales
State-of-the-Art Performance📈Consistently outperforming 28 competitive baselines, achieving up to 43.3% improvement in Hits@1

🏗️ Architecture

HyDRA adopts a multi-scale hypergraph retrieval-augmented generation paradigm, comprising several key stages:

Stage 1: Encoding and Integration 🔄

Stage 2: Scale-Adaptive Entity Projection 📐

Stage 3: Multi-Scale Hypergraph Retrieval 🔍

Stage 4: Multi-Scale Fusion 🔗

📖 For detailed architecture descriptions and theoretical foundations, refer to the accompanying paper.

⚙️ Installation

📋 Prerequisites

First, install dependencies:


pip install -r requirements.txt

📦 Main Dependencies

PackageVersionPurpose
🐍 Python>= 3.7Core language (tested on 3.8.10)
🔥 PyTorch>= 1.10.0Deep learning framework
🔍 Faiss>= 1.7.0Efficient similarity search (CPU/GPU)
📊 NumPy>= 1.21.0Numerical computing
🐼 Pandas>= 1.3.0Data manipulation
⏳ Tqdm>= 4.62.0Progress bars
🌐 NetworkX>= 2.6.0Graph analysis

💡 Note: For GPU-accelerated FAISS, use faiss-gpu instead of faiss-cpu.

📦 Datasets

For our newly proposed TKGA-Wild scenario, we introduce two novel benchmark datasets: BETA and WildBETA.

DatasetDescriptionFact Size
BETABenchmark dataset for TKGA-Wild362K+
WildBETAExtended benchmark dataset for TKGA-Wild563K+

🔗 Download Links

Baidu Netdisk Google Drive

🔐 Baidu Netdisk: Extraction Code: pnax | Password: tkgawild

Dataset Format:

Take the dataset icews_wiki as an example, the folder data/icews_wiki/ should contain:

  • ent_ids_1: Entity IDs in source KG
  • ent_ids_2: Entity IDs in target KG
  • triples_1: Relation triples encoded by IDs in source KG
  • triples_2: Relation triples encoded by IDs in target KG
  • rel_ids_1: Relation IDs in the source KG
  • rel_ids_2: Relation IDs in the target KG
  • time_id: Time IDs in the source KG and the target KG
  • ref_ent_ids: All aligned entity pairs, list of pairs like (e_s \t e_t)

Note: The representative datasets used in experiments are derived from Dual-AMN, JAPE, GCN-Align, BETA, DAEA, AGROLD, DOREMUS, TimeD1M/EN-FR, TimeD1M/EN-DE, Time-FB2M, DBP1M/EN-FR, DBP1M/EN-DE, FBDBP2M and related works.

Large-Scale Preprocessing

For large-scale preprocessing details, see Preprocess/README.md.

🚀 Quick Start

Step 1: Clone the Repository 📥


git clone https://github.com/eduzrh/HyDRA.git

cd HyDRA

Step 2: Prepare Datasets 📦

Download and extract datasets to ./data/

Step 3: Run the Main Experiment ▶️


python HyDRA_main.py --data_dir data/WildBETA

Step 4: View Results 📊

MetricDescription
Hits@1Proportion of correct alignments ranked first
Hits@10Proportion in top-10 candidates
MRRMean Reciprocal Rank

📖 Usage

Basic Usage

Run complete pipeline:


python HyDRA_main.py --data_dir data/WildBETA

Advanced Options

Configure training parameters:


python HyDRA_main.py --data_dir data/WildBETA \

    --cuda 0 \

    --epochs 1500 \

    --max_iterations 5 \

    --min_kg1_entities 100

Parameter Descriptions:

ParameterTypeDefaultDescription
--data_dirstrRequiredPath to dataset directory
--cudaint0CUDA device ID for training
--epochsint500Number of training epochs for encoding stage
--max_iterationsint3Maximum pipeline iterations
--min_kg1_entitiesint50Minimum entities threshold for stopping
--add_noiseflagoffSec. 5.6: mask name-embedding dims in Stage 1 (Simple-HHEA)
--noise_ratiofloat0.0Fraction of 64-d name-embedding dims to zero when --add_noise is set (0.0–1.0)

Multi-Granularity Time Modeling

HyDRA supports multi-granularity temporal modeling (year and month levels) to handle Multi-Granular Temporal Coexistence. Enable it with --multi_granularity_time on HyDRA_main.py (recommended for BETA and WildBETA).

Robustness under Embedding Noise (Sec. 5.6)

Paper Sec. 5.6 injects degradation into entity name embeddings in Stage 1. The full pipeline forwards --add_noise and --noise_ratio to Simple-HHEA (randomly zeroing a fraction of the 64-d name-embedding dimensions):


python HyDRA_main.py --data_dir WildBETA --multi_granularity_time \

    --add_noise --noise_ratio 0.8

Use --noise_ratio from 0.0 to 1.0 (e.g. 0.8 for 80%). Default main results omit noise (do not pass --add_noise).

🔬 Reproducibility

We are committed to ensuring full reproducibility of our results. The following resources are provided:

📋 Experimental Configuration

  • Hyperparameters: All hyperparameter settings are documented in the code and can be configured via command-line arguments
  • Random Seeds: Seed configurations are embedded in the training scripts for reproducibility
  • Environment: Tested on Python 3.8.10 with dependencies as specified in requirements.txt

📊 Reproducing Main Results

To reproduce the main experimental results reported in the paper:

  1. Download datasets following the format described in the Datasets section
  2. Run the complete pipeline with default settings:

python HyDRA_main.py --data_dir data/WildBETA
  1. Evaluate results using the output files in data/icews_wiki/message_pool/

🏗️ Code Organization

The codebase is organized into modular components for clarity:

  • encoding_and_integration/: Multi-granularity temporal entity encoding and integration
  • scale_adaptive_entity_projection/: Relation alignment and entity projection
  • multi_scale_hypergraph_retrieval/: Neural retrieval and hypergraph decomposition
  • multi_scale_fusion/: Multi-scale fusion and alignment refinement
  • HyDRA_main.py: Main pipeline orchestrator

📝 Documentation

  • Comprehensive inline code comments explaining key design decisions
  • Clear module structure with standardized naming conventions
  • This README with step-by-step usage instructions

📊 Evaluation Metrics

We employ standard knowledge graph alignment metrics for transparency and comparability:

  • Hits@1: Proportion of correct alignments ranked first
  • Hits@10: Proportion of correct alignments in top-10 candidates
  • MRR (Mean Reciprocal Rank): Average reciprocal rank of correct alignments

📜 License

MIT License - Copyright notices preserved.

📬 Contact

Responses targeted within 2-3 business days.

📑 Citation

If you find this work helpful for your research or applications, we would appreciate it if you could cite the following paper:

@article{DBLP:journals/corr/abs-2507-14475,
  author       = {Runhao Zhao and
                  Weixin Zeng and
                  Wentao Zhang and
                  Xiang Zhao and
                  Jiuyang Tang and
                  Lei Chen},
  title        = {Towards Temporal Knowledge Graph Alignment in the Wild},
  journal      = {CoRR},
  volume       = {abs/2507.14475},
  year         = {2025},
  url          = {https://doi.org/10.48550/arXiv.2507.14475},
  doi          = {10.48550/ARXIV.2507.14475},
  eprinttype   = {arXiv},
  eprint       = {2507.14475}
}

🔗 References

🙏 Acknowledgement

The following open source projects were partially referenced in this work. We sincerely appreciate their contributions:

Dual-AMN, JAPE, GCN-Align, Simple-HHEA, BETA, Dual-Match, Faiss, NetworkX, AdaCoAgentEA, DAEA, AGROLD, DOREMUS, LargeTKGA Datasets, LargeKGA Datasets,ELsEA

This repository corresponds to the paper Towards Temporal Knowledge Graph Alignment in the Wild (under review at IEEE TPAMI), and is an extension of our previous work BETA.

关于 About

No description, website, or topics provided.

语言 Languages

Python100.0%

提交活跃度 Commit Activity

代码提交热力图
过去 52 周的开发活跃度
75
Total Commits
峰值: 39次/周
Less
More

核心贡献者 Contributors