Dynamic Network Classes

A simple demo of usage can be found here.

Introduction

Dynamic graphs can be represented as:

  • Sequences of snapshots
  • Interval Graphs
  • Link streams

Each representation has strengths and weaknesses. The representation to use depends on

  1. Algorithms we wish to use
  2. Information we need to access to efficiently
  3. Properties of the network to represent.

In summary, the properties of each representation are the following:

Sequences of snapshots

Time is discrete. Interactions are ponctual.

Most appropriate if there are a few timesteps (<50?), or if you need to access efficiently the network at a given time.

Inefficient to access the list of all interactions of a particular node/edge.

Interval Graph

Time is continuous. Interactions have a duration.

Most appropriate when observed relations last a consequent time relatively to the whole period of study, i.e., if the original data is continuous or if it is discrete but an edge observed at time t tends to be also present from t to t+n, with n large.

Efficient to access all the interactions of a node or a pair of nodes, but not to access all interactions at a particular time.

Automatic model selection

As introduced in Data compression to choose a proper dynamic network representation (TBP), the library propose to choose automatically the representation when provided with a file containing interactions as triplets <Time, Node1,Node2>. The method is based on the most efficient data compression. Check the Read/Write section to know more.

Shared methods

All representation share a set of common fonctions to access and modify them. Note that the implementation of those methods vary.

Those methods are:

start() First valid date of the data
end() Last valid date of the data
summary() Print a summary of the graph
add_node_presence(node, time) Add presence of a node
add_nodes_presence_from(nodes, times) Add nodes at times
add_interaction(u, v, time) Add an interaction at a time
add_interactions_from(nodePairs, times) Add interactions at times
remove_node_presence(node, time) Remove a node presence
remove_interaction(u, v, time) Remove an interaction at a time
remove_interactions_from(nodePairs, times) Remove interactions at times
edge_presence([nbunch]) Return presence time of edges
interactions() Return all interactions as a set
change_times() Return all times with interactions/change
graph_at_time(t) Return graph at a time
cumulated_graph([times]) Return the cumulated graph over a period
slice(start, end) Return a slice of the temporal network
aggregate_sliding_window([bin_size, shift, …]) Aggregate using sliding windows
frequency(value) Set and/or return graph frequency
write_interactions(filename) Export custom format with only interactions

Sequences of snapshots

class tnetwork.DynGraphSN(data=None, frequency=1)[source]

A class to represent dynamic graphs as snapshot sequence.

Each snapshot is represented as a networkx graph, and is associated to a time step identifier. The time step can be an position in the sequence (1,2,3,…) or an arbitrary temporal indicator (year, timestamp…).

Snpashots are ordered according to their time step identifier using a sorted dictionary (SortedDict).

Adding and removing nodes and edges

DynGraphSN.__init__([data, frequency]) Instanciate a new graph, with or without initial data
DynGraphSN.add_node_presence(n, time) Add presence for a node at a time
DynGraphSN.add_nodes_presence_from(nodes, times) Add nodes for times
DynGraphSN.add_interaction(u, v, time) Add a single interaction at a single time step.
DynGraphSN.add_interactions_from(nodePairs, …) Add interactions between the provided node pairs for the provided times.
DynGraphSN.remove_node_presence(n, time) Remove presence for a node at a time
DynGraphSN.remove_interaction(u, v, time) Remove a single interaction at a single time step.
DynGraphSN.remove_interactions_from(…) Remove interactions between the provided node pairs for the provided times.
DynGraphSN.add_snapshot([t, graphSN]) Add a snapshot for a time step t
DynGraphSN.remove_snapshot(t) Remove a snapshot
DynGraphSN.discard_empty_snapshots() Discard snapshots with no edges

Accessing the graph

DynGraphSN.summary() Print a summary of the graph
DynGraphSN.snapshots([t]) Return all snapshots or a particular one
DynGraphSN.node_presence([nodes]) Presence time of nodes
DynGraphSN.edge_presence([edges]) Presence time of edges
DynGraphSN.graph_at_time(t) Return the graph as it is at time t
DynGraphSN.snapshots_timesteps() Return the list of time steps
DynGraphSN.last_snapshot() Return the last snapshot
DynGraphSN.start() Time of the first snapshot
DynGraphSN.end() Time of the last snapshot
DynGraphSN.change_times() Times of non-empty snapshots
DynGraphSN.frequency(value) Set and/or return graph frequency

Conversion to different formats

DynGraphSN.to_DynGraphIG() Convert the graph into a DynGraph_IG.
DynGraphSN.to_DynGraphLS() Convert to a linkstream
DynGraphSN.to_tensor([always_all_nodes]) Return a tensor representation

Aggregation

DynGraphSN.cumulated_graph([times]) Compute the cumulated graph.
DynGraphSN.slice(start, end) Keep only the selected period
DynGraphSN.aggregate_sliding_window([…]) Return a new dynamic graph without modifying the original one, aggregated using sliding windows of the desired size.
DynGraphSN.aggregate_time_period(period[, …]) Aggregate graph by time period (day, year, …)

Other graph operations

DynGraphSN.apply_nx_function(function[, …]) Apply a networkx function to each snapshot and return the list of result.
DynGraphSN.code_length([as_matrix, as_edgelist])
DynGraphSN.write_interactions(filename) Write interactions in a file

Interval graphs

class tnetwork.DynGraphIG(edges=None, nodes=None, start=None, end=None, frequency=1)[source]
A class to represent dynamic graphs as interval graphs.

It is represented using a networkx Graph, using an attribute (“t”) for each node and each edge representing its periods of presence. The representation is done using the class Intervals (tnetwork.utils.intervals) Time steps are represented by integers, that can correspond to an arbitrary scale (1,2,3,…) or to timestamps in order to represent dates.

Examples

Adding and removing nodes and edges

DynGraphIG.__init__([edges, nodes, start, …]) Instanciate a dynamic graph
DynGraphIG.add_node_presence(n, time) Add presence for a node for a period
DynGraphIG.add_nodes_presence_from(nodes, times) Add interactions between provided pairs for the provided periods
DynGraphIG.add_interaction(u, v, time) Add an interaction between nodes u and v at time time
DynGraphIG.add_interactions_from(nodePairs, …) Add interactions between provided pairs for the provided periods
DynGraphIG.remove_node_presence(node, time) Remove node and its interactions over the period
DynGraphIG.remove_interaction(u, v, time) Remove an interaction between nodes u and v at time time
DynGraphIG.remove_interactions_from(…) Remove interactions between provided pairs for the provided periods

Accessing the graph

DynGraphIG.summary() Print a summary of the graph
DynGraphIG.node_presence([nodes]) Presence period of nodes
DynGraphIG.edge_presence([edges, as_intervals]) Return the periods of interactions for each pair of nodes with at least an interaction
DynGraphIG.graph_at_time(t) Graph as it is at time t
DynGraphIG.interactions() Return all interactions as a set
DynGraphIG.interactions_intervals([edges]) Return the periods of interactions for each pair of nodes with at least an interaction
DynGraphIG.change_times() List of all times with a node/edge change
DynGraphIG.start() First valid date of the data
DynGraphIG.end() Last valid date of the data

Conversion to different formats

DynGraphIG.to_DynGraphSN([slices, discard_empty]) Convert to a snapshot representation.

Aggregation

DynGraphIG.cumulated_graph([times]) Compute the cumulated graph.
DynGraphIG.slice(start, end) Keep only the selected period
DynGraphIG.code_length()
DynGraphIG.write_interactions(filename) Write a file with interactions

Link Streams

class tnetwork.DynGraphLS(edges=None, nodes=None, frequency=1, start=None, end=None)[source]
A class to represent dynamic graphs as link streams.

It is represented using a networkx Graph, using an attribute (“t”) for each node and each edge representing its time of presence. The representation is done using a list of integer.

Adding and removing nodes and edges

DynGraphLS.__init__([edges, nodes, …]) Instanciate a dynamic graph
DynGraphLS.start() First valid date of the data
DynGraphLS.end() Last valid date of the data
DynGraphLS.add_interaction(u, v, time) Add an interaction between nodes u and v at time time
DynGraphLS.add_interactions_from(nodePairs, …) Add interactions between the provided node pairs for the provided times.
DynGraphLS.add_node_presence(n, time) Add presence for a node for a period
DynGraphLS.add_nodes_presence_from(nodes, times) Add interactions between provided pairs for the provided periods
DynGraphLS.remove_node_presence(node, time) Remove node and its interactions over the period
DynGraphLS.remove_interaction(u, v, time) Remove an interaction between nodes u and v at time time
DynGraphLS.remove_interactions_from(…) Remove interactions between provided pairs for the provided periods

Accessing the graph

DynGraphLS.summary() Print a summary of the graph
DynGraphLS.interactions() Return all interactions as a set
DynGraphLS.node_presence([nodes]) Presence period of nodes
DynGraphLS.edge_presence([edges]) Return the periods of interactions for each pair of nodes with at least an interaction
DynGraphLS.graph_at_time(t) Graph as it is at time t
DynGraphLS.change_times() List of all times with a node/edge change

Conversion to different formats

DynGraphLS.to_DynGraphSN([slices, weighted]) Convert to a snapshot representation.

Aggregation

DynGraphLS.cumulated_graph([times, weighted]) Compute the cumulated graph.
DynGraphLS.slice(start, end) Keep only the selected period
DynGraphLS.aggregate_sliding_window([…]) Return a new dynamic graph without modifying the original one, aggregated using sliding windows of the desired size.

Other

DynGraphLS.code_length()
DynGraphLS.write_interactions(filename)
param filename: