LifeCycle¶

The LifeCycle class is the primary object for representing and analyzing time-aware clusters. Here is a brief overview of the methods available for LifeCycle objects, structured in thematic groups.

Partition-based Methods¶

These methods are used to store and access temporally ordered partitions of the data.

`LifeCycle.add_partition`	add a partition to the LifeCycle.
`LifeCycle.add_partitions_from`	add multiple partitions to the LifeCycle.
`LifeCycle.get_partition_at`	retrieve a partition by id

Group-based Methods¶

These methods are used to retrieve, filter, and analyze the individual clusters in the data.

`LifeCycle.get_group`	retrieve a group by id
`LifeCycle.group_iterator`	returns an iterator over the groups of the LifeCycle.
`LifeCycle.filter_on_group_size`	remove groups that do not meet the size criteria
`LifeCycle.group_flow`	compute the flow of a group w.r.t.
`LifeCycle.all_flows`	compute the flow of all groups w.r.t.

Element-based Methods¶

These methods are used to retrieve the membership of individual items in the data (i.e., the groups they belong to).

`LifeCycle.get_element_membership`	retrieve the list of groups that contain a given element
`LifeCycle.get_all_element_memberships`	retrieve the list of groups that contain each element in the LifeCycle

Attribute-based Methods¶

These methods are used to store and access time-changing metadata assigned to the individual clusters.

`LifeCycle.set_attributes`	set the temporal attributes of the elements in the LifeCycle
`LifeCycle.get_attributes`	retrieve the temporal attributes of the LifeCycle

Other Convenience Methods¶

These methods are used to retrieve fundamental information about the data such as the universe set, and the list of time instants.

`LifeCycle.groups_ids`	retrieve the group ids of the lifecycle.
`LifeCycle.temporal_ids`	retrieve the temporal ids of the LifeCycle.
`LifeCycle.universe_set`	retrieve the universe set.
`LifeCycle.slice`	slice the LifeCycle to keep only a given interval

IO Methods¶

These methods are used to read and write LifeCycle objects to and from disk.

`LifeCycle.to_dict`	convert the LifeCycle to a dictionary
`LifeCycle.write_json`	save the LifeCycle to a json file
`LifeCycle.read_json`	load the LifeCycle from a json file.

Complete LifeCycle API¶

Note

Object methods and functions are reported in alphabetical order.

class LifeCycle(dtype: type = <class 'int'>)¶

Bases: object

A class to represent and analyze temporally-evolving groups.

Parameters:: dtype – the datatype of the elements in the groups.

Supported types are int, float, str, list, and dict.

Returns:: a LifeCycle object
Example:

>>> lc = LifeCycle(dtype=int) # accepts int elements
>>> lc = LifeCycle(dtype=str) # accepts str elements

add_partition(partition: list) → None¶

add a partition to the LifeCycle. A partition is a list of groups observed at a given time instant. Each partition will be assigned a unique id (tid) corresponding to the observation time, and each group in the partition will be assigned a unique name

Parameters:: partition – a collection of groups
Returns:: None
Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([{5,7}, {6,8}])

add_partitions_from(partitions: list) → None¶

add multiple partitions to the LifeCycle.

Parameters:: partitions – a list of partitions
Returns:: None
Example:

>>> lc = LifeCycle()
>>> partitions = [
>>>     [[1,2], [3,4,5]],
>>>     [{5,7}, {6,8}]
>>> ]
>>> lc.add_partitions_from(partitions)

all_flows(direction: str, min_branch_size: int = 1) → dict¶

compute the flow of all groups w.r.t. a given temporal direction

Parameters:

direction – the temporal direction in which the groups are to be analyzed
min_branch_size – the minimum size of a branch to be considered

Returns:

a dictionary keyed by group name and valued by the flow of the group

Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([[1,2,3], [4,5]])
>>> lc.all_flows("+")
>>> # {'0_0': {'1_0': {1, 2}}, '0_1': {'1_0': {3}, '1_1': {4, 5}}}

filter_on_group_size(min_size: int = 1, max_size: int | None = None) → None¶

remove groups that do not meet the size criteria

Parameters:

min_size – the minimum size of the groups to keep
max_size – the maximum size of the groups to keep

Returns:

None

Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([[1,2,3], [4,5]])
>>> lc.filter_on_group_size(min_size=3) # remove groups with less than 3 elements
>>> lc.groups_ids() # only groups 1_0 and 1_1 remain
>>> # ['0_1', '1_0']

get_all_element_memberships() → dict¶

retrieve the list of groups that contain each element in the LifeCycle

Returns:: a dictionary keyed by element and valued by a list of group names that contain the element
Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([[1,2,3], [4,5]])
>>> lc.get_all_element_memberships()

get_attributes(attr_name, of=None) → dict¶

retrieve the temporal attributes of the LifeCycle

Parameters:

attr_name – the name of the attribute
of – the element for which to retrieve the attributes. If None, all attributes are returned

Returns:

a dictionary keyed by element id and valued by a dictionary keyed by temporal id and valued by the attribute value

Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([[1,2,3], [4,5]])
>>> attributes = {
>>>     1: {0: 'red', 1: 'blue'}, # element 1 is red at time 0 and blue at time 1
>>>     2: {0: 'green', 1: 'magenta'} # element 2 is green at time 0 and magenta at time 1
>>> }
>>> lc.set_attributes(attributes, attr_name="color")
>>> lc.get_attributes("color")
>>> # {1: {0: 'red', 1: 'blue'}, 2: {0: 'green', 1: 'magenta'}}
>>> lc.get_attributes("color", of=1) # get the attributes of element 1
>>> # {0: 'red', 1: 'blue'}

get_element_membership(element: object) → list¶

retrieve the list of groups that contain a given element

Parameters:: element – the element for which to retrieve the memberships
Returns:: a list of group names that contain the given element
Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([[1,2,3], [4,5]])
>>> lc.get_element_membership(1)
>>> # ['0_0', '1_0']

get_group(gid: str) → set¶

retrieve a group by id

Parameters:: gid – the name of the group to retrieve
Returns:: the group corresponding to the given name
Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.get_group("0_0")
>>> # {1, 2}

get_partition_at(tid: int) → list¶

retrieve a partition by id

Parameters:: tid – the id of the partition to retrieve
Returns:: the partition corresponding to the given id
Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([{5,7}, {6,8}, {9}])
>>> lc.get_partition_at(0)
['0_0', '0_1']
>>> lc.get_partition_at(1)
['1_0', '1_1', '1_2']

group_flow(target: str, direction: str, min_branch_size: int = 1) → dict¶

compute the flow of a group w.r.t. a given temporal direction. The flow of a group is the collection of groups that contain at least one element of the target group, Returns a dictionary keyed by group name and valued by the intersection of the target group and the group corresponding to the key.

Parameters:

target – the name of the group to analyze
direction – the temporal direction in which the group is to be analyzed
min_branch_size – the minimum size of the intersection between the target group and the group corresponding

Returns:

a dictionary keyed by group name and valued by the intersection of the target group and the group

Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([[1,2,3], [4,5]])
>>> lc.group_flow("0_0", "+")
>>> # {'1_0': {1, 2}}

group_iterator(tid: int | None = None) → iter¶

returns an iterator over the groups of the LifeCycle. if a temporal id is provided, it will iterate over the groups observed at that time instant

Parameters:: tid – the temporal id of the groups to iterate over. Default is None
Returns:: an iterator over the groups
Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([[1,2,3], [4,5]])
>>> for group in lc.group_iterator():
>>>     print(group)
>>> # {1, 2}
>>> # {3, 4, 5}
>>> # {1, 2, 3}
>>> # {4, 5}

groups_ids() → list¶

retrieve the group ids of the lifecycle. Each id is of the form ‘tid_gid’ where tid is the temporal id and gid is the group id. The group id is a unique identifier of the group within the temporal id.

Returns:: a list of ids of the temporal groups
Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([{5,7}, {6,8}])
>>> lc.groups_ids()
['0_0', '0_1', '1_0', '1_1']

read_json(path: str) → None¶

load the LifeCycle from a json file. If the dtype declared at instantiation differs from the one in the json file, the former will be overwritten by the latter.

Parameters:: path – the path to the json file
Returns:: None
Example:

>>> lc = LifeCycle().read_json('lc.json')

set_attributes(attributes: dict, attr_name: str) → None¶

set the temporal attributes of the elements in the LifeCycle

The temporal attributes must be provided as a dictionary keyed by the element id and valued by a dictionary keyed by the temporal id and valued by the attribute value.

Parameters:

attr_name – the name of the attribute
attributes – a dictionary of temporal attributes

Returns:

None

Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([[1,2,3], [4,5]])
>>> attributes = {
>>>     1: c{0: 'red', 1: 'blue'}, # element 1 is red at time 0 and blue at time 1
>>>     2: {0: 'green', 1: 'magenta'} # element 2 is green at time 0 and magenta at time 1
>>> }
>>> lc.set_attributes(attributes, attr_name="color")

slice(start: int, end: int) → object¶

slice the LifeCycle to keep only a given interval

Parameters:

start – the start of the interval
end – the end of the interval

Returns:

a new LifeCycle object

Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([{5,7}, {6,8}])
>>> lc.add_partition([{5,7}, {1,6,8}])
>>> sliced = lc.slice(0, 1)

temporal_ids() → list¶

retrieve the temporal ids of the LifeCycle. Temporal ids are integers that represent the observation time of a partition.

Example:

>>> lc = LifeCycle()
>>> lc.add_partition([{"a", "b"}, {"c", "d"}]) # at time 0
>>> lc.add_partition([{"a", "b"}, {"c"}]) # at time 1
>>> lc.temporal_ids()
[0, 1]

to_dict() → dict¶

convert the LifeCycle to a dictionary

Returns:: a dictionary representation of the LifeCycle
Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([[1,2,3], [4,5]])
>>> lc.to_dict()
>>> # {'dtype': 'int', 'named_sets': {'0_0': {1, 2}, '0_1': {3, 4, 5}, '1_0': {1, 2, 3}, '1_1': {4, 5}}}

universe_set() → set¶

retrieve the universe set. The universe set is the union of all groups in the LifeCycle

Returns:: the universe set
Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]]) # at time 0
>>> lc.add_partition([{5,7}, {6,8}]) # at time 1
>>> lc.universe_set()
{1, 2, 3, 4, 5, 6, 7, 8}

write_json(path: str) → None¶

save the LifeCycle to a json file

Parameters:: path – the path to the json file
Returns:: None
Example:

>>> lc = LifeCycle()
>>> lc.add_partition([[1,2], [3,4,5]])
>>> lc.add_partition([[1,2,3], [4,5]])
>>> lc.write_json("lc.json")