ProbINet

Welcome to the documentation for the Probabilistic Inference on Networks (ProbINet) Python package. This project is a collaborative effort to consolidate state-of-the-art probabilistic generative modeling implementations from various scientific publications. Our focus lies in advancing network analysis techniques with an emphasis on recent modeling approaches that relax the restrictive conditional independence assumption, enabling the modeling of joint distributions of network data.

The ProbINet package is designed to be a comprehensive and user-friendly toolset for researchers and practitioners interested in modeling network data through probabilistic generative approaches. Our goal is to provide a unified resource that brings together different advances scattered across many code repositories. By doing so, we aim not only to enhance the usability of existing models, but also to facilitate the comparison of different approaches. Moreover, through a range of tutorials, we aim at simplifying the use of these methods to perform inferential tasks, including the prediction of missing network edges, node clustering (community detection), anomaly identification, and the generation of synthetic data from latent variables.

Models Overview

The package integrates a wide range of probabilistic generative models tailored for various network data types and analytical goals. The following table summarizes the models currently implemented in ProbINet:

Name	Description	Network Properties
CRep	Models directed networks with communities and reciprocity [CSDB22].	Directed, Weighted, Communities, Reciprocity
JointCRep	Captures community structure and reciprocity with a joint edge distribution [SCDB21].	Directed, Communities, Reciprocity
DynCRep	Extends CRep for dynamic networks [SCDB22].	Directed, Weighted, Dynamic, Communities, Reciprocity
ACD	Identifies anomalous edges and node community memberships in weighted networks [SDB22].	Directed, Weighted, Communities, Anomalies
MTCOV	Extracts overlapping communities in multilayer networks using topology and node attributes [CPDB20].	Weighted, Multilayer, Attributes, Communities

For more details on each model, please refer to the documentation. References to the original papers can be found here.

Installation

This package requires Python 3.10 or higher. Please ensure you have one of these versions before proceeding with the installation. To get started, follow these steps:

1. Clone the repository and navigate to the probinet directory:

   git clone https://github.com/MPI-IS/probinet.git
   cd probinet

2. Create a virtual environment. For example, using venv:

   python3 -m venv --copies venv
   . venv/bin/activate
   (venv) pip install -U pip # optional but always advised!

3. Install the ProbINet package by running:

   (venv) pip install probinet

Usage

Run the ProbINet package as a whole with the run_probinet command. This command can be run from any directory after the package is installed.

A list of the parameters that can be passed as arguments is available by running:

    run_probinet --help

To run a specific model, pass the model name as an argument. The available models are: CRep, JointCRep, MTCOV, DynCRep, and ACD. For example, to run the CRep model, use:

    run_probinet CRep

To see the specific options for a model, use the -h flag. For example, to see the options for the CRep model, use:

    run_probinet CRep -h

The run_probinet command can be run at different logging levels. To run the command with the DEBUG level, use:

    run_probinet CRep -d

To set arguments with double dashes (e.g., --convergence_tol), include them in the command line as follows:

    run_probinet CRep --convergence_tol 0.1

Some commands can also be executed using shorter versions of the arguments. For example, the --convergence_tol argument can be shortened to -tol:

    run_probinet CRep -tol 0.1

These shorter versions can be found in the help message of each model.

Tests

To run the tests:

    python -m unittest

Documentation

The documentation can be built locally. First, install the dev extra:

    pip install ".[dev]"

To build the documentation, run:

    cd docs
    make html

The documentation will be available in the docs/build/html directory.

Tutorials

The tutorials are available in the tutorials directory. Each tutorial is a Jupyter notebook that can be run in a Jupyter environment.

Where to start

If you are new to this type of modeling, we suggest checking out the Inputs and Outputs section. This section provides an overview of the input and output data structures used in the package.

Authors

• Diego Baptista Theuerkauf
• Jean-Claude Passy

The authors of the original implementations integrated to this package are:

• Caterina De Bacco
• Martina Contisciani
• Hadiseh Safdari

See the references in the documentation for more details.

Special thanks to Alejandro Posada for his contributions to the logo design. A sincere thank you to Valkyrie Felso and Kathy Su for their invaluable feedback. We also deeply appreciate Kibidi Neocosmos for serving as a beta user and helping refine the package.

Contributing

Would you like to contribute to the development of ProbINet? Contributions are welcome and appreciated! You can find detailed information on how to get started here: Contributing Guide.

License

This project is licensed under the GNU GPL version 3 - see the LICENSE file for details.

Copyright

© 2024, Max Planck Society / Software Workshop - Max Planck Institute for Intelligent Systems