bicm 3.5.0

BiCM package

This is a Python package for the computation of the maximum entropy bipartite configuration model (BiCM) and the projection of bipartite networks on one layer. It requires Python 3.10 or later.

You can install this package via pip:

pip install bicm

Documentation is available at https://bipartite-configuration-model.readthedocs.io/en/latest/ .

This package is also a module of NEMtropy that you can find at https://github.com/nicoloval/NEMtropy .

For more solvers of maximum entropy configuration models visit https://meh.imtlucca.it/ .

NOTE of the developer: there was an error in the projection threshold, validating less links than it should have. Please re-run your analysis after updating to the last version (>=3.1)

Basic functionalities

To install:

pip install bicm

To import the module:

import bicm

To generate a Graph object and initialize it (with a biadjacency matrix, edgelist or degree sequences):

from bicm import BipartiteGraph
myGraph = BipartiteGraph()
myGraph.set_biadjacency_matrix(my_biadjacency_matrix)
myGraph.set_adjacency_list(my_adjacency_list)
myGraph.set_edgelist(my_edgelist)
myGraph.set_degree_sequences((first_degree_sequence, second_degree_sequence))

Or alternatively, with the respective data structure as input:

from bicm import BipartiteGraph
myGraph = BipartiteGraph(biadjacency=my_biadjacency_matrix, adjacency_list=my_adjacency_list, edgelist=my_edgelist, degree_sequences=((first_degree_sequence, second_degree_sequence)))

To compute the BiCM probability matrix of the graph or the relative fitnesses coefficients as dictionaries containing the nodes names as keys:

my_probability_matrix = myGraph.get_bicm_matrix()
my_x, my_y = myGraph.get_bicm_fitnesses()

This will solve the bicm using recommended settings for the solver. To customize the solver you can alternatively use (in advance) the following method:

myGraph.solve_tool(light_mode=False, method='newton', initial_guess=None, tol=1e-8, max_steps=None, verbose=False, linsearch=True, regularise=False, print_error=True, exp=False)

To get the rows or columns projection of the graph:

myGraph.get_rows_projection()
myGraph.get_cols_projection()

Alternatively, to customize the projection:

myGraph.compute_projection(rows=True, alpha=0.05, approx_method='poisson', threads_num=4, progress_bar=True)

Warnings, logging and reproducibility

Problems found while solving or projecting (for example a solver that did not converge) are reported as Python warnings of category bicm.BiCMWarning, so they can be filtered:

import warnings
import bicm
warnings.filterwarnings("ignore", category=bicm.BiCMWarning)

Informative messages (for example "Computing the BiCM...") go to the bicm logger and are hidden by default. To show them:

import logging
logging.basicConfig()
logging.getLogger("bicm").setLevel(logging.INFO)

The sampling functions accept a seed argument (an integer or a numpy.random.Generator) to get reproducible samples, e.g. sample_bicm(avg_mat, seed=42). Without it, numpy's global random state is used as in previous versions.

Projections use several processes by default. On macOS, scripts must put their code under if __name__ == "__main__": for this to work, or pass threads_num=1. On Windows projections always run in a single process.

Now version 3 is online, and you can use the package with weighted networks as well using the BiWCM models!

See a more detailed walkthrough in tests/bicm_test or tests/biwcm_test notebooks, or check out the API in the documentation.

Development

To install the package from source together with the test dependencies and run the test suite:

pip install -e ".[test]"
pytest

The tests run automatically on GitHub Actions for every push and pull request. A new version is published to PyPI when a GitHub release is created with a tag matching the package version (e.g. v3.5.0).

How to cite

If you use the bicm module, please cite its location on Github https://github.com/mat701/BiCM and the original articles [Vallarano2021], [Saracco2015] and [Saracco2017].

If you use the weighted models (BiWCM_c or BiWCM_d), please also cite [Bruno2023].

References

[Vallarano2021] N. Vallarano, M. Bruno, E. Marchese, G. Trapani, F. Saracco, T. Squartini, G. Cimini, M. Zanon, Fast and scalable likelihood maximization for Exponential Random Graph Models with local constraints, Nature Scientific Reports

[Bruno2023] M. Bruno, D. Mazzilli, A. Patelli, T. Squartini, F. Saracco, Inferring comparative advantage via entropy maximization. J. Phys. Complex. 4, 045011 (2023), doi:10.1088/2632-072X/ad1411

[Saracco2015] F. Saracco, R. Di Clemente, A. Gabrielli, T. Squartini, Randomizing bipartite networks: the case of the World Trade Web, Scientific Reports 5, 10595 (2015).

[Saracco2017] F. Saracco, M. J. Straka, R. Di Clemente, A. Gabrielli, G. Caldarelli, and T. Squartini, Inferring monopartite projections of bipartite networks: an entropy-based approach, New J. Phys. 19, 053022 (2017)

Author:

Matteo Bruno (BiCM) (a.k.a. mat701)