Source code for tacoma.api

# -*- coding: utf-8 -*-
"""
This module provides wrapper functions for the core functions provided in the
C++-module `_tacoma`.
"""

import numpy as np

import _tacoma as _tc

from _tacoma import edge_changes as ec
from _tacoma import edge_lists as el
from _tacoma import edge_lists_with_histograms as el_h
from _tacoma import edge_changes_with_histograms as ec_h

edge_changes = _tc.edge_changes
edge_lists = _tc.edge_lists
edge_lists_with_histograms = _tc.edge_lists_with_histograms
edge_changes_with_histograms = _tc.edge_changes_with_histograms
edge_trajectories = _tc.edge_trajectories
edge_trajectory_entry = _tc.edge_trajectory_entry

from tacoma.network_formats import adjacency_matrices
from tacoma.network_formats import sparse_adjacency_matrices

edge_weight = _tc.edge_weight
social_trajectory_entry = _tc.social_trajectory_entry

SI = _tc.SI
SIS = _tc.SIS
SIR = _tc.SIR
SR = _tc.SR
SIRS = _tc.SIRS
node_based_SIS = _tc.node_based_SIS
eSIS = _tc.eSIS
EdgeActivityModel = _tc.EdgeActivityModel
QS_SIS = _tc.QS_SIS
coverage_SIS = _tc.coverage_SIS
cluster_size_SIS = _tc.cluster_size_SIS
FlockworkPModel = _tc.FlockworkPModel
MARKOV_SIS = _tc.MARKOV_SIS


def _get_raw_temporal_network(temporal_network):
    """Return an instance of `edge_changes` if the temporal network was an instance of 
    `edge_changes_with_histograms` (return `edge_lists` for `edge_lists_with_histograms`)."""

    if type(temporal_network) == ec_h:
        temporal_network = ec(temporal_network)
    elif type(temporal_network) == el_h:
        temporal_network = el(temporal_network)

    return temporal_network


[docs]def measure_group_sizes_and_durations(temporal_network, ignore_size_histogram=False, verbose=False): """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 : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_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. Returns ------- :class:`_tacoma.group_sizes_and_durations` 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 :class:`_tacoma.group_sizes_and_durations.group_durations`. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.measure_group_sizes_and_durations_for_edge_changes(temporal_network, ignore_size_histogram, verbose, ) elif type(temporal_network) == el: result = _tc.measure_group_sizes_and_durations_for_edge_lists(temporal_network, ignore_size_histogram, verbose, ) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def aggregated_network(temporal_network): """Measures the static network composed. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_tacoma.edge_lists_with_histograms` An instance of a temporal network. Returns ------- aggregated_network : :obj:`dict` where keys are pairs of ints and values are floats Keys represent edges and values represent the aggregated time spent together (in units of time provided by the temporal network """ return measure_group_sizes_and_durations(temporal_network).aggregated_network
[docs]def degree_distribution(temporal_network): """Measures the time-averaged degree distribution. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_tacoma.edge_lists_with_histograms` An instance of a temporal network. Returns ------- P_k : :obj:`list` of `float` A list of N entries where the k-th entry is the time-averaged probability of finding a node with degree k. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.degree_distribution_from_edge_changes(temporal_network) elif type(temporal_network) == el: result = _tc.degree_distribution_from_edge_lists(temporal_network) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def bin(temporal_network, dt=0.0, N_time_steps=0, verbose=False): """Bins a temporal network for each `dt` (after each step, respectively, if `N_time_steps` was provided). Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_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. Returns ------- :class:`_tacoma.edge_lists` 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. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.bin_from_edge_changes( temporal_network, dt, N_time_steps, verbose) elif type(temporal_network) == el: result = _tc.bin_from_edge_lists( temporal_network, dt, N_time_steps, verbose) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def slice(temporal_network, new_t0, new_tmax, verbose=False): """Get a slice of a temporal network for times new_t0 <= t < new_tmax. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_tacoma.edge_lists_with_histograms` An instance of a temporal network. new_t0 : float Where the slice should begin. new_t0 : float Where the slice should end. verbose: bool, optional Be chatty. default : False Returns ------- :class:`_tacoma.edge_lists` or :class:`_tacoma.edge_changes` Sliced network (type depending on input type). """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.slice_edge_changes( temporal_network, new_t0, new_tmax, verbose) elif type(temporal_network) == el: result = _tc.slice_edge_lists( temporal_network, new_t0, new_tmax, verbose) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def sample(temporal_network, dt=0.0, N_time_steps=0, sample_aggregates=False, verbose=False): """Samples a temporal network after each `dt` (after each step, respectively, if `N_time_steps` was provided). Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_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. Returns ------- :class:`_tacoma.edge_lists` An edge_lists instance with one edge list describing the network states after each discrete time step. """ temporal_network = _get_raw_temporal_network(temporal_network) if isinstance(temporal_network, ec): result = _tc.sample_from_edge_changes(temporal_network, dt, N_time_steps, sample_aggregates, verbose, ) elif isinstance(temporal_network, el): result = _tc.sample_from_edge_lists(temporal_network, dt, N_time_steps, sample_aggregates, verbose, ) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def binned_social_trajectory(temporal_network, node, dt=0.0, N_time_steps=0, verbose=False): """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 : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_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. Returns ------- :obj:`list` of :obj:`list` of int A list, one entry for each dt. Each entry is a list of group ids. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.binned_social_trajectory_from_edge_changes(temporal_network, node, dt, N_time_steps, verbose ) elif type(temporal_network) == el: result = _tc.binned_social_trajectory_from_edge_lists(temporal_network, node, dt, N_time_steps, verbose ) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def social_trajectory(temporal_network, node, verbose=False): """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 : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_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. Returns ------- :obj:`list` of :class:`_tacoma.social_trajectory_entry` """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.social_trajectory_from_edge_changes( temporal_network, node, verbose) elif type(temporal_network) == el: result = _tc.social_trajectory_from_edge_lists( temporal_network, node, verbose) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def markov_epidemics(temporal_network_or_model, epidemic_object, max_dt, is_static=False, reset_simulation_objects=True, verbose=False): """Integrates an epidemic markov process on the provided temporal network. Parameters ---------- temporal_network_or_model : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, :class:`_tacoma.edge_lists_with_histograms`, :class:`_tacoma.EdgeActivityModel`, or :class:`_tacoma.FlockworkPModel`. An instance of a temporal network or network model. epidemic_object : :class:`_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 :class:`_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. Returns ------- None But the observables are saved in the :mod:`_tacoma` epidemic Markov-object. """ tn_or_mdl = temporal_network_or_model if type(tn_or_mdl) in [ec, ec_h]: temporal_network = _get_raw_temporal_network(tn_or_mdl) if type(epidemic_object) == MARKOV_SIS: _tc.markov_SIS_on_edge_changes(temporal_network, epidemic_object, max_dt, verbose) else: raise ValueError('Invalid epidemic object type: ' + str(type(epidemic_object))) elif type(tn_or_mdl) in [el, el_h]: temporal_network = _get_raw_temporal_network(tn_or_mdl) if type(epidemic_object) == MARKOV_SIS: _tc.markov_SIS_on_edge_lists(temporal_network, epidemic_object, max_dt, is_static, verbose) else: raise ValueError('Invalid epidemic object type: ' + str(type(epidemic_object))) elif type(tn_or_mdl) in [EdgeActivityModel]: temporal_network = tn_or_mdl if type(epidemic_object) == MARKOV_SIS: _tc.markov_SIS_on_EdgeActivityModel(temporal_network, epidemic_object, max_dt, reset_simulation_objects, verbose) else: raise ValueError('Invalid epidemic object type: ' + str(type(epidemic_object))) elif type(tn_or_mdl) in [FlockworkPModel]: temporal_network = tn_or_mdl if type(epidemic_object) == MARKOV_SIS: _tc.markov_SIS_on_FlockworkPModel(temporal_network, epidemic_object, max_dt, reset_simulation_objects, verbose) else: raise ValueError('Invalid epidemic object type: ' + str(type(epidemic_object))) else: raise ValueError('Invalid temporal network/model format: ' + str(type(tn_or_mdl)))
[docs]def gillespie_epidemics(temporal_network_or_model, epidemic_object, is_static=False, reset_simulation_objects=True, verbose=False): """Simulates an epidemic process on the provided temporal network using the Gillespie stochastic simulation algorithm. Parameters ---------- temporal_network_or_model : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, :class:`_tacoma.edge_lists_with_histograms`, :class:`_tacoma.EdgeActivityModel`, or :class:`_tacoma.FlockworkPModel`. An instance of a temporal network or network model. epidemic_object : :class:`_tacoma.SI`, :class:`_tacoma.SIS`, :class:`_tacoma.SIR`, :class:`_tacoma.SIRS`, :class:`_tacoma.node_based_SIS`, :class:`_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 :class:`_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. Returns ------- None But the observables are saved in the :mod:`_tacoma` epidemic object. """ tn_or_mdl = temporal_network_or_model if type(tn_or_mdl) in [ec, ec_h]: temporal_network = _get_raw_temporal_network(tn_or_mdl) if type(epidemic_object) == SI: _tc.gillespie_SI_on_edge_changes(temporal_network, epidemic_object, verbose) elif type(epidemic_object) == SIS: _tc.gillespie_SIS_on_edge_changes(temporal_network, epidemic_object, verbose) elif type(epidemic_object) == SIR: _tc.gillespie_SIR_on_edge_changes(temporal_network, epidemic_object, verbose) elif type(epidemic_object) == SR: _tc.gillespie_SR_on_edge_changes(temporal_network, epidemic_object, verbose) elif type(epidemic_object) == SIRS: _tc.gillespie_SIRS_on_edge_changes(temporal_network, epidemic_object, verbose) elif type(epidemic_object) == node_based_SIS: _tc.gillespie_node_based_SIS_on_edge_changes(temporal_network, epidemic_object, verbose) elif type(epidemic_object) == eSIS: _tc.gillespie_eSIS_on_edge_changes(temporal_network, epidemic_object, verbose) elif type(epidemic_object) == coverage_SIS: _tc.gillespie_coverage_SIS_on_edge_changes(temporal_network, epidemic_object, verbose) elif type(epidemic_object) == cluster_size_SIS: _tc.gillespie_cluster_size_SIS_on_edge_changes(temporal_network, epidemic_object, verbose) else: raise ValueError('Invalid epidemic object type: ' + str(type(epidemic_object))) elif type(tn_or_mdl) in [el, el_h]: temporal_network = _get_raw_temporal_network(tn_or_mdl) if type(epidemic_object) == SI: _tc.gillespie_SI_on_edge_lists(temporal_network, epidemic_object, is_static, verbose) elif type(epidemic_object) == SIS: _tc.gillespie_SIS_on_edge_lists(temporal_network, epidemic_object, is_static, verbose) elif type(epidemic_object) == SIR: _tc.gillespie_SIR_on_edge_lists(temporal_network, epidemic_object, is_static, verbose) elif type(epidemic_object) == SR: _tc.gillespie_SR_on_edge_lists(temporal_network, epidemic_object, is_static, verbose) elif type(epidemic_object) == SIRS: _tc.gillespie_SIRS_on_edge_lists(temporal_network, epidemic_object, is_static, verbose) elif type(epidemic_object) == node_based_SIS: _tc.gillespie_node_based_SIS_on_edge_lists(temporal_network, epidemic_object, is_static, verbose) elif type(epidemic_object) == eSIS: _tc.gillespie_eSIS_on_edge_lists(temporal_network, epidemic_object, is_static, verbose) elif type(epidemic_object) == coverage_SIS: _tc.gillespie_coverage_SIS_on_edge_lists(temporal_network, epidemic_object, is_static, verbose) elif type(epidemic_object) == cluster_size_SIS: _tc.gillespie_cluster_size_SIS_on_edge_lists(temporal_network, epidemic_object, is_static, verbose) else: raise ValueError('Invalid epidemic object type: ' + str(type(epidemic_object))) elif type(tn_or_mdl) in [EdgeActivityModel]: temporal_network = tn_or_mdl if type(epidemic_object) == SI: _tc.gillespie_SI_on_EdgeActivityModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == SIS: _tc.gillespie_SIS_on_EdgeActivityModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == SIR: _tc.gillespie_SIR_on_EdgeActivityModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == SR: _tc.gillespie_SR_on_EdgeActivityModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == SIRS: _tc.gillespie_SIRS_on_EdgeActivityModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == node_based_SIS: _tc.gillespie_node_based_SIS_on_EdgeActivityModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == eSIS: _tc.gillespie_eSIS_on_EdgeActivityModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == coverage_SIS: _tc.gillespie_coverage_SIS_on_EdgeActivityModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == cluster_size_SIS: _tc.gillespie_cluster_size_SIS_on_EdgeActivityModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) else: raise ValueError('Invalid epidemic object type: ' + str(type(epidemic_object))) elif type(tn_or_mdl) in [FlockworkPModel]: temporal_network = tn_or_mdl if type(epidemic_object) == SI: _tc.gillespie_SI_on_FlockworkPModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == SIS: _tc.gillespie_SIS_on_FlockworkPModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == SIR: _tc.gillespie_SIR_on_FlockworkPModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == SR: _tc.gillespie_SIR_on_FlockworkPModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == SIRS: _tc.gillespie_SIRS_on_FlockworkPModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == node_based_SIS: _tc.gillespie_node_based_SIS_on_FlockworkPModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == eSIS: _tc.gillespie_eSIS_on_FlockworkPModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == coverage_SIS: _tc.gillespie_coverage_SIS_on_FlockworkPModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) elif type(epidemic_object) == cluster_size_SIS: _tc.gillespie_cluster_size_SIS_on_FlockworkPModel(temporal_network, epidemic_object, reset_simulation_objects, verbose) else: raise ValueError('Invalid epidemic object type: ' + str(type(epidemic_object))) else: raise ValueError('Invalid temporal network/model format: ' + str(type(tn_or_mdl)))
[docs]def gillespie_SIS(temporal_network, SIS, is_static=False, verbose=False): """Simulates an SIS process on the provided temporal network using the Gillespie stochastic simulation algorithm. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_tacoma.edge_lists_with_histograms` An instance of a temporal network. SIS : :class:`_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 :class:`_tacoma.edge_lists`. verbose: bool, optional Be chatty. Returns ------- None But the observables are saved in the :class:`_tacoma.SIS` object. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.gillespie_SIS_on_edge_changes( temporal_network, SIS, verbose) elif type(temporal_network) == el: result = _tc.gillespie_SIS_on_edge_lists( temporal_network, SIS, is_static, verbose) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def gillespie_node_based_SIS(temporal_network, SIS, is_static=False, verbose=False): """Simulates a node-based SIS process on the provided temporal network using the Gillespie stochastic simulation algorithm. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_tacoma.edge_lists_with_histograms` An instance of a temporal network. SIS : :class:`_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 :class:`_tacoma.edge_lists`. verbose: bool, optional Be chatty. Returns ------- None But the observables are saved in the :class:`_tacoma.SIS` object. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.gillespie_node_based_SIS_on_edge_changes( temporal_network, SIS, verbose) elif type(temporal_network) == el: result = _tc.gillespie_node_based_SIS_on_edge_lists( temporal_network, SIS, is_static, verbose) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def gillespie_SI(temporal_network, SI, is_static=False, verbose=False): """Simulates an SI process on the provided temporal network using the Gillespie stochastic simulation algorithm. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_tacoma.edge_lists_with_histograms` An instance of a temporal network. SI : :class:`_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 :class:`_tacoma.edge_lists`. verbose: bool, optional Be chatty. Returns ------- None But the observables are saved in the :class:`_tacoma.SI` object. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.gillespie_SI_on_edge_changes( temporal_network, SI, verbose) elif type(temporal_network) == el: result = _tc.gillespie_SI_on_edge_lists( temporal_network, SI, is_static, verbose) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def gillespie_SIR(temporal_network, SIR, is_static=False, verbose=False): """Simulates an SIR process on the provided temporal network using the Gillespie stochastic simulation algorithm. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_tacoma.edge_lists_with_histograms` An instance of a temporal network. SIR : :class:`_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 :class:`_tacoma.edge_lists`. verbose: bool, optional Be chatty. Returns ------- None But the observables are saved in the :class:`_tacoma.SIR` object. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.gillespie_SIR_on_edge_changes( temporal_network, SIR, verbose) elif type(temporal_network) == el: result = _tc.gillespie_SIR_on_edge_lists( temporal_network, SIR, is_static, verbose) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def gillespie_SIRS(temporal_network, SIRS, is_static=False, verbose=False): """Simulates an SIRS process on the provided temporal network using the Gillespie stochastic simulation algorithm. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_tacoma.edge_lists_with_histograms` An instance of a temporal network. SIRS : :class:`_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 :class:`_tacoma.edge_lists`. verbose: bool, optional Be chatty. Returns ------- None But the observables are saved in the :class:`_tacoma.SIRS` object. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: _tc.gillespie_SIRS_on_edge_changes(temporal_network, SIRS, verbose) elif type(temporal_network) == el: _tc.gillespie_SIRS_on_edge_lists( temporal_network, SIRS, is_static, verbose) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network)))
[docs]def convert_to_edge_trajectories(temporal_network, return_edge_similarities=False, verbose=False): """Converts a temporal network to an instance of :class:`_tacoma.edge_trajectories`. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_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. Returns ------- traj : :class:`_tacoma.edge_trajectories` The converted temporal network. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: if return_edge_similarities: raise ValueError( 'Please convert to `edge_lists` first as the edge similarity algorithm is only implemented for `edge_lists`') result = _tc.edge_trajectories_from_edge_changes( temporal_network, return_edge_similarities, verbose) elif type(temporal_network) == el: result = _tc.edge_trajectories_from_edge_lists( temporal_network, return_edge_similarities) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def convert_edge_trajectories(traj): """ Convert an instance of :class:`_tacoma.edge_trajectories` to an instance of :class:`_tacoma.edge_changes`. Note that there's no method to convert to :class:`_tacoma.edge_lists` directly. Parameters ---------- traj : :class:`_tacoma.edge_trajectories` The temporal network which has to be converted. Returns ------- temporal_network : :class:`_tacoma.edge_changes` The converted temporal network. """ return _tc.convert_edge_trajectories_to_edge_changes(traj)
[docs]def get_edge_trajectories(temporal_network, return_edge_similarities=False, verbose=False): """ Computes a list of time intervals in which each edge existed and optionally the similarity between edges. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, :class:`_tacoma.edge_lists_with_histograms` or :class:`_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. Returns ------- trajectories : :class:`_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 : :class:`_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. """ if type(temporal_network) == edge_trajectories: result = temporal_network else: result = convert_to_edge_trajectories( temporal_network, return_edge_similarities, verbose) if return_edge_similarities: return result.trajectories, result.edge_similarities else: return result.trajectories return result
[docs]def verify(temporal_network, verbose=False): """Checks wether the temporal network is compliant with the demanded formats for analyses. Writes remarks on violations to stdout. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_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 Returns ------- int Number of found errors. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.verify_edge_changes(temporal_network, verbose) elif type(temporal_network) == el: result = _tc.verify_edge_lists(temporal_network, verbose) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def convert(temporal_network, verbose=False): """Converts either an instance of :class:`_tacoma.edge_changes` to an instance of :class:`_tacoma.edge_lists` or vice versa. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_tacoma.edge_lists_with_histograms` An instance of a temporal network. verbose: bool, optional Be chatty. Returns ------- An instance of the other format. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.convert_edge_changes(temporal_network, verbose=False) elif type(temporal_network) == el: result = _tc.convert_edge_lists(temporal_network, verbose=False) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return result
[docs]def concatenate(list_of_temporal_networks, verbose = False): """Concatenates a list of either :class:`_tacoma.edge_changes` or :class:`_tacoma.edge_lists` to a single instance of :class:`_tacoma.edge_changes` or :class:`_tacoma.edge_lists`, respectively. Parameters ---------- temporal_network : :obj:`list` of :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_tacoma.edge_lists_with_histograms` A list of a temporal networks. verbose: bool, default : False Be chatty. Returns ------- A single instance of the format provided in the lists. """ list_of_temporal_networks = [_get_raw_temporal_network( _t) for _t in list_of_temporal_networks] _t = list_of_temporal_networks[0] if type(_t) == ec: result = _tc.concatenate_edge_changes( list_of_temporal_networks, verbose) elif type(_t) == el: result = _tc.concatenate_edge_lists(list_of_temporal_networks, verbose) else: raise ValueError('Unknown temporal network format: ' + str(type(_t))) return result
[docs]def mean_degree(temporal_network): """Computes the time dependent mean degree of the temporal network. Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_tacoma.edge_lists_with_histograms` A list of a temporal networks. Returns ------- numpy array `t` containing the time points. numpy array `k` containing the mean degree at the corresponding times. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == ec: result = _tc.mean_degree_from_edge_changes(temporal_network) elif type(temporal_network) == el: result = _tc.mean_degree_from_edge_lists(temporal_network) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) result = np.array(result) t, k = result[:, 0], result[:, 1] return t, k
[docs]def edge_counts(temporal_network): """Returns the number of edge events and total edge count (In this order: `m_in`, `m_out`, and `m`). Parameters ---------- temporal_network : :class:`_tacoma.edge_changes`, :class:`_tacoma.edge_lists`, :class:`_tacoma.edge_changes_with_histograms`, or :class:`_tacoma.edge_lists_with_histograms` A list of a temporal networks. Returns ------- :obj:`list` of `int` Number of edges coming into the network at the corresponding times. :obj:`list` of `int` Number of edges leaving the network at the corresponding times. :obj:`list` of `int` Number of edges existent in the network at the corresponding times. """ temporal_network = _get_raw_temporal_network(temporal_network) if type(temporal_network) == el: temporal_network = convert(temporal_network) if type(temporal_network) == ec: m_in, m_out, m = _tc.get_edge_counts(temporal_network) else: raise ValueError('Unknown temporal network format: ' + str(type(temporal_network))) return m_in, m_out, m