What are the abstract base classes¶
In order to have a user-consistent interface irrelevant from the implementations of our base-objects, we wanted to define a set of classes with their associated methods, which correspond to all the objects needed for building a StreamGraph.
Such objects are the NodeSet, the LinkSet, the TimeSet, the TemporalNodeSet and the TemporalLinkSet.
Subject of this section is a walkthrough of all those classes and their methods, as well as their properties. This section should be considered as a supplementary to the one of the API documentation and as so a bit less technical and more descriptive.
NodeSet¶
The NodeSet: ns corresponds to a set of nodes.
It’s ns.size is the number of (distinct) elements in the node-set and it’s boolean value bool(ns) is True when the node-set contains more than one element. When iterated iter(ns) (or for n in ns) this object returns distinct nodes, with a paricular order.
The containement statement u in ns, should be true if u is a valid node that belongs to the node-set.
As for all the following classes, the binary operators &, |, -, are defined, corresponding to intersection, union and difference between objects instantiated on the same ABC, defined as set operations.
Similarly the ns.issuperset(nsp) is True if nsp is an instantiation of the same ABC and it is all contained inside ns.
All the above section stands, respectively, for all objects and as so if we don’t have anything special to mention, it will be omitted. All of those functions will be refered collectively as the set binary operators.
Based on each iterator, all objects have a string representation, on which they can be represented as a table.
Finally a copy (with an argument of deep=True) function, is in the definition of all ABCs.
LinkSet¶
The LinkSet: ls corresponds to a set of links.
Those links can be weighted, something which is signified by a boolean property of the class, as ls.weighted.
Along comes the property of ls.weighted_size which is equal with the sum of weights for each distinct-link inside the link-set.
When iterating this object, weights will appear last inside the link tuple, in case the link-set is weighted.
A characteristic method of the LinkSet is the one of ls.neighbors, with two optional arguments u and direction.
If u is not None, the method returns all the neighbors of u inside the link-set as a NodeSet. Inversely if u is None, the method returns for each node inside the link-set it’s neighboring node-set, as a NodeCollection of NodeSet (for learning about the package collections please read the next section).
In all link-objects data is always considered to be directed. Thus, the argument direction, given also to most objects and their methods that consider links, gives the opportunity of getting the 'in', 'out' or 'both' neighbors of the graph. If the graph uni-directed (containing both entries), the direction argument could be ommiteed, as its default (“out”) will reveal the only possible form of neighbors. Similar is the degree, that calculates the amount of neighbors with arguments u, direction and final argument weights which designates if the weighted-degree should be calculated, if the link-set is weighted.
TimeSet¶
The TimeSet: ts, corresponds to a set of time elements.
Time-elements can be both of discrete or instantaneous (time), defined by the properties ts.discrete, ts.instantaneous. For separating instantaneous and non-instantaneous TimeSet a new ABC, is defined by the name ITimeSet (having an inheritance relation to the previous), in which case ts.instantaneous returns aways True, whereas in the first always False.
This is the case for all temporal objects, as the TemporalNodeSet/ITemporalNodeSet and the TemporalLinkSet/ITemporalLinkSet.
In both ABCs, ls.size equals the finish-time minus the start-time of each time element, in the continuous case, where this equals the finish-time minus the start-time, plus one in the discrete. For instantaneous objects, the supplementary property of ts.number_of_instants, counts the number of distinct time-elements.
Finally a method discretize, given some bins and a bin_size, should be able to convert a continuous object to a discrete one, returning the object and the associated bins.
TemporalNodeSet¶
The TemporalNodeSet: tns, comes again in two flavors the normal and an instantaneous one :code:ITemporaNodeSet`, which can be decomposed to the tns.nodeset, that contains all nodes appearing in tns and the tns.timeset, which contains all the time-elements appearing inside the temporal-node-set. When iterated this object returns a tuple where the first element is the node and the other are the time-elements.
Size in this case is the sum: \(\sum_{u} |T_{u}|\), where \(T_{u}\) is the time-set associated with the node \(u\).
tns.n a parameter from graph theory stands therefore to indicate the number of distinct nodes, whereas tns.total_time stands to indicate the amount of time the temporal-node-set exists.
Similarly for each node the tns.node_duration: \(|T_{u}|\) can be calculated for a certain node u or a NodeCollection can be returned calculating that for all nodes. Similarly tns.times_of returns all the time-sets corresponding to each node.
The property tns.total_common_time and the measures tns.common_time and commont_time_pair, calculate respectively the size of time-elements, that appear between each node and all the other, a node and all the other and a pair of nodes. If ommited in the last two cases (which node and which pair it is) a NodeCollection and a LinkCollection are returned respectively.
Finally methods, as ls.nodes_at or ls.n_at (methods that monitor the evolution of some derived information inside time usually end with an _at, whereas method that examine information related with nodes or link throughtout time, end with an _of) extract the NodeSet or the number of nodes active at a certain time instants or throught time, as a TimeGenerator and a TimeCollection.
TemporalLinkSet¶
The TemporalLinkSet: tls, comes to combine all elements discussed before, comming also into an instantaneous flavor :code:ITemporaLinkSet` and being characterized by all previous mentioned ABC properties, tls.discrete, tls.instantaneous, tls.weighted.
The size of temporal-link-set is equal to the sum: \(\sum_{uv} |T_{uv}|\) of all time-elements. As links can have weights, the temporal-link-set has a tls.weighted_size method equal to the sum: \(\sum_{uv} w_{uv}|T_{uv}|\) of the sizes of all time-elements times their weights. Also for the instantaneous, the tls.number_of_instants and the tls.weighted_number_of_instants, can be extracted, where in the second case its instant counts as much as the sum of its weights.
When iterated, this object returns a tuple where the first two elements correspond to the link’s nodes, the last two to the weights if they exist and the in-between to the time-elements.
It can be decomposed to the tls.nodeset, that contains all the nodes appearing inside the temporal-link-set, the tls.linkset that contains all the appearing links (whose size can be extracted as tls.m), a tns.timeset, which contains all the appearing time-elements and two types of TemporalNodeSet, which can be infered from it, referenced as ls.basic_temporal_nodeset and the ls.minimal_temporal_nodeset. In the first one, all nodes that exist inside the temporal-link-set exist from the begining till the end of time, whereas in the second each node-set exists, only for the time-elements that it appears inside a link.
We can extract all the links through time, as the ls.links_at method, as a link-set (for a certain link) or a time-collection of link-sets. Similarly whe can extract all the ls.neighbors_at of a node at a particular time-instant. If t is ommited, we have a TimeGenerator, whereas if code:u is ommited we have a NodeCollection (in case both are ommited we have a NodeCollection of TimeCollection objects).
Similarly with a temporal-node-set, we can extract the time-set related to a particular link ls.times_of or the time-sets of all links if the LinkCollection is ommited.
In order to extract the TemporalNodeSet connected with a node, we have the method neighbors_of.
As the measures of the above methods, we can find tls.m_at, tls.degree_at, tls.duration_of, tls.degree_of where all take the argument weights which signifies if their results will be weighted or not (in case the temporal-link-set is weighted).
Moreover, three methods exist so that a smaller part of the temporal-link-set is extracted. The most general one is the tls.filter method which keeps only those links that satisfy a given boolean function. The next is the tls.substream method, that extracts a temporal-link-set, by constraining it to at least one node-set for the left nodes of links, to a node-set to the right nodes of links and to a time-set for the valid time-elements of a link. Finally the method tls.induced_substream extracts the temporal-link-set that exists inside a given temporal-node-set.
Also, given a temporal-node-set we can extract the tls.temporal_neighborhood of the temporal-link-set, as a temporal-node-set, that is the temporal-nodes that are the neighbors of some given temporal-nodes, inside the temporal-link-set.
Finally, as defined in the introduction we can calculate the mamximal cliques of the temporal-link-set, as tls.get_maximal_cliques.