Drawing module

This module contains functions for drawing temporal networks in different ways. It depends on three packages not being installed during installation with pip, which are

  • matplotlib
  • networkx
  • python-louvain

If you want to use this module, please install the dependencies listed above.

tacoma.drawing.draw_edges(traj, time_normalization_factor=1.0, time_unit=None, ax=None, fit=False, edge_order=None, color=None, alpha=0.5, linewidth=1.0, intervals_to_discard_for_fit=[], fit_color='k', return_fit_params=False)[source]

Draw edges according to an edge activity plot.

Parameters:
  • traj (list of _tacoma.edge_trajectory_entry) – The result of tacoma.api.get_edge_trajectories().
  • float, default (time_normalization_factor,) – Rescale time by this factor.
  • time_unit (str, default : None) – Unit of time to put on the axis.
  • ax (matplotlib.Axes, default : None) – Axis to draw on, will create new one if none provided.
  • fit (bool, default : False) – Fit a curve to the number of uniquely observed edges.
  • edge_order (list of int, default : None) – Reorder the edges according to this list before drawing.
  • color (a matplotlib color, default : None) – Color in which to draw the edges in
  • alpha (float, default : 0.5) – Line opacity of edges
  • linewidth (float, default : 1.0) – Line width of edges
  • intervals_to_discard_for_fit (list of tuple of float) – a list of time intervals which have to be discarded for the fit
  • fit_color (a matplotlib color, default : 'k') – color in which to draw the fit in
  • return_fit_params (bool, default : False) – Switch this on if you want to obtain the fit parameters.
Returns:

  • fig (matplotlib.Figure) – If an axes was provided, this is None.
  • ax (matplotlib.Axes) – The axes the plot was drawn on.
  • popt (tuple of float) – Fit parameters, will only be returned if return_fit_params is True.
tacoma.drawing.edge_activity_plot(temporal_network, time_normalization_factor=1.0, time_unit=None, ax=None, fit=False, edge_order=None, color=None, alpha=0.5, linewidth=1, intervals_to_discard_for_fit=[], fit_color=None, return_fit_params=False)[source]

Draw an edge activity plot for the given temporal network. This is a wrapper for tacoma.drawing.draw_edges().

Parameters:
  • temporal_network (_tacoma.edge_lists or _tacoma.edge_changes.) – A temporal network.
  • float, default (time_normalization_factor,) – Rescale time by this factor.
  • time_unit (str, default : None) – Unit of time to put on the axis.
  • ax (matplotlib.Axes, default : None) – Axis to draw an, will create new one if none provided.
  • fit (bool, default : False) – Fit a curve to the number of uniquely observed edges.
  • edge_order (list of int, default : None) – Reorder the edges according to this list before drawing.
  • color (a matplotlib color, default : None) – Color in which to draw the edges in
  • alpha (float, default : 0.5) – Line opacity of edges
  • linewidth (float, default : 1.0) – Line width of edges
  • intervals_to_discard_for_fit (list of tuple of float) – a list of time intervals which have to be discarded for the fit
  • fit_color (a matplotlib color, default : 'k') – color in which to draw the fit in
  • return_fit_params (bool, default : False) – Switch this on if you want to obtain the fit parameters.
Returns:

  • fig (matplotlib.Figure) – If an axes was provided, this is None.
  • ax (matplotlib.Axes) – The axes the plot was drawn on.
  • popt (tuple of float) – Fit parameters, will only be returned if return_fit_params is True.
tacoma.drawing.fit_function(x, alpha, scale, fac, intervals_to_discard_for_fit)[source]

A fit function for the number of uniquely observed edges over time, following the assumption that edge activity rates follow a gamma distribution.

\[\begin{split}f(x) = \frac{\lambda^\alpha}{\Gamma(\lambda)} x^{\alpha-1}\\exp(-\lambda x)\end{split}\]

The fit function is

\[y(x) = \phi\times \left[ 1 - \left(\frac{\lambda}{\lambda+x}\right)^\alpha\right]\]
Parameters:
  • x (numpy.ndarray) – Data on the x-axis, typically time
  • alpha (float) – exponent in gamma distribution, has to be alpha > 0
  • scale (float) – scale \(\\lambda\) in gamma distribution, has to be scale > 0
  • fac (float) – prefactor, typically \(\\phi=N(N-1)/2\).
  • intervals_to_discard_for_fit (list of tuple of float) – a list of time intervals which have to be discarded for the fit
Returns:

y – value of the function
Return type:

numpy.ndarray
tacoma.drawing.get_edge_graph(edge_traj, edge_sim, threshold=0.0)[source]

Construct a thresholded edge similarity graph.

Parameters:
  • edge_traj (list of _tacoma.edge_trajectory_entry) – Edge trajectories, first result of tacoma.api.get_edge_trajectories(), or entry trajectories of :class`_tacoma.edge_trajectories`.
  • edge_sim (dict where key is a tuple of int and value is a float) – Edge similarities, tuple of int denoting the pair of edges, similarity is in dimension of time. 2nd result of tacoma.api.get_edge_trajectories(), or entry edge_similarities of :class`_tacoma.edge_trajectories`.
  • threshold (float) – Ignore similarities below this threshold (minimum time spent together, where spent together refers to edges connected to the same node at the same time).
Returns:

G – An undirected, unweighted graph where nodes are edges in the temporal network and edges mean their similarity is above the threshold.
Return type:

nx.Graph
tacoma.drawing.get_edge_order(edge_traj, edge_sim, threshold=0.0)[source]

Create an edge order by performing a Louvain-clustering on the thresholded edge similarity graph.

Parameters:
  • edge_traj (list of _tacoma.edge_trajectory_entry) – Edge trajectories, first result of tacoma.api.get_edge_trajectories(), or entry trajectories of :class`_tacoma.edge_trajectories`.
  • edge_sim (dict where key is a tuple of int and value is a float) – Edge similarities, tuple of int denoting the pair of edges, similarity is in dimension of time. 2nd result of tacoma.api.get_edge_trajectories(), or entry edge_similarities of :class`_tacoma.edge_trajectories`.
  • threshold (float) – Ignore similarities below this threshold (minimum time spent together, where spent together refers to edges connected to the same node at the same time).
Returns:

edge_order – Edge indices ordered in clusters.
Return type:

list of int