[](https://www.gnu.org/licenses/gpl-3.0)
[](https://doi.org/10.1038/s41598-021-93830-4)
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/).
If you use the module for your scientific research, please consider citing us:
```
@article{vallarano2021fast,
title={Fast and scalable likelihood maximization for exponential random graph models with local constraints},
author={Vallarano, Nicol{\`o} and Bruno, Matteo and Marchese, Emiliano and Trapani, Giuseppe and Saracco, Fabio and Cimini, Giulio and Zanon, Mario and Squartini, Tiziano},
journal={Scientific Reports},
volume={11},
number={1},
pages={15227},
year={2021},
publisher={Nature Publishing Group UK London}
}
```
#### 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)
* **BiWCM** *Bipartite Weighted Configuration Model* [[4]](#4)
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* | *BiWCM*
The BiCM module is now (NEMtropy>=3.0.0) imported and it is mantained as a [a standalone package](https://github.com/mat701/BiCM), find its docs [here](https://bipartite-configuration-model.readthedocs.io/en/latest/).
_References_
* <a id="1">[1]</a>
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
* <a id="2">[2]</a>
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
* <a id="3">[3]</a>
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
* <a id="4">[4]</a>
Bruno, Matteo, Dario Mazzilli, Aurelio Patelli, Tiziano Squartini, and Fabio Saracco.
"Inferring comparative advantage via entropy maximization."
Journal of Physics: Complexity, Volume 4, Number 4 (2023).
https://doi.org/10.1088/2632-072X/ad1411
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 <code>numba</code>, <code>powerlaw</code>, <code>tqdm</code>, <code>scipy</code>, <code>networkx</code>, <code>bicm</code> libraries. They can be installed via pip by running in your terminal the following command:
```
$ pip install numba
$ pip install powerlaw
$ pip install networkx
$ pip install scipy
$ pip install tqdm
$ pip install bicm
```
For <code>python3.5</code> users the correct command is the following:
```
$ pip install --prefer-binary numba
```
It avoids an error during the installation of <code>llvmlite</code> due to
the absence of its wheel in <code>python3.5</code>.
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](https://www.ifi.uzh.ch/en/bdlt/Team/Postdocs/Dr.-Vallarano-Nicol%C3%B2.html) (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://csl.sony.it/member/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](https://mariozanon.wordpress.com/), 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/nicoloval/NEMtropy/",
"name": "NEMtropy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Network reconstruction, Networks Null Models, Maximum Entropy Methods",
"author": "Nicolo' Vallarano, Emiliano Marchese, Matteo Bruno",
"author_email": "nico.vallarano@gmail.com, emilianomarcheserc@gmail.com, matteobruno180@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/04/63/3713a753beb82e25943414a67ca77824f546d224f3e7c0b2e5b637f3f30b/NEMtropy-3.0.3.tar.gz",
"platform": null,
"description": "\n\n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://doi.org/10.1038/s41598-021-93830-4)\n\nNEMtropy: Network Entropy Maximization, a Toolbox Running On PYthon\n-------------------------------------------------------------------\n\nNEMtropy is a Maximum-Entropy toolbox for networks, released as a python3 module. \n\nNEMtropy provides the user with a state of the art solver for a range variety of Maximum Entropy Networks models derived from the ERGM family.\nThis module allows you to solve the desired model and generate a number of randomized graphs from the original one: the so-called _graphs ensemble_.\n\nNEMtropy builds on the current literature on the matter, improving both in speed of convergence and in the scale of the feasible networks.\nTo explore Maximum-Entropy modeling on networks, checkout [Maximum Entropy Hub](https://meh.imtlucca.it/).\n\nIf you use the module for your scientific research, please consider citing us:\n\n```\n@article{vallarano2021fast,\n title={Fast and scalable likelihood maximization for exponential random graph models with local constraints},\n author={Vallarano, Nicol{\\`o} and Bruno, Matteo and Marchese, Emiliano and Trapani, Giuseppe and Saracco, Fabio and Cimini, Giulio and Zanon, Mario and Squartini, Tiziano},\n journal={Scientific Reports},\n volume={11},\n number={1},\n pages={15227},\n year={2021},\n publisher={Nature Publishing Group UK London}\n}\n\n```\n\n#### Table Of Contents\n- [Currently Implemented Models](#currently-implemented-models)\n- [Installation](#installation)\n- [Dependencies](#dependencies)\n- [A Simple Example](#simple-example)\n- [Documentation](#documentation)\n- [Development](#development)\n- [Testing](#testing)\n- [Credits](#credits)\n\n## Currently Implemented Models\nThe main feature of NEMtropy is (but not limited to) *network randomization*. \nThe specific kind of network to randomize and property to preserve defines the model you need:\n\n* **UBCM** *Undirected Binary Configuration Model* [[1]](#1)\n* **UECM** *Undirected Enhanced Configuration Model* [[1]](#1)\n* **DBCM** *Directed Binary Configuration Model* [[1]](#1)\n* **DECM** *Directed Enhanced Configuration Model* [[1]](#1)\n* **CReMa** [[2]](#2)\n* **BiCM** *Bipartite Configuration Model* [[3]](#3)\n* **BiWCM** *Bipartite Weighted Configuration Model* [[4]](#4)\n\nThe following table may helps you identify the model that fits your needs in function of the type of network you are working with;\nfor in-depth discussion please see the references.\n\n[...] | Undirected Graph | Directed Graph | Bipartite Graph\n----- | ---------------- | -------------- | --------------\n**Binary Graph** | *UBCM* | *DBCM* | *BiCM*\n**Weighted Graph** | *UECM*, *CReMa* | *DECM*, *CReMa* | *BiWCM*\n\nThe BiCM module is now (NEMtropy>=3.0.0) imported and it is mantained as a [a standalone package](https://github.com/mat701/BiCM), find its docs [here](https://bipartite-configuration-model.readthedocs.io/en/latest/). \n\n_References_\n\n* <a id=\"1\">[1]</a>\n Squartini, Tiziano, Rossana Mastrandrea, and Diego Garlaschelli.\n \"Unbiased sampling of network ensembles.\"\n New Journal of Physics 17.2 (2015): 023052.\n https://arxiv.org/abs/1406.1197\n* <a id=\"2\">[2]</a>\n Parisi, Federica, Tiziano Squartini, and Diego Garlaschelli.\n \"A faster horse on a safer trail: generalized inference for the efficient reconstruction of weighted networks.\"\n New Journal of Physics 22.5 (2020): 053053.\n https://arxiv.org/abs/1811.09829\n* <a id=\"3\">[3]</a>\n Saracco, Fabio, Riccardo Di Clemente, Andrea Gabrielli, and Tiziano Squartini.\n\t\"Randomizing bipartite networks: the case of the World Trade Web.\" \n\tScientific reports 5, no. 1 (2015): 1-18.\n https://doi.org/10.1038/srep10595\n* <a id=\"4\">[4]</a>\n Bruno, Matteo, Dario Mazzilli, Aurelio Patelli, Tiziano Squartini, and Fabio Saracco.\n \"Inferring comparative advantage via entropy maximization.\"\n Journal of Physics: Complexity, Volume 4, Number 4 (2023).\n https://doi.org/10.1088/2632-072X/ad1411\n\nInstallation\n------------\n\nNEMtropy can be installed via pip. You can get it from your terminal:\n\n```\n $ pip install NEMtropy\n```\n\nIf you already install the package and wish to upgrade it,\nyou can simply type from your terminal:\n\n```\n $ pip install NEMtropy --upgrade\n```\n\nDependencies\n------------\n\nNEMtropy uses <code>numba</code>, <code>powerlaw</code>, <code>tqdm</code>, <code>scipy</code>, <code>networkx</code>, <code>bicm</code> libraries. They can be installed via pip by running in your terminal the following command:\n\n```\n $ pip install numba\n $ pip install powerlaw\n $ pip install networkx\n $ pip install scipy\n $ pip install tqdm\n $ pip install bicm\n```\n\nFor <code>python3.5</code> users the correct command is the following:\n\n```\n $ pip install --prefer-binary numba\n```\n\nIt avoids an error during the installation of <code>llvmlite</code> due to \nthe absence of its wheel in <code>python3.5</code>.\n\nSimple Example\n--------------\nAs an example we solve the UBCM for zachary karate club network.\n\n```\n import numpy as np\n import networkx as nx\n from NEMtropy import UndirectedGraph\n\n G = nx.karate_club_graph()\n adj_kar = nx.to_numpy_array(G)\n graph = UndirectedGraph(adj_kar)\n\n graph.solve_tool(model=\"cm_exp\",\n method=\"newton\",\n initial_guess=\"random\")\n```\n\nGiven the UBCM model, we can generate ten random copies of zachary's karate club.\n\n```\n graph.ensemble_sampler(10, cpu_n=2, output_dir=\"sample/\")\n```\n\nThese copies are saved as an edgelist, each edgelist can be converted to an\nadjacency matrix by running the NEMtropy build graph function.\n\n```\n from NEMtropy.network_functions import build_adjacency_from_edgelist\n\n edgelist_ens = np.loadtxt(\"sample/0.txt\")\n ens_adj = build_adjacency_from_edgelist(edgelist = edgelist_ens,\n is_directed = False,\n is_sparse = False,\n is_weighted = False)\n```\n\nThese collections of random adjacency matrices can be used as a null model:\nit is enough to compute the expected value of the selected network feature \non the ensemble of matrices and to compare it with its original value.\n\nTo learn more, please read the ipython notebooks in the examples directory:\n- one is a study case on a [directed graph](https://github.com/nicoloval/NEMtropy/blob/master/examples/Directed%20Graphs.ipynb), \n- while the other is on an [undirected graph](https://github.com/nicoloval/NEMtropy/blob/master/examples/Undirected%20Graphs.ipynb).\n- There is also one on motifs!!! [motifs](https://github.com/nicoloval/NEMtropy/blob/c4283e6b939274f532278cd84841656b20d819a4/examples/Motifs.ipynb).\n\n\nDocumentation\n-------------\n\nYou can find complete documentation about NEMtropy library in [docs](https://nemtropy.readthedocs.io/en/master/index.html).\n\nDevelopment\n-----------\nPlease work on a feature branch and create a pull request to the development \nbranch. If necessary to merge manually do so without fast-forward:\n\n```\n $ git merge --no-ff myfeature\n```\n\nTo build a development environment run:\n\n```\n $ python3 -m venv venv \n $ source venv/bin/activate \n $ pip install -e '.[dev]'\n```\n\nTesting\n-------\nIf you want to test the package integrity, you can run the following \nbash command from the tests' directory:\n\n```\n $ bash run_all.sh\n```\n\n__P.S.__ _at the moment there may be some problems with the DECM solver functions_\n\nCredits\n-------\n\n_Authors_:\n\n[Nicol\u00f2 Vallarano](https://www.ifi.uzh.ch/en/bdlt/Team/Postdocs/Dr.-Vallarano-Nicol%C3%B2.html) (a.k.a. [nicoloval](https://github.com/nicoloval))\n\n[Emiliano Marchese](https://www.imtlucca.it/en/emiliano.marchese/) (a.k.a. [EmilianoMarchese](https://github.com/EmilianoMarchese))\n\n[Matteo Bruno](https://csl.sony.it/member/matteo-bruno/) (BiCM) (a.k.a. [mat701](https://github.com/mat701))\n\n_Acknowledgements:_\n\nThe 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](https://mariozanon.wordpress.com/), and [Giulio Cimini](https://www.fisica.uniroma2.it/elenco-telefonico/ciminigi/).\nIt 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.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3",
"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.",
"version": "3.0.3",
"project_urls": {
"Download": "https://github.com/nicoloval/NEMtropy/archive/refs/tags/v2.1.1.zip",
"Homepage": "https://github.com/nicoloval/NEMtropy/"
},
"split_keywords": [
"network reconstruction",
" networks null models",
" maximum entropy methods"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a7ad4d13bc5e88f2b855b279ebeb8e0b090f2bbd7832c065b2cb7869cb947684",
"md5": "3fe508743fa4bbb5112215f9bfd4eeff",
"sha256": "b6d03751e3bc966551ea706ba5cea1466781509aab3122bbe37b19e0de2d26a3"
},
"downloads": -1,
"filename": "NEMtropy-3.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3fe508743fa4bbb5112215f9bfd4eeff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 51313,
"upload_time": "2024-06-17T13:32:00",
"upload_time_iso_8601": "2024-06-17T13:32:00.155940Z",
"url": "https://files.pythonhosted.org/packages/a7/ad/4d13bc5e88f2b855b279ebeb8e0b090f2bbd7832c065b2cb7869cb947684/NEMtropy-3.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "04633713a753beb82e25943414a67ca77824f546d224f3e7c0b2e5b637f3f30b",
"md5": "f15f502493d022dac59e277ac069f398",
"sha256": "d598f45578272e26b51908be34ac0ec8ba4f674431848db325ab2e3a58e27c37"
},
"downloads": -1,
"filename": "NEMtropy-3.0.3.tar.gz",
"has_sig": false,
"md5_digest": "f15f502493d022dac59e277ac069f398",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 66347,
"upload_time": "2024-06-17T13:32:02",
"upload_time_iso_8601": "2024-06-17T13:32:02.504659Z",
"url": "https://files.pythonhosted.org/packages/04/63/3713a753beb82e25943414a67ca77824f546d224f3e7c0b2e5b637f3f30b/NEMtropy-3.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-17 13:32:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nicoloval",
"github_project": "NEMtropy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": [
[
"~=",
"1.20.1"
]
]
},
{
"name": "scipy",
"specs": [
[
"~=",
"1.6.0"
]
]
},
{
"name": "networkx",
"specs": [
[
"~=",
"2.5"
]
]
},
{
"name": "powerlaw",
"specs": [
[
"~=",
"1.4.6"
]
]
},
{
"name": "numba",
"specs": [
[
"~=",
"0.52.0"
]
]
},
{
"name": "NEMtropy",
"specs": [
[
"~=",
"1.0.5"
]
]
},
{
"name": "setuptools",
"specs": [
[
"~=",
"51.1.2"
]
]
},
{
"name": "Pillow",
"specs": [
[
"~=",
"8.1.0"
]
]
},
{
"name": "pip",
"specs": [
[
"~=",
"20.3.3"
]
]
},
{
"name": "wheel",
"specs": [
[
"~=",
"0.36.2"
]
]
},
{
"name": "six",
"specs": [
[
"~=",
"1.15.0"
]
]
},
{
"name": "llvmlite",
"specs": [
[
"~=",
"0.35.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"~=",
"3.3.4"
]
]
},
{
"name": "mpmath",
"specs": [
[
"~=",
"1.2.1"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"~=",
"2.8.1"
]
]
},
{
"name": "decorator",
"specs": [
[
"~=",
"4.4.2"
]
]
},
{
"name": "pyparsing",
"specs": [
[
"~=",
"2.4.7"
]
]
},
{
"name": "cycler",
"specs": [
[
"~=",
"0.10.0"
]
]
},
{
"name": "kiwisolver",
"specs": [
[
"~=",
"1.3.1"
]
]
},
{
"name": "bicm",
"specs": [
[
">=",
"3.2.0"
]
]
}
],
"lcname": "nemtropy"
}
JSON
