diff --git a/docs/source/conf.py b/docs/source/conf.py index c450bd84..3e6f53b8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,7 +23,7 @@ author = "Emiliano Marchese, Nicolo' Vallarano, Matteo Bruno" # The full version, including alpha/beta/rc tags -release = '2.0.7' +release = '2.1.0' # -- General configuration --------------------------------------------------- diff --git a/setup.py b/setup.py index b7d314bd..b68d6b21 100644 --- a/setup.py +++ b/setup.py @@ -12,7 +12,7 @@ ' matteo.bruno@imtlucca.it', packages=["NEMtropy"], package_dir={'': 'src'}, - version="2.0.7", + version="2.1.0", description="NEMtropy is a Maximum-Entropy toolbox for networks, it" " provides the user with a state of the art solver for a" " range variety of Maximum Entropy Networks models derived" diff --git a/src/NEMtropy.egg-info/PKG-INFO b/src/NEMtropy.egg-info/PKG-INFO index de310049..05f46760 100644 --- a/src/NEMtropy.egg-info/PKG-INFO +++ b/src/NEMtropy.egg-info/PKG-INFO @@ -1,206 +1,13 @@ Metadata-Version: 2.1 Name: NEMtropy -Version: 1.0.5 +Version: 2.0.7 Summary: NEMtropy is a Maximum-Entropy toolbox for networks, it provides the user with a state of the art solver for a range variety of Maximum Entropy Networks models derived from the ERGM family. This module allows you to solve the desired model and generate a number of randomized graphs from the original one: the so-called graphs ensemble. Home-page: https://github.com/nicoloval/NEMtropy/ -Author: Nicolo' Vallarano, Emiliano Marchese -Author-email: nicolo.vallarano@imtlucca.it, emiliano.marchese@imtlucca.it +Download-URL: https://github.com/nicoloval/NEMtropy/archive/refs/tags/v2.0.6.zip +Author: Nicolo' Vallarano, Emiliano Marchese, Matteo Bruno +Author-email: nicolo.vallarano@imtlucca.it, emiliano.marchese@imtlucca.it, matteo.bruno@imtlucca.it License: GNU General Public License v3 -Download-URL: https://github.com/nicoloval/NEMtropy/archive/1.0.5.zip -Description: ![PyPI](https://img.shields.io/pypi/v/nemtropy) - ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/nemtropy) - [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) - [![ArXiv](https://img.shields.io/badge/ArXiv-2101.12625-red)](https://arxiv.org/abs/2101.12625) - - NEMtropy: Network Entropy Maximization, a Toolbox Running On PYthon - ------------------------------------------------------------------- - - NEMtropy is a Maximum-Entropy toolbox for networks, released as a python3 module. - - NEMtropy provides the user with a state of the art solver for a range variety of Maximum Entropy Networks models derived from the ERGM family. - This module allows you to solve the desired model and generate a number of randomized graphs from the original one: the so-called _graphs ensemble_. - - NEMtropy builds on the current literature on the matter, improving both in speed of convergence and in the scale of the feasible networks. - To explore Maximum-Entropy modeling on networks, checkout [Maximum Entropy Hub](https://meh.imtlucca.it/). - - The models implemented in NEMtropy are presented in a forthcoming [paper](https://arxiv.org/abs/2101.12625) on arXiv. - If you use the module for your scientific research, please consider citing us: - - ``` - @misc{vallarano2021fast, - title={Fast and scalable likelihood maximization for Exponential Random Graph Models}, - author={Nicolò Vallarano and Matteo Bruno and Emiliano Marchese and Giuseppe Trapani and Fabio Saracco and Tiziano Squartini and Giulio Cimini and Mario Zanon}, - year={2021}, - eprint={2101.12625}, - archivePrefix={arXiv}, - primaryClass={physics.data-an} - } - ``` - - #### Table Of Contents - - [Currently Implemented Models](#currently-implemented-models) - - [Installation](#installation) - - [Dependencies](#dependencies) - - [A Simple Example](#simple-example) - - [Development](#development) - - [Testing](#testing) - - [Credits](#credits) - - ## Currently Implemented Models - The main feature of NEMtropy is (but not limited to) *network randomization*. - The specific kind of network to randomize and property to preserve defines the model you need: - - * **UBCM** *Undirected Binary Configuration Model* [[1]](#1) - * **UECM** *Undirected Enhanced Configuration Model* [[1]](#1) - * **DBCM** *Directed Binary Configuration Model* [[1]](#1) - * **DECM** *Directed Enhanced Configuration Model* [[1]](#1) - * **CReMa** [[2]](#2) - - The following table may helps you identify the model that fits your needs in function of the type of network you are working with; - for in-depth discussion please see the references. - - [...] | Undirected Graph | Directed Graph - ----- | ---------------- | -------------- - **Binary Graph** | *UBCM* | *DBCM* - **Weighted Graph** | *UECM*, *CReMa* | *DECM*, *CReMa* - - _References_ - - * [1] - Squartini, Tiziano, Rossana Mastrandrea, and Diego Garlaschelli. - "Unbiased sampling of network ensembles." - New Journal of Physics 17.2 (2015): 023052. - https://arxiv.org/abs/1406.1197 - * [2] - Parisi, Federica, Tiziano Squartini, and Diego Garlaschelli. - "A faster horse on a safer trail: generalized inference for the efficient reconstruction of weighted networks." - New Journal of Physics 22.5 (2020): 053053. - https://arxiv.org/abs/1811.09829 - - - Installation - ------------ - - NEMtropy can be installed via pip. You can get it from your terminal: - - ``` - $ pip install NEMtropy - ``` - - If you already install the package and wish to upgrade it, - you can simply type from your terminal: - - ``` - $ pip install NEMtropy --upgrade - ``` - - Dependencies - ------------ - - NEMtropy uses numba library. It can be installed via pip by running - in your terminal the following command: - - ``` - $ pip install numba - ``` - - For python3.5 users the correct command is the following: - - ``` - $ pip install --prefer-binary numba - ``` - - It avoids an error during the installation of llvmlite due to - the absence of its wheel in python3.5. - - Simple Example - -------------- - As an example we solve the UBCM for zachary karate club network. - - ``` - import networkx as nx - from NEMtropy import UndirectedGraph - - G = nx.karate_club_graph() - adj_kar = nx.to_numpy_array(G) - graph = UndirectedGraph(adj_kar) - - graph.solve_tool(model="cm_exp", - method="newton", - initial_guess="random") - ``` - - Given the UBCM model, we can generate ten random copies of zachary's karate club. - - ``` - graph.ensemble_sampler(10, cpu_n=2, output_dir="sample/") - ``` - - These copies are saved as an edgelist, each edgelist can be converted to an - adjacency matrix by running the NEMtropy build graph function. - - ``` - from NEMtropy.network_functions import build_graph_from_edgelist - - edgelist_ens = np.loadtxt("sample/0.txt") - ens_adj = build_graph_from_edgelist(edgelist = edgelist_ens, - is_directed = False, - is_sparse = False, - is_weighted = False) - ``` - - These collection of random adjacency matrices can be used as a null model: - it is enough to compute the expected value of the selected network feature - on the ensemble of matrices and to compare it with its original value. - - To learn more, please read the two ipython notebooks in the examples directory: - one is a study case on a [directed graph](https://github.com/nicoloval/NEMtropy/blob/master/examples/Directed%20Graphs.ipynb), - while the other is on an [undirected graph](https://github.com/nicoloval/NEMtropy/blob/master/examples/Undirected%20Graphs.ipynb). - - Development - ----------- - Please work on a feature branch and create a pull request to the development - branch. If necessary to merge manually do so without fast forward: - - ``` - $ git merge --no-ff myfeature - ``` - - To build a development environment run: - - ``` - $ python3 -m venv venv - $ source venv/bin/activate - $ pip install -e '.[dev]' - ``` - - Testing - ------- - If you want to test the package integrity, you can run the following - bash command from the tests directory: - - ``` - $ bash run_all.sh - ``` - - __P.S.__ _at the moment there may be some problems with the DECM solver functions_ - - Credits - ------- - - _Authors_: - - [Nicolò Vallarano](http://www.imtlucca.it/en/nicolo.vallarano/)(a.k.a. [nicoloval](https://github.com/nicoloval)) - - [Emiliano Marchese](https://www.imtlucca.it/en/emiliano.marchese/) (a.k.a. [EmilianoMarchese](https://github.com/EmilianoMarchese)) - - _Acknowledgements:_ - - The module was developed under the supervision of [Tiziano Squartini](http://www.imtlucca.it/en/tiziano.squartini/), [Mario Zanon](http://www.imtlucca.it/it/mario.zanon/), and [Giulio Cimini](https://www.fisica.uniroma2.it/elenco-telefonico/ciminigi/). - It was developed at [IMT school of advanced studies Lucca](https://www.imtlucca.it/), and financed by the research project Optimized Reconstruction of Complex networkS - ORCS. - -Keywords: Network reconstruction,Networks Null Models,Maximum Entrophy Methods -Platform: UNKNOWN +Keywords: Network reconstruction,Networks Null Models,Maximum Entropy Methods Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL) Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.5 @@ -209,3 +16,215 @@ Classifier: Programming Language :: Python :: 3.7 Classifier: Programming Language :: Python :: 3.8 Description-Content-Type: text/markdown Provides-Extra: dev +License-File: LICENSE.txt + +![PyPI](https://img.shields.io/pypi/v/nemtropy) +![PyPI - Python Version](https://img.shields.io/pypi/pyversions/nemtropy) +[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) +[![ArXiv](https://img.shields.io/badge/ArXiv-2101.12625-red)](https://arxiv.org/abs/2101.12625) + +NEMtropy: Network Entropy Maximization, a Toolbox Running On PYthon +------------------------------------------------------------------- + +NEMtropy is a Maximum-Entropy toolbox for networks, released as a python3 module. + +NEMtropy provides the user with a state of the art solver for a range variety of Maximum Entropy Networks models derived from the ERGM family. +This module allows you to solve the desired model and generate a number of randomized graphs from the original one: the so-called _graphs ensemble_. + +NEMtropy builds on the current literature on the matter, improving both in speed of convergence and in the scale of the feasible networks. +To explore Maximum-Entropy modeling on networks, checkout [Maximum Entropy Hub](https://meh.imtlucca.it/). + +The models implemented in NEMtropy are presented in a forthcoming [paper](https://arxiv.org/abs/2101.12625) on arXiv. +If you use the module for your scientific research, please consider citing us: + +``` + @misc{vallarano2021fast, + title={Fast and scalable likelihood maximization for Exponential Random Graph Models}, + author={Nicolò Vallarano and Matteo Bruno and Emiliano Marchese and Giuseppe Trapani and Fabio Saracco and Tiziano Squartini and Giulio Cimini and Mario Zanon}, + year={2021}, + eprint={2101.12625}, + archivePrefix={arXiv}, + primaryClass={physics.data-an} + } +``` + +#### Table Of Contents +- [Currently Implemented Models](#currently-implemented-models) +- [Installation](#installation) +- [Dependencies](#dependencies) +- [A Simple Example](#simple-example) +- [Documentation](#documentation) +- [Development](#development) +- [Testing](#testing) +- [Credits](#credits) + +## Currently Implemented Models +The main feature of NEMtropy is (but not limited to) *network randomization*. +The specific kind of network to randomize and property to preserve defines the model you need: + +* **UBCM** *Undirected Binary Configuration Model* [[1]](#1) +* **UECM** *Undirected Enhanced Configuration Model* [[1]](#1) +* **DBCM** *Directed Binary Configuration Model* [[1]](#1) +* **DECM** *Directed Enhanced Configuration Model* [[1]](#1) +* **CReMa** [[2]](#2) +* **BiCM** *Bipartite Configuration Model* [[3]](#3) + +The following table may helps you identify the model that fits your needs in function of the type of network you are working with; +for in-depth discussion please see the references. + +[...] | Undirected Graph | Directed Graph | Bipartite Graph +----- | ---------------- | -------------- | -------------- +**Binary Graph** | *UBCM* | *DBCM* | *BiCM* +**Weighted Graph** | *UECM*, *CReMa* | *DECM*, *CReMa* | - + +The BiCM module is also available as [a standalone package](https://github.com/mat701/BiCM), find its docs [here](https://bipartite-configuration-model.readthedocs.io/en/latest/). + +_References_ + +* [1] + Squartini, Tiziano, Rossana Mastrandrea, and Diego Garlaschelli. + "Unbiased sampling of network ensembles." + New Journal of Physics 17.2 (2015): 023052. + https://arxiv.org/abs/1406.1197 +* [2] + Parisi, Federica, Tiziano Squartini, and Diego Garlaschelli. + "A faster horse on a safer trail: generalized inference for the efficient reconstruction of weighted networks." + New Journal of Physics 22.5 (2020): 053053. + https://arxiv.org/abs/1811.09829 +* [3] + Saracco, Fabio, Riccardo Di Clemente, Andrea Gabrielli, and Tiziano Squartini. + "Randomizing bipartite networks: the case of the World Trade Web." + Scientific reports 5, no. 1 (2015): 1-18. + https://doi.org/10.1038/srep10595 + + +Installation +------------ + +NEMtropy can be installed via pip. You can get it from your terminal: + +``` + $ pip install NEMtropy +``` + +If you already install the package and wish to upgrade it, +you can simply type from your terminal: + +``` + $ pip install NEMtropy --upgrade +``` + +Dependencies +------------ + +NEMtropy uses numba and powerlaw libraries. They can be installed via pip by running in your terminal the following command: + +``` + $ pip install numba + $ pip install powerlaw +``` + +For python3.5 users the correct command is the following: + +``` + $ pip install --prefer-binary numba +``` + +It avoids an error during the installation of llvmlite due to +the absence of its wheel in python3.5. + +Simple Example +-------------- +As an example we solve the UBCM for zachary karate club network. + +``` + import numpy as np + import networkx as nx + from NEMtropy import UndirectedGraph + + G = nx.karate_club_graph() + adj_kar = nx.to_numpy_array(G) + graph = UndirectedGraph(adj_kar) + + graph.solve_tool(model="cm_exp", + method="newton", + initial_guess="random") +``` + +Given the UBCM model, we can generate ten random copies of zachary's karate club. + +``` + graph.ensemble_sampler(10, cpu_n=2, output_dir="sample/") +``` + +These copies are saved as an edgelist, each edgelist can be converted to an +adjacency matrix by running the NEMtropy build graph function. + +``` + from NEMtropy.network_functions import build_adjacency_from_edgelist + + edgelist_ens = np.loadtxt("sample/0.txt") + ens_adj = build_adjacency_from_edgelist(edgelist = edgelist_ens, + is_directed = False, + is_sparse = False, + is_weighted = False) +``` + +These collections of random adjacency matrices can be used as a null model: +it is enough to compute the expected value of the selected network feature +on the ensemble of matrices and to compare it with its original value. + +To learn more, please read the ipython notebooks in the examples directory: +- one is a study case on a [directed graph](https://github.com/nicoloval/NEMtropy/blob/master/examples/Directed%20Graphs.ipynb), +- while the other is on an [undirected graph](https://github.com/nicoloval/NEMtropy/blob/master/examples/Undirected%20Graphs.ipynb). +- There is also one on motifs!!! [motifs](https://github.com/nicoloval/NEMtropy/blob/c4283e6b939274f532278cd84841656b20d819a4/examples/Motifs.ipynb). + + +Documentation +------------- + +You can find complete documentation about NEMtropy library in [docs](https://nemtropy.readthedocs.io/en/master/index.html). + +Development +----------- +Please work on a feature branch and create a pull request to the development +branch. If necessary to merge manually do so without fast-forward: + +``` + $ git merge --no-ff myfeature +``` + +To build a development environment run: + +``` + $ python3 -m venv venv + $ source venv/bin/activate + $ pip install -e '.[dev]' +``` + +Testing +------- +If you want to test the package integrity, you can run the following +bash command from the tests' directory: + +``` + $ bash run_all.sh +``` + +__P.S.__ _at the moment there may be some problems with the DECM solver functions_ + +Credits +------- + +_Authors_: + +[Nicolò Vallarano](http://www.imtlucca.it/en/nicolo.vallarano/) (a.k.a. [nicoloval](https://github.com/nicoloval)) + +[Emiliano Marchese](https://www.imtlucca.it/en/emiliano.marchese/) (a.k.a. [EmilianoMarchese](https://github.com/EmilianoMarchese)) + +[Matteo Bruno](https://www.imtlucca.it/en/matteo.bruno/) (BiCM) (a.k.a. [mat701](https://github.com/mat701)) + +_Acknowledgements:_ + +The module was developed under the supervision of [Tiziano Squartini](http://www.imtlucca.it/en/tiziano.squartini/), [Fabio Saracco](http://www.imtlucca.it/en/fabio.saracco/), [Mario Zanon](http://www.imtlucca.it/it/mario.zanon/), and [Giulio Cimini](https://www.fisica.uniroma2.it/elenco-telefonico/ciminigi/). +It was developed at [IMT school of advanced studies Lucca](https://www.imtlucca.it/), and financed by the research project Optimized Reconstruction of Complex networkS - ORCS. diff --git a/src/NEMtropy.egg-info/SOURCES.txt b/src/NEMtropy.egg-info/SOURCES.txt index 3856264b..e733d153 100644 --- a/src/NEMtropy.egg-info/SOURCES.txt +++ b/src/NEMtropy.egg-info/SOURCES.txt @@ -1,26 +1,17 @@ +LICENSE.txt README.md setup.py src/NEMtropy/__init__.py +src/NEMtropy/ensemble_functions.py src/NEMtropy/ensemble_generator.py src/NEMtropy/graph_classes.py src/NEMtropy/matrix_generator.py src/NEMtropy/models_functions.py src/NEMtropy/network_functions.py +src/NEMtropy/poibin.py src/NEMtropy/solver_functions.py src/NEMtropy.egg-info/PKG-INFO src/NEMtropy.egg-info/SOURCES.txt src/NEMtropy.egg-info/dependency_links.txt src/NEMtropy.egg-info/requires.txt -src/NEMtropy.egg-info/top_level.txt -src/nemtropy/__init__.py -src/nemtropy/ensemble_generator.py -src/nemtropy/graph_classes.py -src/nemtropy/matrix_generator.py -src/nemtropy/models_functions.py -src/nemtropy/network_functions.py -src/nemtropy/solver_functions.py -src/nemtropy.egg-info/PKG-INFO -src/nemtropy.egg-info/SOURCES.txt -src/nemtropy.egg-info/dependency_links.txt -src/nemtropy.egg-info/requires.txt -src/nemtropy.egg-info/top_level.txt \ No newline at end of file +src/NEMtropy.egg-info/top_level.txt \ No newline at end of file diff --git a/src/NEMtropy.egg-info/requires.txt b/src/NEMtropy.egg-info/requires.txt index d957ac9a..07455f39 100644 --- a/src/NEMtropy.egg-info/requires.txt +++ b/src/NEMtropy.egg-info/requires.txt @@ -1,7 +1,8 @@ numpy>=1.17 scipy>=1.4 networkx>=2.4 -powerlaw>=1.4tqdm>=4.5 +powerlaw>=1.4 +tqdm>=4.5 [dev] pytest>=6.0.1 diff --git a/src/NEMtropy/__init__.py b/src/NEMtropy/__init__.py index d286459a..8da76066 100644 --- a/src/NEMtropy/__init__.py +++ b/src/NEMtropy/__init__.py @@ -3,7 +3,7 @@ from .ensemble_generator import * from .models_functions import * -__version__ = "2.0.7" +__version__ = "2.1.0" __author__ = """Nicolo' Vallarano (nicolo.vallarano@imtlucca.it) Emiliano Marchese (emiliano.marchese@imtlucca.it) Matteo Bruno (matteo.bruno@imtlucca.it)"""