MuDCoD: Multi-subject Dynamic Community Detection

MuDCoD (Multi-subject Dynamic Community Detection) provides robust community detection in time-varying personalized networks modules. It allow signal sharing between time-steps and subjects by applying eigenvector smoothing. When available, MuDCoD leverages common signals among networks of the subjects and performs robustly when subjects do not share any apparent information. Documentation can be found here.

Installation

Running

See the examples directory for simple examples of Multi-subject Dynamic DCBM, community detection with MuDCoD and cross-validation to choose alpha and beta, $\alpha$ and $\beta$.

For a Python interpreter to be able to import mudcod, it should be on your Python path. The current working directory is (usually) included in the Python path. So you can probably run the examples by running commands like python examples/community_detection.py inside the directory which you clone. You might also want to add mudcod to your global Python path by installing it via pip or copying it to your site-packages directory.

Dependencies

You are able to install dependencies by using poetry install. However, be aware that installed dependencies do not necessarily include all libraries used in experiment scripts (files in the experiments/ directory). The goal was keeping actual dependencies as minimal as possible. So, if you want to re-produce experiments on simulation data or on single-cell RNA-seq datasets, you need to go over the imported libraries and install them separately. A tool like pipreqs or pigar might help in that case. This is not the case for the examples (examples/), poetry install is sufficient to run them.

A Simple Demonstration

Multi-subject Dynamic Degree Corrected Block Model

There are three classes, namely DCBM, DynamicDCBM, and MuSDynamicDCBM.

We use the MuSDynamicDCBM class to generate simulation networks with a given parameter configuration. For example, you can initialize a class instance as below.

mus_dynamic_dcbm = MuSDynamicDCBM(
  n=500,
  k=10,
  p_in=(0.2, 0.4),
  p_out=(0.05, 0.1),
  time_horizon=8,
  r_time=0.4,
  num_subjects=16,
  r_subject=0.2,
  seed=0
)

This will initialize a multi-subject dynamic degree corrected block model with $500$ nodes, $10$ communities, $16$ subjects, and $8$ number of time steps. The connectivity matrix values will be sampled from $\textnormal{Uniform}(0.2, 0.4)$ for the nodes within the same community and from $\textnormal{Uniform}(0.05, 0.1)$ for the nodes in different communities. The parameter for the network evolution along the time will be $0.4$, note that higher values imply more rapid temporal change. Similarly, r_subject=0.2 parameterize the degree of dissimilarity among subjects. After initializing the MuSDynamicDCBM, we can generate an instance of multi-subject time series of networks by running the below line of code.

mus_dynamic_dcbm.simulate_mus_dynamic_dcbm(setting=setting)

Different setting values correspond to the following scenarios. In our experiments, we use setting=1 and setting=2.

• setting=0: Totally independent subjects, evolve independently.

• setting=1: Subjects are siblings at the initial time step, then they evolve independently. (SSoT)

• setting=2: Subjects are siblings at each time point. (SSoS)

• setting=3: Subjects are parents of each other at time 0, then they evolve independently.

• setting=4: Subjects are parents of each other at each time point.

File & Folder Structure

The code is mostly organized and readable.

References

• [1]: Liu, F., Choi, D., Xie, L., Roeder, K. Global spectral clustering in dynamic networks. Proceedings of the National Academy of Sciences 115(5), 927–932 (2018). https://doi.org/10.1073/pnas.1718449115
• [2]: Jerber, J., Seaton, D.D., Cuomo, A.S.E. et al. Population-scale single-cell RNA-seq profiling across dopaminergic neuron differentiation. Nat Genet 53, 304–312 (2021). https://doi.org/10.1038/s41588-021-00801-6