ProbINet

ProbINet#

Python PyPI version Build Status Code Style: Black Typed

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

MTCOV

Extracts overlapping communities in multilayer networks using topology and node attributes [CPDB20].

Weighted, Multilayer, Attributes, Communities

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

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

  1. 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!

  1. 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. For example:

    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#

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

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.

References#

[CPDB20]

Martina Contisciani, Eleanor A Power, and Caterina De Bacco. Community detection with node attributes in multilayer networks. Scientific reports, 10(1):15736, 2020.

[CSDB22]

Martina Contisciani, Hadiseh Safdari, and Caterina De Bacco. Community detection and reciprocity in networks by jointly modeling pairs of edges. Journal of Complex Networks, 10(4):cnac034, 2022.

[SCDB21]

Hadiseh Safdari, Martina Contisciani, and Caterina De Bacco. Generative model for reciprocity and community detection in networks. Physical Review Research, 3(2):023209, 2021.

[SCDB22]

Hadiseh Safdari, Martina Contisciani, and Caterina De Bacco. Reciprocity, community detection, and link prediction in dynamic networks. Journal of Physics: Complexity, 3(1):015010, 2022.

[SDB22]

Hadiseh Safdari and Caterina De Bacco. Anomaly detection and community detection in networks. Journal of Big Data, 9(1):122, 2022.

Thank you for choosing ProbINet. We hope you enjoy using it!

Contents

First Steps

Tutorials

Contributing

References

Indices and tables#

Contents