semantica/cookbook/advanced/10_Temporal_Knowledge_Graphs.ipynb

Temporal Knowledge Graphs

Overview

This notebook demonstrates advanced temporal knowledge graph capabilities using TemporalGraphQuery, TemporalPatternDetector, TemporalVersionManager, and TemporalVisualizer.

Documentation: API Reference

Learning Objectives

• Use TemporalGraphQuery for time-aware queries
• Use TemporalPatternDetector to detect temporal patterns
• Use TemporalVersionManager for temporal versioning and snapshots
• Use TemporalVisualizer to visualize temporal data

Installation

Install Semantica from PyPI:

pip install semantica
# Or with all optional dependencies:
pip install semantica[all]

---

Workflow: Build Temporal KG → Time-Aware Queries → Pattern Detection → Version Management → Visualization

In [ ]:

from semantica.kg import GraphBuilder, TemporalGraphQuery, TemporalPatternDetector, TemporalVersionManager
from semantica.visualization import TemporalVisualizer
from datetime import datetime

builder = GraphBuilder()

entities = [
    {"id": "e1", "type": "Organization", "name": "Apple Inc.", "properties": {"founded": "1976"}},
    {"id": "e2", "type": "Person", "name": "Steve Jobs", "properties": {"born": "1955"}}
]

relationships = [
    {"source": "e2", "target": "e1", "type": "founded", "properties": {"timestamp": "1976-04-01"}}
]

temporal_kg = builder.build(entities, relationships)

print(f"Built temporal knowledge graph with {len(entities)} entities")

Step 2: Time-Aware Queries

Query the graph at specific time points.

In [ ]:

temporal_query = TemporalGraphQuery()

query_result = temporal_query.query_time_range(
    graph=temporal_kg,
    query="Find entities founded in 1976",
    start_time="1976-01-01",
    end_time="1976-12-31"
)

print(f"Time-aware query returned {len(query_result.get('entities', []))} entities")

Step 3: Temporal Pattern Detection

Detect temporal patterns in the graph.

In [ ]:

pattern_detector = TemporalPatternDetector()

patterns = pattern_detector.detect_temporal_patterns(
    temporal_kg,
    pattern_type="sequence",
    min_frequency=1
)

print(f"Detected {len(patterns)} temporal patterns")

Step 4: Version Management

Manage temporal versions and snapshots.

In [ ]:

version_manager = TemporalVersionManager()

snapshot = version_manager.create_snapshot(temporal_kg, timestamp=datetime.now())

print(f"Created temporal snapshot at {snapshot.get('timestamp', 'N/A')}")
print(f"Snapshot contains {len(snapshot.get('entities', []))} entities")

Step 5: Temporal Visualization

Visualize temporal data.

In [ ]:

temporal_visualizer = TemporalVisualizer()

visualization = temporal_visualizer.visualize_timeline(temporal_kg, output="interactive")

Summary

You've learned advanced temporal knowledge graph capabilities:

• TemporalGraphQuery: Time-aware graph querying
• TemporalPatternDetector: Temporal pattern detection
• TemporalVersionManager: Temporal versioning and snapshots
• TemporalVisualizer: Temporal data visualization

Snapshot Comparison and Version History

Compare graph snapshots across time and visualize version history.

In [ ]:

# Create multiple versions
version_manager = TemporalVersionManager()
version_2020 = version_manager.create_version(temporal_kg, timestamp="2020-01-01", version_label="v2020")
# Simulate changes for 2023
temporal_kg_updated = {
    "entities": temporal_kg.get("entities", []),
    "relationships": temporal_kg.get("relationships", []) + [
        {"source": "e1", "target": "e2", "type": "collaborated_with", "valid_from": "2023-01-01"}
    ]
}
version_2023 = version_manager.create_version(temporal_kg_updated, timestamp="2023-01-01", version_label="v2023")

# Build snapshots dict for comparison
snapshots = {
    version_2020["timestamp"]: version_2020,
    version_2023["timestamp"]: version_2023
}

# Visualize snapshot comparison
fig_snapshots = temporal_visualizer.visualize_snapshot_comparison(snapshots, output="interactive")

# Build version history list
version_history = [
    {"version": version_2020.get("label", "v2020"), "timestamp": version_2020.get("timestamp"), "changes": f"Entities: {len(version_2020.get('entities', []))}, Relationships: {len(version_2020.get('relationships', []))}"},
    {"version": version_2023.get("label", "v2023"), "timestamp": version_2023.get("timestamp"), "changes": f"Entities: {len(version_2023.get('entities', []))}, Relationships: {len(version_2023.get('relationships', []))}"}
]

# Visualize version history
fig_versions = temporal_visualizer.visualize_version_history(version_history, output="interactive")