`networkx_temporal.transform`

Transform data between different temporal graph representations.

Summary

`from_events`(events[, directed, multigraph, ...])	Returns `TemporalGraph` from edge-level events.
`from_snapshots`(graphs)	Returns `TemporalGraph` from snapshots.
`from_static`(*graphs)	Returns `TemporalGraph` from a static graph.
`from_unrolled`(UTG[, delta])	Returns `TemporalGraph` from an unrolled graph.
`to_events`(TG[, delta, attr])	Returns a list of edge-level events.
`to_snapshots`(TG[, to, as_view])	Returns a list of snapshots.
`to_static`(TG[, to, directed, multigraph, index])	Returns a static graph object.
`to_unrolled`(TG[, to, delta, edge_couplings, ...])	Returns an unrolled temporal graph.

Functions

from_events(events: list, directed: bool = None, multigraph: bool = None, as_view: bool = True) → TemporalGraph[source]

Returns TemporalGraph from edge-level events. Events are:

3-tuples (\(u, v, t\)), where elements are the source node, target node, and time attribute;
4-tuples (\(u, v, t, \delta\)), where \(\delta\) is either an integer for edge addition (1) or deletion (-1) event, or a float defining the duration of the pairwise interaction (zero for a single snapshot).

See also

The Convert and transform → Graph representations page for details and examples.

Parameters:

events (list) – List of 3-tuple or 4-tuple edge-level events.
directed (bool) – If True, returns as TemporalDiGraph object.
multigraph (bool) – If True (default), returns a MultiGraph.
as_view (bool) – If False, returns copies instead of views of the original graph. Default is True.

Return type:

TemporalGraph

from_snapshots(graphs: dict | list) → TemporalGraph[source]

Returns TemporalGraph from snapshots.

See also

The Convert and transform → Graph representations page for details and examples.

Parameters:: graphs (dict | list) – List or dictionary of NetworkX graphs.
Return type:: TemporalGraph

from_static(*graphs: Graph) → TemporalGraph[source]

Returns TemporalGraph from a static graph.

See also

The Convert and transform → Graph representations page for details and examples.

Parameters:

G – NetworkX graph object.
graphs (Graph)

Return type:

TemporalGraph

from_unrolled(UTG: Graph, delta: int | None = None) → TemporalGraph[source]

Returns TemporalGraph from an unrolled graph.

Unrolled graphs are a static representation of temporal networks, where each node is suffixed with its temporal index (e.g., 'a_0') and inter-slice edges are added to connect copies of the same node at different time steps (e.g., 'a_0' and 'a_1'), resulting in increased order and size.

If delta is set, edges are mapped to their original time steps based on the time step difference between source and target temporal nodes, \((u_{t}, v_{t-\delta})\). If unset, the delta attribute from the unrolled temporal graph is used, or 0 by default.

Example

>>> import networkx_temporal as tx
>>>
>>> TG = tx.from_events([
>>>     ('a', 'b', 0),
>>>     ('c', 'b', 1),
>>>     ('a', 'c', 2),
>>>     ('d', 'c', 2),
>>>     ('d', 'e', 2),
>>>     ('f', 'e', 3),
>>>     ('f', 'a', 3),
>>>     ('f', 'b', 3)
>>> ])
>>>
>>> UTG = TG.to_unrolled()
>>>
>>> node_color = [
>>>     "tab:red" if int(n.split("_")[1]) == TG.index_node(n.split("_")[0])[0] else "#333"
>>>     for n in UTG.nodes()]
>>>
>>> tx.draw(UTG,
>>>         layout=tx.unrolled_layout,
>>>         labels={n: f"{n.split('_')[0]}$_{n.split('_')[1]}$" for n in UTG.nodes()},
>>>         node_color=node_color,
>>>         font_size=10,
>>>         title="Unrolled Temporal Graph",
>>>         connectionstyle="arc3,rad=0.25")

Attention

As a static graph, unrolled graphs do not preserve graph-level temporal attributes.

Parameters:

UTG (Graph) – Unrolled temporal graph.
delta (int | None) – Time step between temporal nodes. Optional.

Return type:

TemporalGraph

to_events(TG: TemporalGraph | Graph, delta: Literal['int', 'float'] | None = None, attr: str | None = None) → list[source]

Returns a list of edge-level events.

3-tuples (\(u, v, t\)), where elements are the source node, target node, and time attribute;
4-tuples (\(u, v, t, \delta\)), where \(\delta\) is either an integer for edge addition (1) or deletion (-1) event, or a float defining the duration of the interaction (zero for a single snapshot).

Attention

As events are edge-based, node isolates without self-loops are not preserved.

Parameters:

TG (TemporalGraph) – Temporal graph object.
delta (Literal['int', 'float'] | None) –
Defines which additional parameter \(\delta\) should be returned.
- If None, returns events as 3-tuples. Default.
- If 'int', returns events as 4-tuples with an additional parameter representing edge addition (1) or deletion (-1) events.
- If 'float', returns events as 4-tuples with an additional parameter representing the duration of the pairwise interaction.
attr (str | None) – Edge attribute to consider when delta is 'float'. If provided, the attribute value is used for delta instead of the time difference between the start and end of the interaction.

Note:

Available both as a function and as a method from TemporalGraph objects.

Return type:

list

to_snapshots(TG: TemporalGraph, to: Literal['dgl', 'dynetx', 'graph_tool', 'igraph', 'networkit', 'numpy', 'scipy', 'snap', 'stellargraph', 'torch_geometric', 'teneto'] | None = None, as_view: bool = True) → list[source]

Returns a list of snapshots. Each snapshot is a view of the original graph, which can be converted to a different format using the to argument, if desired.

Note

Internally, TemporalGraph already stores data as a list of graph views on slice(). This method simply returns the underlying data, unless convert() is called by setting to.

Parameters:

TG (TemporalGraph) – Temporal graph object.
to (str) – Package name or alias to convert the graph object (see convert()). Optional.
as_view (bool) – If False, returns copies instead of views of the original graph. Default is True.

Note:

Available both as a function and as a method from TemporalGraph objects.

Return type:

list

to_static(TG: TemporalGraph | Graph, to: Literal['dgl', 'dynetx', 'graph_tool', 'igraph', 'networkit', 'numpy', 'scipy', 'snap', 'stellargraph', 'torch_geometric', 'teneto'] | None = None, directed: bool | None = None, multigraph: bool | None = None, index: str | None = None) → Graph[source]

Returns a static graph object.

A static graph is a single object that contains all the nodes and edges of the temporal graph. If directed and multigraph are unset, the returned graph type will match that of the temporal graph. Specifying attr allows to store the time of interaction as an edge attribute.

Attention

As each node in a static graph is unique, dynamic node attributes are not preserved.

See also

The to_unrolled() method for a static representation allowing dynamic node attributes.

Parameters:

TG (TemporalGraph) – Temporal graph object.
to (str) – Package name or alias to convert the graph object. Optional.
directed (bool | None) – If True, returns a DiGraph. Optional.
multigraph (bool | None) – If True, returns a MultiGraph. Optional.
index (str | None) – Edge attribute to store snapshot index. Optional.

Note:

Available both as a function and as a method from TemporalGraph objects.

Return type:

Graph

to_unrolled(TG: TemporalGraph, to: Literal['dgl', 'dynetx', 'graph_tool', 'igraph', 'networkit', 'numpy', 'scipy', 'snap', 'stellargraph', 'torch_geometric', 'teneto'] | None = None, delta: int | str | None = 0, edge_couplings: bool = True, node_copies: Literal['all', 'fill', 'persist'] | None = None, node_index: list | None = None) → Graph[source]

Returns an unrolled temporal graph.

An unrolled temporal graph is a single graph containing all nodes and edges in all snapshots, plus time-adjacent node copies and edge couplings which connect these copies.

If delta is set, edges are added between temporal nodes in sequential time steps, \((u_{t}, v_{t+\delta})\), resulting in time series representations [0] of temporal networks.

Parameters:

TG (TemporalGraph) – Temporal graph object.
to (str) – Package name or alias to convert() the graph. Optional.
delta (int | str | None) – Time step between temporal nodes. Accepts an integer or a string with the edge-level attribute key name. Default: 0.
edge_couplings (bool) – Add inter-slice edges among temporal nodes. Default: True.
node_copies (Literal['all', 'fill', 'persist'] | None) –
Control inter-slice couplings among temporal node copies. Optional.
- 'all': add temporal node copies to all snapshots.
- 'persist': add temporal node copies to all future snapshots.
- 'fill': add temporal node copies in between snapshots.
node_index (list | None) – Store node index from static graph as node-level attribute 'node_index'. Optional.

Note:

Available both as a function and as a method from TemporalGraph objects.

Return type:

Graph

networkx_temporal.transform

`networkx_temporal.transform`