flow_stability

flow_stability copied to clipboard

flowstab - Flow stability for dynamic community detection

Python package for the dynamic community detection in temporal networks implementing the flow stability framework described in

Alexandre Bovet, Jean-Charles Delvenne & Renaud Lambiotte, Flow stability for dynamic community detection, Sci. Adv., 8 (19), eabj3063. DOI: 10.1126/sciadv.abj3063

Requirements:

• Python3 (>=3.9)
• pandas
• scipy
• numpy
• Cython (optional but highly recommended)
• sparse_dot_mkl (optional, allows to perform multithreaded sparse matrix multiplication)

Installation

You can pip install flowstab directly from this repository into your virtual environment. Simply run:

pip install git+https://github.com/alexbovet/flow_stability.git

Usage

After installation you can access the relevant classes and methods by importing flowstab into your python scripts or via command line (see CLI scripts for details).

If you want to use the FlowIntegralClustering class, for example, you would want to add the following line in your script:

from flowstab.FlowStability import FlowIntegralClustering

# forw_flow = FlowIntegralClustering(...

Refer to the examples folder more detailed usage examples.

CLI scripts

flowstab provides also several command line hooks that can be run directly in the terminal after installation without the need of opening a python shell:

run_clusterings

This command requires sparse_dot_mkl which relies on the closed-source libmkl_rt.so library. In Ubuntu you might need to fetch this library with apt-get install libmkl-rt.

run_cov_integrals

run_laplacians_transmats

Content

The main classes are:

• ContTempNetwork in the module TemporalNetwork which is used to store and save temporal networks and to compute inter-event transition matrices.
• FlowIntegralClustering in the module FlowStability which is used to computed the flow stability (integral of covariance) and to find the best forward and backward partition using the Louvain algorithm.

Additional interesting classes and functions are:

• Clustering and SparseClustering in FlowStability can be used to directly cluster covariances or integrals of covariances.
• static_clustering in FlowStability is an helper function to cluster static networks using Markov Stability.
• run_multi_louvain in FlowStability helper function to run the Louvain multiple times on the same covariance in order to check the robustness of the partition.
• avg_norm_var_information in FlowStability computes the average Normalized Variation of Information of list of cluster lists obtained with run_multi_louvain.
• compute_parallel_clustering in parallel_clustering, same than run_multi_louvain but in parallel.
• the parallel_expm module contains functions to compute the matrix exponential of very large matrices using different strategies.

A jupyter notebook reproducing the example from Fig. 2 of the paper is available in asymmetric_example.ipynb.