Temporal contact modeling and analysis¶

About this project¶

Tacoma is an acronym for (T)empor(A)l (CO)ntact (M)odeling and (A)nalysis. It is a joint C++/Python-package for the modeling and analysis of undirected and unweighted temporal networks, with a focus on (but not limited to) human face-to-face contact networks.

Quick example¶

In order to download the SocioPatterns ‘Hypertext 2009’-dataset and visualize it interactively, do the following.

>>> import tacoma as tc
>>> from tacoma.interactive import visualize
>>> temporal_network = tc.download_and_convert_sociopatterns_hypertext_2009()
100% [........................................................] 67463 / 67463
>>> visualize(temporal_network, frame_dt = 20)

This is the result:

Why should I use tacoma?¶

Pros¶

networks are natively described in continuous time
two main native formats to describe temporal networks (_tacoma.edge_lists and _tacoma.edge_changes), a third way, a sorted list of on-intervals for each edge called tc.edge_trajectories is available, but algorithms work on the two native formats only
the simple portable file-format .taco as a standardized way to share temporal network data (which is just the data dumped to a .json-file, a simple file format readable from a variety of languages)
easy functions to produce surrogate temporal networks from four different models
easy way to simulate Gillespie (here, epidemic spreading) processes on temporal networks
easy framework to develop new Gillespie-simulations algorithms on temporal networks
multiple and simple ways to interactively visualize temporal networks
simple functions to manipulate temporal networks (slice, concatenate, rescale time, sample, bin, convert)
simple functions to analyze structural and statistical properties of temporal networks (mean degree, degree distribution, group size distribution, group life time distributions, etc.)
fast algorithms due to C++-core (fast as in faster than pure Python)
relatively fast and easy to compile since it only depends on the C++11-stdlib and pybind11 without the large overhead of Boost

Cons¶

no support for directed temporal networks yet
no support for weighted temporal networks yet

Install¶

If you get compiling errors, make sure that pybind11 is installed.

$ git clone https://github.com/benmaier/tacoma
$ pip install ./tacoma

Note that a C++11-compiler has to be installed on the system before installing tacoma.

Temporal network classes¶

Undirected and unweighted temporal networks are composed of \(N\) nodes and up to \(m_{\mathrm{max}}=N(N+1)/2\) edges, where each edge \((i,j)\) can be described as a series of events where the edge is either switched on or switched off. One way of expressing that is to define the temporal adjacency matrix

\[\begin{split}A_{ij}(t) = \begin{cases} 1, & (i,j)\ \mathrm{connected\ at\ time\ } t\\ 0, & \mathrm{else}. \end{cases}\end{split}\]

In tacoma, we will interpret temporal networks as if they were recorded in an experiment. We expect that over the course of time \(t_0\leq t < t_\mathrm{max}\) in which we record activity, we will encounter \(N\) nodes from the node set \(V={0,1,\dots,N-1}\) (nodes posses an integer label).

The experiment begins at time \(t_0\), where the network consists of an edge set \(E_0 \subseteq \{i,j: V\times V, i<j\}\). Then, each time the network changes, we denote that time by an entry in a time vector \(t\). Each entry in the time vector corresponds to a network change event and thus to a change in the edge set. We call the total number of change events \(N_e\), such that the vector \(t\) has \(N_e\) entries. In between consecutive times, the network is constant. After the last recorded event, we kept the experiment running until the maximum time \(t_\mathrm{max}\) without observing any change and stopped recording at \(t_\mathrm{max}\).

There’s three data structures implemented in this package, all of which capture the situation described above in different ways and are useful in different situations.

Edge lists¶

The class _tacoma.edge_lists consists of a collection of complete edge lists, each time the network changes, a complete edge list of the network after the change is saved. It has the following attributes.

\(N\) : The total number of nodes
\(t\) : A vector of length \(N_e+1\). The 0-th entry contains the time of the beginning of the experiment \(t_0\)
edges : A vector of length \(N_e+1\) where each entry contains an edge list, describing the network after the change which occured at the corresponding time in \(t\). The 0-th entry contains the edge list of the beginning of the experiment \(t_0\)
\(t_\mathrm{max}\) : The time at which the experiment ended.

Additionally,

Edge changes¶

The class _tacoma.edge_changes consists of a collection of both edges being created and edges being deleted. It has the following attributes.

\(N\) : The total number of nodes.
\(t_0\) : The time of the beginning of the experimen.
edges_initial : The edge list of the beginning of the experiment at \(t_0\).
\(t\) : A vector of length \(N_e\), each time corresponding to a change in the network.
\(t_\mathrm{max}\) : The time at which the experiment ended.

Additionally,

Edge trajectories¶

Relevant C++-core classes¶

API module¶

Analysis module¶

A reference to tacoma.analysis.