| Name | NuMeTriS JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | NuMeTris is a package for Maximum-Entropy models for triadic pattern detection. It contains known models such as DBCM and RBCM for binary motif analysis, and contain mixture models such as DBCM+CReMa and RBCM+CRWCM for weighted triadic motif analysis. The models are solved and routine are present for numeric ensemble generation and the computation of the triadic z-scores for triadic sub-graph occurrence, average flux and intensity. |
| upload_time | 2024-10-08 09:58:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
maximum entropy methods
network motifs
pattern detection
graph
network
entropy
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
 [](https://www.gnu.org/licenses/gpl-3.0)  [](https://www.nature.com/articles/s41598-024-53655-3)
# NuMeTriS: NUll ModEls for TRIadic Structures
NuMeTriS is a package developed on python3 for Pattern Detection of the 13 triadic connected sub-graphs using maximum-entropy models using direected and reciprocated constraints on network data.
NuMeTriS provides solvers for the binary models DBCM and RBCM, and the conditional weighted models CReMa and CRWCM.
All of these models are explained in [[1](https://www.nature.com/articles/s41598-024-53655-3)].
The use of DBCM and CReMa enable the user to explicitly constrain network properties based on direction, such as out-degree, in-degree (binary) and out-strength and in-strength (weighted).
In contrast, the use of RBCM and CRWCM enable the user to constrain network properties based on both direction and reciprocity, such as the reciprocated and non-reciprocated degrees and the reciprocated and non-reciprocated strengths.
Moreover, after solving the models it is possible to generate the related ensembles and compute triadic occurrences, the arithmetic mean of the weights on triadic structures (average fluxes) and their geometric mean (intensities). While triadic occurrences and fluxes are explained in [[1](https://www.nature.com/articles/s41598-024-53655-3)], the triadic intensity is the geometric mean of the weights in triadic structures, as explained in [[2](https://journals.aps.org/pre/abstract/10.1103/PhysRevE.71.065103)] but here defined for all 13 sub-graphs.
To explore Maximum-Entropy modeling on networks, checkout [Maximum Entropy Hub](https://meh.imtlucca.it/).
When using the module for your scientific research please consider citing:
```
@article{divece2024commodityspecific,
title={Commodity-specific triads in the Dutch inter-industry production network},
author={Marzio Di Vece and Frank P. Pijpers and Diego Garlaschelli},
year={2024},
eprint={2305.12179},
journal = {Scientific Reports},
number={14},
pages = {3625}
}
```
#### Contents
- [NuMeTriS: NUll ModEls for TRIadic Structures](#dygys-dyadic-gravity-regression-models-with-soft-constraints)
- [Contents](#contents)
- [Currently Available Models](#currently-available-models)
- [Installation](#installation)
- [Dependencies](#dependencies)
- [How-to Guidelines](#how-to-guidelines)
- [Class Instance and Empirical Network Statistics](#class-instance-and-empirical-network-statistics)
- [Solving the models](#solving-the-models)
- [Numerically Computing z-scores and significance profiles](#numerically-computing-z-scores-and-significance-profiles)
- [Documentation](#documentation)
- [Credits](#credits)
## Currently Available Models
NuMeTriS contains models for triadic motif detection on network data for continuous-valued semi-definite positive weights.
The available models are:
* **DBCM** *Directed Binary Configuration Model*
* **RBCM** *Reciprocated Binary Configuration Model*
* **DBCM+CReMa** *Mixture model of Directed Binary Configuration Model and Conditional Reconstruction Method A*
* **RBCM+CRWCM** *Mixture model of Reciprocated Binary Configuration Model and Conditionally Reciprocal Configuration Model*
Please refer to the paper for further details.
## Installation
NuMeTriS can be installed via [pip](https://pypi.org/project/NuMeTriS/). You can do it from your terminal
```
$ pip install NuMeTriS
```
If you already installed the package and want to upgrade it,
you can type from your terminal:
```
$ pip install NuMeTriS --upgrade
```
## Dependencies
NuMeTris uses the following dependencies:
* **scipy** for optimization and root solving of some of the models;
* **numba** for fast computation of network statistics and criterion functions.
* **matplotlib** in order to plot z-score profiles and significance profiles.
They can be easily installed via pip typing
$ pip install scipy
$ pip install numba
$ pip install matplotlib
## How-to Guidelines
The module containes the class Graph, initiated with a 2D weighted adjacency matrix, explaining the interactions present in the network data.
### Class Instance and Empirical Network Statistics
To inizialize a Graph instance you can type:
G = Graph(adjacency=Wij)
where Wij is the weighted adjacency matrix in 2-D numpy array format.
If you want to initialize a sparse matrix you can type:
G = Sparse_Graph(adjacency=Wij)
In this case, a csr sparse matrix is necessary in input.
After initializing you can already explore core network statistics such as (out-)degree, in-degree, reciprocated degrees, non-reciprocated out-degrees and non-reciprocated in-degrees, available using the respective codewords:
G.dseq_out, G.dseq_in, G.dseq_right, G.dseq_left, G.dseq_rec
or weighted core network statistics such as (out-)strength, in-strength, reciprocated strengths, non-reciprocated strengths, available using the respective codewords:
G.stseq_out, G.stseq_in, G.stseq_right, G.stseq_left, G.stseq_rec_out, G.stseq_rec_in
Also triadic network statistics are computed, namely Occurrences, Intensities and Fluxes, available using the respective codewords:
G.Nm_emp, G.Im_emp, G.Fm_emp
### Solving the models
You can explore the currently available models using
G.implemented_models
use their names as described in this list not to incur in error messages.
When ready you can choose one of the aforementioned models and solve for their parameters using
G.solver(model= <chosen model>)
Once you solved the model various other attributes become visible and measures dependent solely on criterion functions are computed. These include Loglikelihood, Jacobian, Infinite Jacobian Norm, relative error and relative infinite norm, available using the codewords:
G.ll, G.jacobian, G.norm, G.relative_error, G.norm_rel
For further details on the .solve functions please see the documentation.
### Numerically Computing z-scores and significance profiles
Computing z-scores and significance profiles is very easy.
Generating the network ensemble is very easy. It's enough to type:
G.numerical_triadic_zscores(n_ensemble=<wanted number of graphs>,percentiles=<wanted percentiles for z-score CIs.>)
This routine generate "n_ensemble" graphs and computes z-scores for triadic occurrences (if a binary model is chosen) or triadic occurrences, fluxes and intensities (if a mixture model is chosen). Moreover it estimates a confidence interval for the z-score to understand the range of the values assumed in the ensemble. Percentiles are defined as tuple types and a 95% confidence interval can be estimated by the tuple (z_{2.5},z_{97.5}), for percentiles = (2.5,97.5).
This method returns expected triadic occurrences, triadic fluxes and triadic intensities
G.avg_Nm, G.avg_Fm, G.avg_Im,
corresponding z-scores
G.zscores_Nm, G.zscores_Fm, G.zscores_Im,
inferior and superior percentiles
G.zscores_down_Nm, G.zscores_down_Fm, G.zscores_down_Im, G.zscores_up_Nm, G.zscores_up_Fm, G.zscores_up_Im
and significance scores
G.normalized_z_Nm, G.normalized_z_Fm, G.normalized_z_Im.
### Plot z-scores and significance profiles
Routine to plot z-scores and significance profiles. It's enough to type:
G.plot_zscores(type='z-scores')
G.plot_zscores(type='significance')
G.plot_zscores(type='both')
It plots triadic occurrences (if a binary model is used) or occurrences, fluxes and intensities (if a mixture model is used).
It is possible to plot z-scores using the argument type='z-scores', significance profiles using argument type='significance' or both, using type='both'.
## Documentation
You can find the complete documentation of the NuMeTriS library in [documentation](https://numetris.readthedocs.io/en/latest/index.html)
## Credits
*Author*:
[Marzio Di Vece](https://www.imtlucca.it/it/marzio.divece) (a.k.a. [MarsMDK](https://github.com/MarsMDK))
*Acknowledgments*:
The module was developed under the supervision of [Diego Garlaschelli](https://www.imtlucca.it/en/diego.garlaschelli) and [Frank P. Pijpers](https://www.uva.nl/profiel/p/i/f.p.pijpers/f.p.pijpers.html).
It was developed at [IMT School for Advanced Studies Lucca](https://www.imtlucca.it/en) and [Statistics Netherlands](https://www.cbs.nl/en-gb).
This work is supported by the European Union - Horizon 2020 Program under the scheme “INFRAIA-01-2018-2019 – Integrating Activities for Advanced Communities”, Grant Agreement n. 871042, ‘SoBigData++: European Integrated Infrastructure for Social Mining and Big Data Analytics’ [(http://www.sobigdata.eu)](http://www.sobigdata.eu) and by the PNRR-M4C2-Investimento 1.3, Partenariato Esteso PE00000013-“FAIR-Future Artificial Intelligence Research”-Spoke 1 “Human-centered AI”, funded by the European Commission under the NextGeneration EU programme. This module was also supported by the Italian ‘Programma di Attività Integrata’ (PAI) project ‘Prosociality, Cognition and Peer Effects’ (Pro.Co.P.E.), funded by IMT School for Advanced Studies.
Raw data
{
"_id": null,
"home_page": null,
"name": "NuMeTriS",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "maximum entropy methods, network motifs, pattern detection, graph, network, entropy",
"author": null,
"author_email": "Marzio Di Vece <marzio.divece@imtlucca.it>",
"download_url": "https://files.pythonhosted.org/packages/d1/ef/5ea5d9e2067f8d607365095add153723b3dc525cf8d12df98e4212531351/numetris-0.1.1.tar.gz",
"platform": null,
"description": " [](https://www.gnu.org/licenses/gpl-3.0)  [](https://www.nature.com/articles/s41598-024-53655-3)\n\n# NuMeTriS: NUll ModEls for TRIadic Structures\n\nNuMeTriS is a package developed on python3 for Pattern Detection of the 13 triadic connected sub-graphs using maximum-entropy models using direected and reciprocated constraints on network data.\n\nNuMeTriS provides solvers for the binary models DBCM and RBCM, and the conditional weighted models CReMa and CRWCM.\nAll of these models are explained in [[1](https://www.nature.com/articles/s41598-024-53655-3)].\nThe use of DBCM and CReMa enable the user to explicitly constrain network properties based on direction, such as out-degree, in-degree (binary) and out-strength and in-strength (weighted).\nIn contrast, the use of RBCM and CRWCM enable the user to constrain network properties based on both direction and reciprocity, such as the reciprocated and non-reciprocated degrees and the reciprocated and non-reciprocated strengths.\n\nMoreover, after solving the models it is possible to generate the related ensembles and compute triadic occurrences, the arithmetic mean of the weights on triadic structures (average fluxes) and their geometric mean (intensities). While triadic occurrences and fluxes are explained in [[1](https://www.nature.com/articles/s41598-024-53655-3)], the triadic intensity is the geometric mean of the weights in triadic structures, as explained in [[2](https://journals.aps.org/pre/abstract/10.1103/PhysRevE.71.065103)] but here defined for all 13 sub-graphs.\n\nTo explore Maximum-Entropy modeling on networks, checkout [Maximum Entropy Hub](https://meh.imtlucca.it/).\n\nWhen using the module for your scientific research please consider citing:\n\n\n```\n @article{divece2024commodityspecific,\n title={Commodity-specific triads in the Dutch inter-industry production network}, \n author={Marzio Di Vece and Frank P. Pijpers and Diego Garlaschelli},\n year={2024},\n eprint={2305.12179},\n journal = {Scientific Reports},\n number={14},\n pages = {3625}\n}\n\n```\n#### Contents\n- [NuMeTriS: NUll ModEls for TRIadic Structures](#dygys-dyadic-gravity-regression-models-with-soft-constraints)\n - [Contents](#contents)\n - [Currently Available Models](#currently-available-models)\n - [Installation](#installation)\n - [Dependencies](#dependencies)\n - [How-to Guidelines](#how-to-guidelines)\n - [Class Instance and Empirical Network Statistics](#class-instance-and-empirical-network-statistics)\n - [Solving the models](#solving-the-models)\n - [Numerically Computing z-scores and significance profiles](#numerically-computing-z-scores-and-significance-profiles)\n - [Documentation](#documentation)\n - [Credits](#credits)\n\n## Currently Available Models\nNuMeTriS contains models for triadic motif detection on network data for continuous-valued semi-definite positive weights.\nThe available models are:\n* **DBCM** *Directed Binary Configuration Model* \n* **RBCM** *Reciprocated Binary Configuration Model* \n* **DBCM+CReMa** *Mixture model of Directed Binary Configuration Model and Conditional Reconstruction Method A* \n* **RBCM+CRWCM** *Mixture model of Reciprocated Binary Configuration Model and Conditionally Reciprocal Configuration Model* \n\nPlease refer to the paper for further details.\n\n## Installation\nNuMeTriS can be installed via [pip](https://pypi.org/project/NuMeTriS/). You can do it from your terminal\n```\n $ pip install NuMeTriS\n```\nIf you already installed the package and want to upgrade it,\nyou can type from your terminal:\n\n```\n $ pip install NuMeTriS --upgrade\n```\n\n## Dependencies\nNuMeTris uses the following dependencies:\n* **scipy** for optimization and root solving of some of the models;\n* **numba** for fast computation of network statistics and criterion functions.\n* **matplotlib** in order to plot z-score profiles and significance profiles.\n\nThey can be easily installed via pip typing\n\n $ pip install scipy\n $ pip install numba\n $ pip install matplotlib\n\n\n## How-to Guidelines\nThe module containes the class Graph, initiated with a 2D weighted adjacency matrix, explaining the interactions present in the network data.\n\n### Class Instance and Empirical Network Statistics\nTo inizialize a Graph instance you can type:\n\n G = Graph(adjacency=Wij)\n\nwhere Wij is the weighted adjacency matrix in 2-D numpy array format.\n\nIf you want to initialize a sparse matrix you can type:\n\n G = Sparse_Graph(adjacency=Wij)\n\nIn this case, a csr sparse matrix is necessary in input.\n\n\nAfter initializing you can already explore core network statistics such as (out-)degree, in-degree, reciprocated degrees, non-reciprocated out-degrees and non-reciprocated in-degrees, available using the respective codewords:\n\n G.dseq_out, G.dseq_in, G.dseq_right, G.dseq_left, G.dseq_rec\n\nor weighted core network statistics such as (out-)strength, in-strength, reciprocated strengths, non-reciprocated strengths, available using the respective codewords:\n\n G.stseq_out, G.stseq_in, G.stseq_right, G.stseq_left, G.stseq_rec_out, G.stseq_rec_in\n\nAlso triadic network statistics are computed, namely Occurrences, Intensities and Fluxes, available using the respective codewords:\n\n G.Nm_emp, G.Im_emp, G.Fm_emp\n\n\n### Solving the models\nYou can explore the currently available models using\n \n G.implemented_models\nuse their names as described in this list not to incur in error messages.\n\nWhen ready you can choose one of the aforementioned models and solve for their parameters using\n \n G.solver(model= <chosen model>)\n\nOnce you solved the model various other attributes become visible and measures dependent solely on criterion functions are computed. These include Loglikelihood, Jacobian, Infinite Jacobian Norm, relative error and relative infinite norm, available using the codewords:\n\n G.ll, G.jacobian, G.norm, G.relative_error, G.norm_rel\n\nFor further details on the .solve functions please see the documentation.\n\n\n\n### Numerically Computing z-scores and significance profiles\n\nComputing z-scores and significance profiles is very easy. \nGenerating the network ensemble is very easy. It's enough to type:\n \n G.numerical_triadic_zscores(n_ensemble=<wanted number of graphs>,percentiles=<wanted percentiles for z-score CIs.>)\n\nThis routine generate \"n_ensemble\" graphs and computes z-scores for triadic occurrences (if a binary model is chosen) or triadic occurrences, fluxes and intensities (if a mixture model is chosen). Moreover it estimates a confidence interval for the z-score to understand the range of the values assumed in the ensemble. Percentiles are defined as tuple types and a 95% confidence interval can be estimated by the tuple (z_{2.5},z_{97.5}), for percentiles = (2.5,97.5).\n\n\nThis method returns expected triadic occurrences, triadic fluxes and triadic intensities \n\n G.avg_Nm, G.avg_Fm, G.avg_Im,\n\ncorresponding z-scores\n\n G.zscores_Nm, G.zscores_Fm, G.zscores_Im,\n\ninferior and superior percentiles\n\n G.zscores_down_Nm, G.zscores_down_Fm, G.zscores_down_Im, G.zscores_up_Nm, G.zscores_up_Fm, G.zscores_up_Im\n\nand significance scores\n\n G.normalized_z_Nm, G.normalized_z_Fm, G.normalized_z_Im.\n\n### Plot z-scores and significance profiles\n\nRoutine to plot z-scores and significance profiles. It's enough to type:\n\n G.plot_zscores(type='z-scores')\n G.plot_zscores(type='significance')\n G.plot_zscores(type='both')\n\nIt plots triadic occurrences (if a binary model is used) or occurrences, fluxes and intensities (if a mixture model is used).\nIt is possible to plot z-scores using the argument type='z-scores', significance profiles using argument type='significance' or both, using type='both'.\n\n\n\n## Documentation\nYou can find the complete documentation of the NuMeTriS library in [documentation](https://numetris.readthedocs.io/en/latest/index.html)\n\n## Credits\n\n*Author*:\n\n[Marzio Di Vece](https://www.imtlucca.it/it/marzio.divece) (a.k.a. [MarsMDK](https://github.com/MarsMDK))\n\n*Acknowledgments*:\nThe module was developed under the supervision of [Diego Garlaschelli](https://www.imtlucca.it/en/diego.garlaschelli) and [Frank P. Pijpers](https://www.uva.nl/profiel/p/i/f.p.pijpers/f.p.pijpers.html).\nIt was developed at [IMT School for Advanced Studies Lucca](https://www.imtlucca.it/en) and [Statistics Netherlands](https://www.cbs.nl/en-gb).\nThis work is supported by the European Union - Horizon 2020 Program under the scheme \u201cINFRAIA-01-2018-2019 \u2013 Integrating Activities for Advanced Communities\u201d, Grant Agreement n. 871042, \u2018SoBigData++: European Integrated Infrastructure for Social Mining and Big Data Analytics\u2019 [(http://www.sobigdata.eu)](http://www.sobigdata.eu) and by the PNRR-M4C2-Investimento 1.3, Partenariato Esteso PE00000013-\u201cFAIR-Future Artificial Intelligence Research\u201d-Spoke 1 \u201cHuman-centered AI\u201d, funded by the European Commission under the NextGeneration EU programme. This module was also supported by the Italian \u2018Programma di Attivit\u00e0 Integrata\u2019 (PAI) project \u2018Prosociality, Cognition and Peer Effects\u2019 (Pro.Co.P.E.), funded by IMT School for Advanced Studies.\n",
"bugtrack_url": null,
"license": null,
"summary": "NuMeTris is a package for Maximum-Entropy models for triadic pattern detection. It contains known models such as DBCM and RBCM for binary motif analysis, and contain mixture models such as DBCM+CReMa and RBCM+CRWCM for weighted triadic motif analysis. The models are solved and routine are present for numeric ensemble generation and the computation of the triadic z-scores for triadic sub-graph occurrence, average flux and intensity.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/MarsMDK/NuMeTriS"
},
"split_keywords": [
"maximum entropy methods",
" network motifs",
" pattern detection",
" graph",
" network",
" entropy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "da6876509c762f5a31d576b3619a986d82f75f1771b1f7104ac0cf7a90bbcf3d",
"md5": "b05ae19776382ae720962911fc031af7",
"sha256": "589859269d0546ccd566518ed43c282dd4acea849d735a2d61558b950a050064"
},
"downloads": -1,
"filename": "NuMeTriS-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b05ae19776382ae720962911fc031af7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 44339,
"upload_time": "2024-10-08T09:58:09",
"upload_time_iso_8601": "2024-10-08T09:58:09.259471Z",
"url": "https://files.pythonhosted.org/packages/da/68/76509c762f5a31d576b3619a986d82f75f1771b1f7104ac0cf7a90bbcf3d/NuMeTriS-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d1ef5ea5d9e2067f8d607365095add153723b3dc525cf8d12df98e4212531351",
"md5": "3230c6d1099a9d454aa6f433c5e0772b",
"sha256": "8b54a6d6cff5903fcad5211f5e07fb7556ec8093fbf6ab75f9c1b643f4cd08f8"
},
"downloads": -1,
"filename": "numetris-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "3230c6d1099a9d454aa6f433c5e0772b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 45589,
"upload_time": "2024-10-08T09:58:11",
"upload_time_iso_8601": "2024-10-08T09:58:11.232221Z",
"url": "https://files.pythonhosted.org/packages/d1/ef/5ea5d9e2067f8d607365095add153723b3dc525cf8d12df98e4212531351/numetris-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-08 09:58:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MarsMDK",
"github_project": "NuMeTriS",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "numetris"
}
