LifeCycle Object

The LifeCycle object is a class that represents the life cycle of temporal communities extracted from a dynamic network. It is used to store the information about the in/out flows of nodes between communities and the from/to events they generate.

class cdlib.LifeCycle(clustering: TemporalClustering | None = None)

Class representing the lifecycle of a temporal clustering. It allows to compute the events composing the lifecycle (leveraging different definitions) and to analyze them starting from a TemporalClustering object.

analyze_flow(com_id: str, direction: str = '+', min_branch_size: int = 1, attr=None) → dict

Analyze the flow of a community

Parameters:

• com_id – the community id

• direction – the temporal direction in which the flow is to be analyzed. Options are “+” and “-“.

• min_branch_size – the minimum branch size

• attr – the attribute to analyze

Returns:

the analyzed flow

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> from networkx.generators.community import LFR_benchmark_graph
>>> tc = TemporalClustering()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     coms = algorithms.louvain(g)  # here any CDlib algorithm can be applied
>>>     tc.add_clustering(coms, t)
>>> events = LifeCycle(tc)
>>> events.compute_events("facets")

analyze_flows(direction: str = '+', min_branch_size: int = 1, attr=None) → dict

Analyze the flows of the lifecycle

Parameters:

• direction – the temporal direction in which the flows are to be analyzed. Options are “+” and “-“.

• min_branch_size – the minimum branch size

• attr – the attribute to analyze

Returns:

the analyzed flows

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> from networkx.generators.community import LFR_benchmark_graph
>>> tc = TemporalClustering()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     coms = algorithms.louvain(g)  # here any CDlib algorithm can be applied
>>>     tc.add_clustering(coms, t)
>>> events = LifeCycle(tc)
>>> events.compute_events("facets")
>>> c = events.analyze_flows("+")

compute_events(matching_type: str = 'facets', matching_params: dict = {'min_branch_size': 1, 'threshold': 0.5})

Compute the events of the lifecycle

Parameters:

• matching_type – the type of matching algorithm to use. Options are “facets”, “asur”, “greene”.

• matching_params – the parameters of the matching algorithm. Defaults to {“min_branch_size”: 1, “threshold”: 0.5}. The former parameter is required for “facets”, the latter by “asur” and “greene”.

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> from networkx.generators.community import LFR_benchmark_graph
>>> tc = TemporalClustering()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     coms = algorithms.louvain(g)  # here any CDlib algorithm can be applied
>>>     tc.add_clustering(coms, t)
>>> events = LifeCycle(tc)
>>> events.compute_events("facets")

compute_events_from_explicit_matching()

Compute the events of the lifecycle using the explicit matching (if available)

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> from networkx.generators.community import LFR_benchmark_graph
>>> from dynetx import DynGraph
>>> dg = DynGraph()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     dg.add_interactions_from(g, t)
>>> tc = algorithms.tiles(dg, 10)
>>> events = LifeCycle(tc)
>>> events.compute_events_from_explicit_matching()

compute_events_with_custom_matching(method: Callable[[set, set], float], two_sided: bool = True, threshold: float = 0.2)

Compute the events of the lifecycle using a custom matching similarity function

Parameters:

• method – a set similarity function with co-domain in [0,1] (e.g., Jaccard)

• two_sided – boolean. Whether the match has to be applied only from the past to the future (False) or even from the future to the past (True, default)

• threshold – the threshold above which two communities are considered matched

Example:

>>> from cdlib import algorithms
>>> from cdlib import TemporalClustering, LifeCycle
>>>  tc = TemporalClustering()
>>> # build the temporal clustering object
>>> evts = LifeCycle(tc)
>>> jaccard = lambda x, y: len(set(x) & set(y)) / len(set(x) | set(y))
>>> evts.compute_events_with_custom_matching(jaccard, two_sided=True, threshold=0.2)

get_attribute(name: str) → dict

Get the attributes associated to the nodes

Parameters:

name – the name of the attribute

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> import random
>>> from networkx.generators.community import LFR_benchmark_graph
>>>
>>> def random_attributes():
>>>     attrs = {}
>>>     for i in range(250):
>>>        attrs[i] = {}
>>>        for t in range(10):
>>>             attrs[i][t] = random.choice(["A", "B", "C", "D", "E"])
>>>     return attrs
>>>
>>> tc = TemporalClustering()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     coms = algorithms.louvain(g)  # here any CDlib algorithm can be applied
>>>     tc.add_clustering(coms, t)
>>> events = LifeCycle(tc)
>>> events.compute_events("facets")
>>> events.set_attribute(random_attributes(), "fakeattribute")
>>> attrs = events.get_attribute("fakeattribute")

get_event(com_id: str) → CommunityEvent

Get the events associated to a community

Parameters:

com_id – the community id

Returns:

the events associated to the community

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> from networkx.generators.community import LFR_benchmark_graph
>>> tc = TemporalClustering()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     coms = algorithms.louvain(g)  # here any CDlib algorithm can be applied
>>>     tc.add_clustering(coms, t)
>>> events = LifeCycle(tc)
>>> events.compute_events("facets")
>>> evt = events.get_event("0_2")

get_event_types() → list

Get the event types

Returns:

the event types

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> from networkx.generators.community import LFR_benchmark_graph
>>> tc = TemporalClustering()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     coms = algorithms.louvain(g)  # here any CDlib algorithm can be applied
>>>     tc.add_clustering(coms, t)
>>> events = LifeCycle(tc)
>>> events.compute_events("facets")
>>> evts = events.get_event_types()

get_events() → dict

Get all the events

Returns:

the events

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> from networkx.generators.community import LFR_benchmark_graph
>>> tc = TemporalClustering()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     coms = algorithms.louvain(g)  # here any CDlib algorithm can be applied
>>>     tc.add_clustering(coms, t)
>>> events = LifeCycle(tc)
>>> events.compute_events("facets")
>>> evts = events.get_events()

polytree() → DiGraph

Reconstruct the poly-tree representing communities lifecycles using a provided similarity function.

Returns:

a networkx DiGraph object. Nodes represent communities, their ids are assigned following the pattern {tid}_{cid}, where tid is the time of observation and cid is the position of the community within the Clustering object.

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> from networkx.generators.community import LFR_benchmark_graph
>>> tc = TemporalClustering()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     coms = algorithms.louvain(g)  # here any CDlib algorithm can be applied
>>>     tc.add_clustering(coms, t)
>>> events = LifeCycle(tc)
>>> events.compute_events("facets")
>>> g = events.polytree()

set_attribute(attr: dict, name: str)

Set the attributes of the lifecycle

Parameters:

• attr – the attributes

• name – the name of the attribute

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> import random
>>> from networkx.generators.community import LFR_benchmark_graph
>>>
>>> def random_attributes():
>>>     attrs = {}
>>>     for i in range(250):
>>>        attrs[i] = {}
>>>        for t in range(10):
>>>             attrs[i][t] = random.choice(["A", "B", "C", "D", "E"])
>>>     return attrs
>>>
>>> tc = TemporalClustering()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     coms = algorithms.louvain(g)  # here any CDlib algorithm can be applied
>>>     tc.add_clustering(coms, t)
>>> events = LifeCycle(tc)
>>> events.compute_events("facets")
>>> events.set_attribute(random_attributes(), "fakeattribute")

to_json() → dict

Convert the lifecycle to json

Returns:

the lifecycle as json

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> from networkx.generators.community import LFR_benchmark_graph
>>> tc = TemporalClustering()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     coms = algorithms.louvain(g)  # here any CDlib algorithm can be applied
>>>     tc.add_clustering(coms, t)
>>> events = LifeCycle(tc)
>>> events.compute_events("facets")
>>> events.to_json()

validate_all_flows(direction: str, min_branch_size=1, iterations=1000) → dict

Compare all flows with null models. See validate_flow for details.

Parameters:

• direction – temporal direction, either “+” (out flow) or “-” (in flow)

• min_branch_size – minimum size of a branch to be considered

• iterations – number of random draws to be used to generate the null model

Returns:

a dictionary keyed by set identifier and valued by mean, std, and p-value

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> from networkx.generators.community import LFR_benchmark_graph
>>> tc = TemporalClustering()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     coms = algorithms.louvain(g)  # here any CDlib algorithm can be applied
>>>     tc.add_clustering(coms, t)
>>> events = LifeCycle(tc)
>>> events.compute_events("facets")
>>> vf = events.validate_all_flows("+")

validate_flow(target: str, direction: str, min_branch_size: int = 1, iterations: int = 1000) → dict

Compare the flow with a null model. Each branch of each flow is compared with a null branch of the same size. The null model is generated by randomly sampling elements from the reference partition iterations times. The mean and standard deviation of the null model are used to compute a z-score for each branch, which is then used to compute a p-value.

Parameters:

• target – target set identifier

• direction – temporal direction, either “+” (out flow) or “-” (in flow)

• min_branch_size – minimum size of a branch to be considered

• iterations – number of random draws to be used to generate the null model

Returns:

Example:

>>> from cdlib import TemporalClustering, LifeCycle
>>> from cdlib import algorithms
>>> from networkx.generators.community import LFR_benchmark_graph
>>> tc = TemporalClustering()
>>> for t in range(0, 10):
>>>     g = LFR_benchmark_graph(
>>>         n=250,
>>>         tau1=3,
>>>         tau2=1.5,
>>>         mu=0.1,
>>>         average_degree=5,
>>>         min_community=20,
>>>         seed=10,
>>>     )
>>>     coms = algorithms.louvain(g)  # here any CDlib algorithm can be applied
>>>     tc.add_clustering(coms, t)
>>> events = LifeCycle(tc)
>>> events.compute_events("facets")
>>> cf = events.validate_flow("0_2", "+")