Merge branch 'master' into stable

nicoloval · Mar 31, 2021 · 8a08a6a · 8a08a6a
2 parents a1bb7a6 + 117f3d6
commit 8a08a6a
Show file tree

Hide file tree

Showing 13 changed files with 465 additions and 366 deletions.
diff --git a/README.md b/README.md
@@ -143,13 +143,13 @@ 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)
+    ens_adj = build_adjacency_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:
+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.
 
@@ -162,7 +162,7 @@ You can find complete documentation about NEMtropy library in [docs](https://nem
 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:
+branch. If necessary to merge manually do so without fast-forward:
 
 ```
     $ git merge --no-ff myfeature
@@ -179,7 +179,7 @@ To build a development environment run:
 Testing
 -------
 If you want to test the package integrity, you can run the following 
-bash command from the tests directory:
+bash command from the tests' directory:
 
 ```
     $ bash run_all.sh

diff --git a/docs/source/NEMtropy.rst b/docs/source/NEMtropy.rst
@@ -36,3 +36,9 @@ Network functions
 
 .. automodule:: NEMtropy.network_functions
     :members:
+
+Poibin class
+-----------------
+
+.. automodule:: NEMtropy.poibin
+    :members:
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -19,11 +19,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'NEMtropy'
-copyright = "2021, Emiliano Marchese and Nicolo' Vallarano"
-author = "Emiliano Marchese, Nicolo' Vallarano"
+copyright = "2021, Emiliano Marchese, Nicolo' Vallarano and Matteo Bruno"
+author = "Emiliano Marchese, Nicolo' Vallarano, Matteo Bruno"
 
 # The full version, including alpha/beta/rc tags
-release = '2.0.1'
+release = '2.0.3'
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -42,18 +42,21 @@ to preserve defines the model you need:
 -  **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    |
-+======================+====================+===================+
-| **Binary Graph**     | *UBCM*             | *DBCM*            |
-+----------------------+--------------------+-------------------+
-| **Weighted Graph**   | *UECM*, *CReMa*    | *DECM*, *CReMa*   |
-+----------------------+--------------------+-------------------+
++----------------------+--------------------+-------------------+-------------------+
+| [...]                | 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*
 
@@ -64,6 +67,9 @@ in-depth discussion please see the references.
    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

diff --git a/examples/Directed Graphs.ipynb b/examples/Directed Graphs.ipynb
diff --git a/examples/Undirected Graphs.ipynb b/examples/Undirected Graphs.ipynb
@@ -2,7 +2,7 @@
  "cells": [
   {
    "source": [
-    "The aim of the notebook is to help you to take confidence with the undirected graph class of NEMtropy. We will guide you through the functionality of the module and they can be use to reconstruct a network given partial information or to generate a null model given a certain network.\n",
+    "The aim of the notebook is to help you to take confidence with the undirected graph class of NEMtropy. We will guide you through the functionality of the module, and how they can be use to reconstruct a network given partial information or to generate a null model given a certain network.\n",
     "For more detail about the theory behind this, we suggest you to read ....."
    ],
    "cell_type": "markdown",
@@ -17,34 +17,13 @@
     "import numpy as np\n",
     "import networkx as nx\n",
     "from NEMtropy import UndirectedGraph, matrix_generator\n",
-    "from NEMtropy.network_functions import build_graph_from_edgelist"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 2,
-   "metadata": {},
-   "outputs": [
-    {
-     "output_type": "error",
-     "ename": "ModuleNotFoundError",
-     "evalue": "No module named 'nemtropy'",
-     "traceback": [
-      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
-      "\u001b[0;31mModuleNotFoundError\u001b[0m                       Traceback (most recent call last)",
-      "\u001b[0;32m<ipython-input-2-10883947ec78>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;32mimport\u001b[0m \u001b[0mnemtropy\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
-      "\u001b[0;31mModuleNotFoundError\u001b[0m: No module named 'nemtropy'"
-     ]
-    }
-   ],
-   "source": [
-    "import nemtropy"
+    "from NEMtropy.network_functions import build_adjacency_from_edgelist"
    ]
   },
   {
    "source": [
     "According to the type of undirected graph, the available models can be divided in:\n",
-    " - models for binary network: \"cm\" and \"cm_exp\"\n",
+    " - models for binary networks: \"cm\" and \"cm_exp\"\n",
     " - models for weighted networks: \"crema\", \"ecm\" and \"ecm_exp\"\n",
     "\n",
     "We will make some examples about both classes of models, lets start from binary models."
@@ -76,7 +55,7 @@
   },
   {
    "source": [
-    "UndirectedGraph instance can be initialised using adjacency matrix, edgelist or degree and strength sequences. As an example we initialise a graph instance using the adjacency matrix."
+    "UndirectedGraph instance can be initialised using adjacency matrix, edgelist or degree and strength sequences. As an example, we initialise a graph instance using the adjacency matrix."
    ],
    "cell_type": "markdown",
    "metadata": {}
@@ -92,7 +71,7 @@
   },
   {
    "source": [
-    "When you use an initiliasition instance that isn't the adjacency matrix you must specify what you are passing to UndirectedGraph. As an exaple we can use the edgelist."
+    "When you use an initiliasition instance that isn't the adjacency matrix, you must specify what you are passing to UndirectedGraph: for exaple an edgelist."
    ],
    "cell_type": "markdown",
    "metadata": {}
@@ -198,10 +177,10 @@
     "edgelist_ens = np.loadtxt(\"sample/0.txt\")\n",
     "\n",
     "# and build the adjacency matrix\n",
-    "ens_adj = build_graph_from_edgelist(edgelist = edgelist_ens,\n",
-    "                                    is_directed = False,\n",
-    "                                    is_sparse = False,\n",
-    "                                    is_weighted = False)"
+    "ens_adj = build_adjacency_from_edgelist(edgelist = edgelist_ens,\n",
+    "                                        is_directed = False,\n",
+    "                                        is_sparse = False,\n",
+    "                                        is_weighted = False)"
    ]
   },
   {
@@ -220,7 +199,7 @@
   },
   {
    "source": [
-    "Suppose now that you have only partial information about the zachary karate club network: only the degree sequence is disclosed. Following the same procedure described above, we can generate generate a network having (on average) the same observed degree sequence."
+    "Suppose now that you have only partial information about the zachary karate club network: only the degree sequence is disclosed. Following the same procedure described above, we can generate a network having (on average) the same observed degree sequence."
    ],
    "cell_type": "markdown",
    "metadata": {}
@@ -250,10 +229,10 @@
     "G.add_edges_from(edgelist_ens)\n",
     "\n",
     "# then we can build the adjacency matrix\n",
-    "ens_adj = build_graph_from_edgelist(edgelist = edgelist_ens,\n",
-    "                                    is_directed = False,\n",
-    "                                    is_sparse = False,\n",
-    "                                    is_weighted = False)\n",
+    "ens_adj = build_adjacency_from_edgelist(edgelist = edgelist_ens,\n",
+    "                                        is_directed = False,\n",
+    "                                        is_sparse = False,\n",
+    "                                        is_weighted = False)\n",
     "\n",
     "# or generate a networkx graph from it\n",
     "G = nx.DiGraph()\n",
@@ -373,10 +352,10 @@
     "edgelist_ens = np.loadtxt(\"sample/0.txt\")\n",
     "\n",
     "# and build the adjacency matrix\n",
-    "ens_adj = build_graph_from_edgelist(edgelist = edgelist_ens,\n",
-    "                                    is_directed = False,\n",
-    "                                    is_sparse = False,\n",
-    "                                    is_weighted = True)"
+    "ens_adj = build_adjacency_from_edgelist(edgelist = edgelist_ens,\n",
+    "                                        is_directed = False,\n",
+    "                                        is_sparse = False,\n",
+    "                                        is_weighted = True)"
    ]
   },
   {
@@ -389,10 +368,10 @@
   {
    "source": [
     "Suppose you have only partial information about the network, for example:\n",
-    " - The binary structure is well-known and you want to assign weights to network edges;\n",
-    " - Only marginals information are available: degree and strength sequences.\n",
+    " - The binary structure is well-known, and you want to assign weights to network edges;\n",
+    " - Only marginal information are available: degree and strength sequences.\n",
     "\n",
-    "You can use NEMtropy methods to reconstruct a network configuration that is consistent with the available informations."
+    "You can use NEMtropy methods to reconstruct a network configuration that is consistent with the available information."
    ],
    "cell_type": "markdown",
    "metadata": {}
@@ -473,10 +452,10 @@
     "edgelist_ens = np.loadtxt(\"sample/0.txt\")\n",
     "\n",
     "# then we can build the adjacency matrix\n",
-    "ens_adj = build_graph_from_edgelist(edgelist = edgelist_ens,\n",
-    "                                    is_directed = False,\n",
-    "                                    is_sparse = False,\n",
-    "                                    is_weighted = True)\n",
+    "ens_adj = build_adjacency_from_edgelist(edgelist = edgelist_ens,\n",
+    "                                        is_directed = False,\n",
+    "                                        is_sparse = False,\n",
+    "                                        is_weighted = True)\n",
     "\n",
     "# and generate a networkx graph from it\n",
     "G = nx.from_numpy_array(ens_adj)"
@@ -580,10 +559,10 @@
     "edgelist_ens = np.loadtxt(\"sample/0.txt\")\n",
     "\n",
     "# then we can build the adjacency matrix\n",
-    "ens_adj = build_graph_from_edgelist(edgelist = edgelist_ens,\n",
-    "                                    is_directed = False,\n",
-    "                                    is_sparse = False,\n",
-    "                                    is_weighted = True)\n",
+    "ens_adj = build_adjacency_from_edgelist(edgelist = edgelist_ens,\n",
+    "                                        is_directed = False,\n",
+    "                                        is_sparse = False,\n",
+    "                                        is_weighted = True)\n",
     "\n",
     "# and generate a networkx graph from it\n",
     "G = nx.from_numpy_array(ens_adj)"

diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1,19 @@
+numpy~=1.20.1
+scipy~=1.6.0
+networkx~=2.5
+powerlaw~=1.4.6
+numba~=0.52.0
+NEMtropy~=1.0.5
+setuptools~=51.1.2
+Pillow~=8.1.0
+pip~=20.3.3
+wheel~=0.36.2
+six~=1.15.0
+llvmlite~=0.35.0
+matplotlib~=3.3.4
+mpmath~=1.2.1
+python-dateutil~=2.8.1
+decorator~=4.4.2
+pyparsing~=2.4.7
+cycler~=0.10.0
+kiwisolver~=1.3.1
diff --git a/setup.py b/setup.py
@@ -12,7 +12,7 @@
                  ' matteo.bruno@imtlucca.it',
     packages=["NEMtropy"],
     package_dir={'': 'src'},
-    version="2.0.2",
+    version="2.0.3",
     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"
@@ -23,9 +23,9 @@
     long_description_content_type="text/markdown",
     license="GNU General Public License v3",
     url="https://github.com/nicoloval/NEMtropy/",
-    download_url="https://github.com/nicoloval/NEMtropy/archive/v2.0.0.zip",
+    download_url="https://github.com/nicoloval/NEMtropy/archive/v2.0.2.zip",
     keywords=['Network reconstruction', 'Networks Null Models',
-              'Maximum Entrophy Methods'],
+              'Maximum Entropy Methods'],
     classifiers=[
                 'License :: OSI Approved :: GNU Library or Lesser General'
                 ' Public License (LGPL)',

diff --git 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.2"
+__version__ = "2.0.3"
 __author__ = """Nicolo' Vallarano (nicolo.vallarano@imtlucca.it)
-Emiliano Marchese (emiliano.marchese@imtulucca.it)
+Emiliano Marchese (emiliano.marchese@imtlucca.it)
 Matteo Bruno (matteo.bruno@imtlucca.it)"""