API module¶

This module provides wrapper functions for the core functions provided in the C++-module _tacoma.

tacoma.api.aggregated_network(temporal_network)[source]

Measures the static network composed.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. aggregated_network – Keys represent edges and values represent the aggregated time spent together (in units of time provided by the temporal network dict where keys are pairs of ints and values are floats
tacoma.api.bin(temporal_network, dt=0.0, N_time_steps=0, verbose=False)[source]

Bins a temporal network for each dt (after each step, respectively, if N_time_steps was provided).

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. dt (float) – The demanded bin size. default : 0.0 N_time_steps (int) – Number of time bins (use either this or dt). default : 0 verbose (bool, optional) – Be chatty. An edge_lists instance with one edge list describing the network as a list of all edges that were present in the last time bin. _tacoma.edge_lists
tacoma.api.binned_social_trajectory(temporal_network, node, dt=0.0, N_time_steps=0, verbose=False)[source]

Computes the binned social trajectory of node node in temporal_network, i.e. the groups it was part of and pairs of times (t0, t1) when it was part of a certain group. In this case, binning makes it easier to, e.g. see the days where a group was active.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. node (int) – The node for which to compute the social trajectory dt (float) – The demanded bin size. default : 0.0 N_time_steps (int) – Number of time bins (use either this or dt). default : 0 verbose (bool, optional) – Be chatty. A list, one entry for each dt. Each entry is a list of group ids. list of list of int
tacoma.api.concatenate(list_of_temporal_networks, verbose=False)[source]

Concatenates a list of either _tacoma.edge_changes or _tacoma.edge_lists to a single instance of _tacoma.edge_changes or _tacoma.edge_lists, respectively.

Parameters: temporal_network (list of _tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – A list of a temporal networks. verbose (bool, default : False) – Be chatty. A single instance of the format provided in the lists.
tacoma.api.convert(temporal_network, verbose=False)[source]

Converts either an instance of _tacoma.edge_changes to an instance of _tacoma.edge_lists or vice versa.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. verbose (bool, optional) – Be chatty. An instance of the other format.
tacoma.api.convert_edge_trajectories(traj)[source]

Convert an instance of _tacoma.edge_trajectories to an instance of _tacoma.edge_changes. Note that there’s no method to convert to _tacoma.edge_lists directly.

Parameters: traj (_tacoma.edge_trajectories) – The temporal network which has to be converted. temporal_network – The converted temporal network. _tacoma.edge_changes
tacoma.api.convert_to_edge_trajectories(temporal_network, return_edge_similarities=False, verbose=False)[source]

Converts a temporal network to an instance of _tacoma.edge_trajectories.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. return_edge_similarities (bool, optional) – If this is True, compute the similarity between edges, too. default : False verbose (bool, optional) – Be chatty. traj – The converted temporal network. _tacoma.edge_trajectories
tacoma.api.degree_distribution(temporal_network)[source]

Measures the time-averaged degree distribution.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. P_k – A list of N entries where the k-th entry is the time-averaged probability of finding a node with degree k. list of float
tacoma.api.edge_counts(temporal_network)[source]

Returns the number of edge events and total edge count (In this order: m_in, m_out, and m).

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – A list of a temporal networks. list of int – Number of edges coming into the network at the corresponding times. list of int – Number of edges leaving the network at the corresponding times. list of int – Number of edges existent in the network at the corresponding times.
tacoma.api.get_edge_trajectories(temporal_network, return_edge_similarities=False, verbose=False)[source]

Computes a list of time intervals in which each edge existed and optionally the similarity between edges.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, _tacoma.edge_lists_with_histograms or _tacoma.edge_trajectories) – An instance of a temporal network. return_edge_similarities (bool, optional) – If this is True, return the similarity between edges. default : False verbose (bool, optional) – Be chatty. trajectories (_tacoma.edge_trajectories.trajectories) – a list of edge_trajectory_entry objects, which contain the .time_pairs attributes, a list of time pairs (t0, t1) for time t0 <= t <= t1 in which the edge existed and .edge a pair of node integers. similarities (_tacoma.edge_trajectories.edge_similarities) – a list of triples ( u, v, similarity ) where u and v refer to the edge indices in edge_trajectories.trajectories and similarity is the integrated time both edges were switched on while being connected to the same node.
tacoma.api.gillespie_SI(temporal_network, SI, is_static=False, verbose=False)[source]

Simulates an SI process on the provided temporal network using the Gillespie stochastic simulation algorithm.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. SI (_tacoma.SI) – An initialized SI object. is_static (bool, default : False) – The algorithm works a bit differently if it knows that the network is actually static. It works only with instances of _tacoma.edge_lists. verbose (bool, optional) – Be chatty. But the observables are saved in the _tacoma.SI object. None
tacoma.api.gillespie_SIR(temporal_network, SIR, is_static=False, verbose=False)[source]

Simulates an SIR process on the provided temporal network using the Gillespie stochastic simulation algorithm.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. SIR (_tacoma.SIR) – An initialized SIR object. is_static (bool, default : False) – The algorithm works a bit differently if it knows that the network is actually static. It works only with instances of _tacoma.edge_lists. verbose (bool, optional) – Be chatty. But the observables are saved in the _tacoma.SIR object. None
tacoma.api.gillespie_SIRS(temporal_network, SIRS, is_static=False, verbose=False)[source]

Simulates an SIRS process on the provided temporal network using the Gillespie stochastic simulation algorithm.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. SIRS (_tacoma.SIRS) – An initialized SIRS object. is_static (bool, default : False) – The algorithm works a bit differently if it knows that the network is actually static. It works only with instances of _tacoma.edge_lists. verbose (bool, optional) – Be chatty. But the observables are saved in the _tacoma.SIRS object. None
tacoma.api.gillespie_SIS(temporal_network, SIS, is_static=False, verbose=False)[source]

Simulates an SIS process on the provided temporal network using the Gillespie stochastic simulation algorithm.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. SIS (_tacoma.SIS) – An initialized SIS object. is_static (bool, default : False) – The algorithm works a bit differently if it knows that the network is actually static. It works only with instances of _tacoma.edge_lists. verbose (bool, optional) – Be chatty. But the observables are saved in the _tacoma.SIS object. None
tacoma.api.gillespie_epidemics(temporal_network_or_model, epidemic_object, is_static=False, reset_simulation_objects=True, verbose=False)[source]

Simulates an epidemic process on the provided temporal network using the Gillespie stochastic simulation algorithm.

Parameters: temporal_network_or_model (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, _tacoma.edge_lists_with_histograms, _tacoma.EdgeActivityModel, or _tacoma.FlockworkPModel.) – An instance of a temporal network or network model. epidemic_object (_tacoma.SI, _tacoma.SIS, _tacoma.SIR, _tacoma.SIRS, _tacoma.node_based_SIS, _tacoma.eSIS) – An initialized epidemic object. is_static (bool, default : False) – The algorithm works a bit differently if it knows that the network is actually static. It works only with instances of _tacoma.edge_lists. reset_simulation_objects (bool, default : True) – Whether or not the simulation objects should be reset in the beginning. verbose (bool, optional) – Be chatty. But the observables are saved in the _tacoma epidemic object. None
tacoma.api.gillespie_node_based_SIS(temporal_network, SIS, is_static=False, verbose=False)[source]

Simulates a node-based SIS process on the provided temporal network using the Gillespie stochastic simulation algorithm.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. SIS (_tacoma.SIS_node_based) – An initialized node-based SIS object. is_static (bool, default : False) – The algorithm works a bit differently if it knows that the network is actually static. It works only with instances of _tacoma.edge_lists. verbose (bool, optional) – Be chatty. But the observables are saved in the _tacoma.SIS object. None
tacoma.api.markov_epidemics(temporal_network_or_model, epidemic_object, max_dt, is_static=False, reset_simulation_objects=True, verbose=False)[source]

Integrates an epidemic markov process on the provided temporal network.

Parameters: temporal_network_or_model (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, _tacoma.edge_lists_with_histograms, _tacoma.EdgeActivityModel, or _tacoma.FlockworkPModel.) – An instance of a temporal network or network model. epidemic_object (_tacoma.MARKOV_SIS) – An initialized epidemic object. max_dt (float) – The maximally allowed integration step. is_static (bool, default : False) – The algorithm works a bit differently if it knows that the network is actually static. It works only with instances of _tacoma.edge_lists. reset_simulation_objects (bool, default : True) – Whether or not the simulation objects should be reset in the beginning. verbose (bool, optional) – Be chatty. But the observables are saved in the _tacoma epidemic Markov-object. None
tacoma.api.mean_degree(temporal_network)[source]

Computes the time dependent mean degree of the temporal network.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – A list of a temporal networks. numpy array – t containing the time points. numpy array – k containing the mean degree at the corresponding times.
tacoma.api.measure_group_sizes_and_durations(temporal_network, ignore_size_histogram=False, verbose=False)[source]

Measures aggregated group size distribution, group size histogram for each time point, contact durations, inter-contact durations, durations of each group size, and the aggregated social network.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. ignore_size_histogram (bool, optional) – Don’t compute the single time point group size histograms (save time and memory). default : False verbose (bool, optional) – Be chatty. The result of the measurements. Note that inter-contact durations is just durations of groups of size 1 and hence correspond to the first entry of _tacoma.group_sizes_and_durations.group_durations. _tacoma.group_sizes_and_durations
tacoma.api.sample(temporal_network, dt=0.0, N_time_steps=0, sample_aggregates=False, verbose=False)[source]

Samples a temporal network after each dt (after each step, respectively, if N_time_steps was provided).

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. dt (float) – The demanded bin size. default : 0.0 N_time_steps (int) – Number of time bins (use either this or dt). default : 0 sample_aggregates (bool, optional) – If this is True, the following happens. If an edge is active during a time bin, it will appear in the final graph at the end of this time bin. It will then exist until the ende of the coming time bin. (This is different from the binning procedure). This does not seem to make very much sense so maybe just don’t use it. default : False verbose (bool, optional) – Be chatty. An edge_lists instance with one edge list describing the network states after each discrete time step. _tacoma.edge_lists
tacoma.api.slice(temporal_network, new_t0, new_tmax, verbose=False)[source]

Get a slice of a temporal network for times new_t0 <= t < new_tmax.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. new_t0 (float) – Where the slice should begin. new_t0 – Where the slice should end. verbose (bool, optional) – Be chatty. default : False Sliced network (type depending on input type).
tacoma.api.social_trajectory(temporal_network, node, verbose=False)[source]

Computes the social trajectory of node node in temporal_network, i.e. the groups it was part of and pairs of times (t0, t1) when it was part of a certain group.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. node (int) – The node for which to compute the social trajectory verbose (bool, optional) – Be chatty.
tacoma.api.verify(temporal_network, verbose=False)[source]

Checks wether the temporal network is compliant with the demanded formats for analyses. Writes remarks on violations to stdout.

Parameters: temporal_network (_tacoma.edge_changes, _tacoma.edge_lists, _tacoma.edge_changes_with_histograms, or _tacoma.edge_lists_with_histograms) – An instance of a temporal network. verbose (bool, optional) – If this is True, cout all errors that were found. default : False Number of found errors. int