temporal-graph

Model graphs that evolve over time, compute on them, and render them as SVG, PNG or animated GIF.

Giuliano Crenna
Facultad de Ciencias Exactas, Ingeniería y Agrimensura, Universidad Nacional de Rosario
giulicrenna@fceia.unr.edu.ar

A temporal graph is a graph whose edges exist only at certain instants. This library stores one snapshot per instant and offers three things on top:

• Visualization. Timeline charts in two modes and animated node-link views, written natively as SVG, PNG and GIF. There is no matplotlib, cairo or Pillow underneath.
• Algorithms. Journeys (time-respecting paths), temporal distance and diameter, connectivity metrics, the temporal Menger theorems, information dissemination, temporal design, periodic availability, random temporal graphs and exact solvers for temporal matching, exploration and TSP.
• Data tools. Graph transformations, per-snapshot analysis, and JSON, CSV and GEXF export.

Every algorithm is checked against the worked examples of the notes Grafos temporales: una introducción desde la perspectiva algorítmica and cross-checked against brute force on random graphs.

Contents

• Install
• Quick start
• Visualization
• Animating the evolution (GIF)
• Algorithms
• Data tools
• Examples
• Behavior notes
• Development
• Author
• Citing
• License

Install

pip install temporal-graph

From source:

pip install -e ".[dev]"

Quick start

from temporal_graph import Edge, TemporalGraph, animate, journeys, render

g = TemporalGraph(nodes=["a", "b", "c", "d"])
g.add_snapshot(0, [Edge("a", "b"), Edge("b", "c"), Edge("c", "d")])
g.add_snapshot(1, [
    Edge("a", "b", directed=True, weight=2.5, color="#d62728"),
    Edge("a", "c", color="#1f77b4"),
])
g.add_snapshot(2, [Edge("a", "c")])

render(g, mode="decisions").savefig("decisions.png")   # or .svg
animate(g).save("evolution.gif")
journeys.earliest_arrival(g, "d")                      # who hears from d, and when

Visualization

Modes

Both modes share one layout: a horizontal lifeline per node, time on the x-axis. Every figure embeds its own legend.

Edge properties

Edge identity is the unordered endpoint pair: Edge("a", "b") and Edge("b", "a") are the same edge. Direction, weight and color may change between snapshots without creating a new edge.

Saving figures

render(graph, mode) returns a Figure:

In Jupyter a Figure displays inline as SVG. render(graph, mode, path) still works and returns the written path.

PNG output uses a built-in anti-aliasing rasterizer and an embedded copy of the DejaVu Sans outlines (see THIRD_PARTY_NOTICES.md). A typical graph renders in a fraction of a second. Very large ones, thousands of pixels per side, take seconds, so lower scale if needed. Colors may be hex, rgb() / rgba() or any CSS color name; an unsupported color raises ValueError when saving PNG.

Animating the evolution (GIF)

animate(graph) builds a node-link view with one frame per timestep and saves it as an animated GIF, also natively:

from temporal_graph import animate

anim = animate(g, frame_duration=800, loop=0)   # ms per frame; 0 = loop forever
anim.save("evolution.gif")                      # scale=1.5 pixels per unit
anim.frames[2].savefig("t2.png")                # every frame is a Figure

In each frame:

A header shows the timestep and a change summary, and a timeline bar at the bottom marks progress. Animation.to_gif_bytes() returns the file contents.

Nodes sit on a fixed circle by default. Pass positions={node: (x, y)} (any unit, y pointing down) to use your own layout, e.g. a hierarchy for a tree. Coordinates are scaled so that the two closest nodes do not overlap. Short labels are drawn inside the nodes and longer ones below.

Algorithms

Timesteps are instants: a snapshot at t lists the edges available at t, and unrecorded instants have no edges. A journey crosses edges at strictly increasing instants (strict=False allows equal instants, for chained instantaneous contacts). Directed edges are one-way.

from temporal_graph import TemporalGraph, connectivity, flows, journeys

g = TemporalGraph.from_time_edges(
    ["u1", "u2", "u3", "u4", "u5"],
    [("u1", "u2", 5), ("u1", "u3", 1), ("u2", "u3", 2), ("u2", "u4", 6),
     ("u2", "u5", 3), ("u3", "u4", 4), ("u4", "u5", 7)],
)
journeys.earliest_arrival(g, "u1", start=0)     # {'u1': 0, 'u3': 1, 'u2': 2, 'u5': 3, 'u4': 4}
journeys.foremost_journey(g, "u1", "u5")        # u1 -1-> u3 -2-> u2 -3-> u5
flows.max_out_disjoint_journeys(g, "u1", "u5")  # 2

The test suite reproduces these results from the notes:

• the journeys of figure 2;
• the static-expansion sizes;
• the Menger examples;
• the table 4 metrics;
• the labelings of section 7;
• the periodic coincidences;
• formulas (5) to (7);
• the exploration times of figure 7.

It also cross-checks against brute force on random graphs: BFS on the static expansion, exhaustive journey enumeration and exhaustive disjoint-journey search.

Data tools

Core API of TemporalGraph:

from temporal_graph import analysis, exporters, utils

utils.snapshot_diff(g, 0, 1)           # (added, removed)
analysis.degree_timeline(g, "a")       # {0: 1, 1: 2, 2: 1}
exporters.to_gexf(g, "graph.gexf")

Examples

Every script in examples/ runs from the repo root and writes its output into output/.

Social network, decisions mode:

Delivery pipeline, connections mode:

Behavior notes

• Self-loops and undeclared nodes are rejected (ValueError).
• Duplicate edges within one snapshot are deduplicated; the first one wins.
• An edge absent from a snapshot is disconnected; it must be declared again to reappear.
• Because edge identity ignores direction, u -> v and v -> u cannot both be present at the same instant.
• When several edges act at the same timestep they are placed in sub-lanes inside that timestep's column.

Development

pip install -e ".[dev]"
ruff check temporal_graph tests
mypy temporal_graph
pytest --cov=temporal_graph

See CONTRIBUTING.md, CHANGELOG.md and PUBLISHING.md.

Author

Giuliano Crenna Facultad de Ciencias Exactas, Ingeniería y Agrimensura Universidad Nacional de Rosario giulicrenna@fceia.unr.edu.ar

Questions, bug reports and contributions are welcome by email or through the repository's issues.

Citing

If you use this library in academic work, please cite it together with the notes its algorithms follow:

@software{crenna_temporal_graph,
  author      = {Crenna, Giuliano},
  title       = {temporal-graph: modelling, computing on and rendering temporal graphs},
  year        = {2026},
  institution = {Facultad de Ciencias Exactas, Ingenier{\'\i}a y Agrimensura, Universidad Nacional de Rosario}
}

@misc{crenna_grafos_temporales,
  author = {Crenna, Giuliano},
  title  = {Grafos temporales: una introducci{\'o}n desde la perspectiva algor{\'\i}tmica},
  year   = {2026},
  month  = oct,
  note   = {Facultad de Ciencias Exactas, Ingenier{\'\i}a y Agrimensura, Universidad Nacional de Rosario}
}

License

MIT, see LICENSE. The embedded DejaVu Sans outlines are under the Bitstream Vera license, see THIRD_PARTY_NOTICES.md.