PometryDocs
GitHub

History and Intervals

Every node and edge in Raphtory tracks its update history. The History object provides access to when updates occurred, and each entry is an EventTime that combines a timestamp with an event ID.

Accessing history

Nodes and edges have a .history property that returns their update history:

earliest_time and latest_time return an OptionalEventTime rather than EventTime | None. This means you can safely chain .dt or .t without checking for None first — if there's no history, these properties simply return None instead of raising an error.

EventTime

Each entry in a History is an EventTime object. This combines a timestamp with an event ID to provide a unique, ordered timepoint.

The event ID is used to order events that share the same timestamp. This is useful for data like blockchain transactions where multiple events occur in the same block but have a defined order:

EventTime has the following properties:

  • .t: Timestamp in milliseconds since epoch
  • .dt: UTC datetime representation
  • .event_id: Event ID for sub-timestamp ordering
  • .as_tuple: Returns (timestamp, event_id) tuple

History formats

The History object provides several ways to access the time data. Each returns its own distinct object type — this allows Raphtory to perform conversions and filtering internally (in Rust) without having to materialize the full data in Python:

Each returns an iterable that you can .collect() into an array. For integer-based data (.t, .event_id, .intervals), collect returns a NumPy array for efficient numerical operations. For .dt, it returns a Python list of datetime objects. Use .to_list() if you need a regular Python list.

History operations

The History object supports several operations for working with temporal data:

  • collect() / collect_rev(): Materialize the history into a list of EventTime entries, either in chronological or reverse order.
  • earliest_time() / latest_time(): Get the time bounds of the history without collecting all entries.
  • is_empty(): Check if the history has any entries — useful for validation before processing.
  • reverse(): Return a view that iterates in reverse order, enabling you to process recent events first without materializing the full history.
  • merge(): Combine two histories into a single interleaved timeline — useful for analyzing co-activity patterns.
  • compose_histories(): Combine multiple histories at once (more than two) — ideal for aggregating activity across many entities.

Intervals

The Intervals object (returned by history.intervals) provides analytical functions for working with time gaps between events:

Statistical functions:

  • min(): Find the shortest gap between consecutive events — useful for detecting bursts of rapid activity.
  • max(): Find the longest gap — helps identify dormant periods or unusual pauses.
  • mean(): Calculate the average interval — gives a sense of typical activity frequency.
  • median(): Get the middle interval value — more robust than mean when there are outliers.

Collection functions: