Classes

Overview of the core package classes.

Summary

ASH

NProfile

A profile holding attributes and computed statistics for a node.

PresenceStore

Minimal dict‑like interface required by ASH.

DensePresenceStore

Keep the original dense mapping time → set[id] intact.

IntervalPresenceStore

Sparse interval representation.

Details

Note

The ASH class acts as the core data structure for representing temporal hypergraphs. It encapsulates nodes, hyperedges, attributes and their temporal dynamics, providing methods for manipulation and analysis.

Note

The NProfile class is designed to manage all attributes related to a node within the ASH framework. It supports various data types and provides functionality for adding, updating, and querying node attributes over time.

Note

The PresenceStore class and its subclasses (DensePresenceStore, IntervalPresenceStore) are specialized data structures for efficiently storing and querying the temporal presence of hyperedges within the ASH model. They support different storage strategies to optimize for various use cases and performance requirements.

Backend Selection

ASH supports two backend implementations for managing temporal presence:

Dense Backend (default)

  • Storage: Direct mapping time → set(hyperedge_ids)

  • Best for: Dense timelines, frequent snapshot queries, shorter time spans

  • Complexity: O(1) snapshot access, O(1) per-time updates

  • Memory: Proportional to number of distinct time points

Interval Backend

  • Storage: Sparse representation hyperedge_id → list[(start, end)] with optimized event-diff indexing

  • Best for: Long sparse intervals, bulk interval operations, memory-constrained environments

  • Complexity: O(log k) snapshot materialization via bisect (k = intervals per id), O(1) interval add/remove

  • Memory: Proportional to number of intervals (typically much smaller for sparse data)

Usage example:

# Default dense backend
H = ASH()

# Interval backend for sparse temporal data
H_sparse = ASH(backend="interval")

# Both backends provide identical API
H.add_hyperedge([1, 2, 3], start=0, end=100)
H_sparse.add_hyperedge([1, 2, 3], start=0, end=100)

Technical Note

The IntervalPresenceStore implements two key optimizations:

  1. Binary search for presence queries: Maintains a parallel starts list for each hyperedge’s intervals, enabling O(log k) lookup instead of O(k) linear scan.

  2. Event-diff for interval updates: Uses a difference array (_time_events) to represent interval boundaries. Adding/removing an interval requires only O(1) event updates instead of O(length) per-time operations. The full time→count mapping is rebuilt lazily when keys() is called.

These optimizations make the interval backend practical for large-scale temporal networks with long, sparse activity patterns.