 [](https://www.gnu.org/licenses/gpl-3.0) 
[](https://arxiv.org/abs/2508.00542)
# SIBERIA: SIgned BEnchmarks foR tIme series Analysis
SIBERIA provides **maximum-entropy null models and validation methods for signed networks derived from time series**.
It enables the construction, filtering, and community detection of signed adjacency matrices based on validated co-fluctuations.
The library implements advanced null models (`bSRGM`, `bSCM`) to rigorously distinguish meaningful patterns from noise, supporting reproducible and interpretable time-series network analysis.
SIBERIA includes methods to:
- Compute binary **signature matrices** for co-fluctuations.
- Fit maximum-entropy **null models** (`bSRGM`, `bSCM`).
- Predict event probabilities from model parameters.
- Validate signatures using **analytical statistics** and **FDR correction**.
- Build **signed graphs** and filter them.
- Perform **community detection** minimizing BIC or frustration.
- Visualize results via heatmaps and network adjacency plots.
---
## Citation
If you use **SIBERIA** in your research, please cite the following paper:
```bibtex
@misc{divece2025assessingimbalancesignedbrain,
title={Assessing (im)balance in signed brain networks},
author={Marzio Di Vece and Emanuele Agrimi and Samuele Tatullo and Tommaso Gili and Miguel Ibáñez-Berganza and Tiziano Squartini},
year={2025},
eprint={2508.00542},
archivePrefix={arXiv},
primaryClass={physics.soc-ph},
url={https://arxiv.org/abs/2508.00542},
}
```
## Contents
- [Installation](#installation)
- [Dependencies](#dependencies)
- [Initialization](#initialization)
- [Core Functionalities](#core-functionalities)
- [Compute Signatures](#compute-signatures)
- [Fit Null Models](#fit-null-models)
- [Predict Event Probabilities](#predict-event-probabilities)
- [Validate Signatures](#validate-signatures)
- [Build and Filter Graphs](#build-and-filter-graphs)
- [Community Detection](#community-detection)
- [Plotting](#plotting)
- [Documentation](#documentation)
- [Credits](#credits)
---
## Installation
siberia can be installed via [pip](https://pypi.org/project/siberia/). Run:
```bash
pip install siberia
```
To upgrade to the latest version:
```bash
pip install siberia --upgrade
```
## Dependencies
SIBERIA requires the following libraries:
- **numpy** for numerical operations
- **scipy** for optimization and statistical functions
- **pandas** for structured data handling
- **fast-poibin** for Poisson-Binomial distributions
- **joblib** for parallel computation
- **statsmodels** for multiple testing corrections
- **matplotlib** and **seaborn** for visualization
- **tqdm** for progress bars
- **numba** for accelerating heavy computations
Install them via:
```bash
pip install numpy scipy pandas fast-poibin joblib statsmodels matplotlib tqdm numba
```
## How-to Guidelines
The main entry point of Siberia is the `TSeries` class, initialized with an `N × T` float matrix representing `N` time series of length `T`.
### Initialization
```python
from siberia import TSeries
# Tij is a 2D numpy array of shape (N, T) with float values
T = TSeries(data=Tij, n_jobs=4)
```
After initialization, you can already explore marginal statistics:
```python
T.ai_plus, T.ai_minus # row-wise positive/negative counts
T.kt_plus, T.kt_minus # column-wise positive/negative counts
T.a_plus, T.a_minus # total positive/negative counts
```
### Computing the Signature
The signature captures concordant and discordant motifs in your time series:
```python
binary_signature = T.compute_signature()
```
The signature matrix is computed as:
- Concordant motifs = positive-positive + negative-negative
- Discordant motifs = positive-negative + negative-positive
- Binary signature = concordant − discordant
### Fitting the Models
You can list available models:
```python
T.implemented_models
```
which returns:
```python
['bSRGM', 'bSCM']
```
Choose and fit a model:
```python
T.fit(model="bSCM")
```
After fitting, the following attributes become available:
```python
T.ll # log-likelihood
T.jac # Jacobian
T.norm # infinite norm of the Jacobian
T.norm_rel_error # relative error
T.aic # Akaike Information Criterion
```
### Predicting Event Probabilities
Compute the expected probability of observing positive and negative events:
```python
pit_plus, pit_minus = T.predict()
```
These matrices provide event probabilities under the null model.
### Validating the Signature
Statistical validation with False Discovery Rate (FDR) correction:
```python
filtered_signature = T.validate_signature(fdr_correction_flag=True, alpha=0.05)
```
This filters out non-significant entries from the signature matrix.
### Building Signed Graphs
Convert signatures into signed adjacency matrices:
```python
naive_graph, filtered_graph = T.build_graph()
```
- **Naive Graph**: raw signature signs
- **Filtered Graph**: FDR-validated signature signs
### Plotting Signatures
Visualize empirical vs. filtered signature matrices:
```python
T.plot_signature(export_path="results/signature", show=True)
```
Visualize naive vs. filtered adjacency matrices:
```python
T.plot_graph(export_path="results/adjacency", show=True)
```
### Community Detection
SIBERIA includes community detection routines based on:
- **BIC minimization**
- **Frustration minimization**
Run detection:
```python
stats = T.community_detection(
trials=500,
method="bic", # or "frustration"
show=True
)
```
The output dictionary contains:
```python
stats['naive'] # stats for naive graph
stats['filtered'] # stats for filtered graph
stats['method'] # chosen minimization method
```
Best community assignments:
```python
T.naive_communities
T.filtered_communities
```
### Plotting Communities
The `plot_communities` function provides a visualization of adjacency matrices reordered by detected communities.
It highlights community partitions by drawing boxes around groups of nodes assigned to the same community.
#### Usage
```python
T.plot_communities(graph_type="filtered", export_path="results/communities", show=True)
```
## Documentation
You can find the complete documentation of the MaxEntSeries library in [documentation](https://maxentseries.readthedocs.io/en/latest/index.html)
## Credits
*Author*:
[Marzio Di Vece](https://www.sns.it/it/persona/marzio-di-vece) (a.k.a. [MarsMDK](https://github.com/MarsMDK))
[Emanuele Agrimi](https://www.imtlucca.it/it/people/emanuele-agrimi) (a.k.a. [Emaagr](https://github.com/Emaagr))
[Samuele Tatullo](https://www.imtlucca.it/it/people/samuele-tatullo)
*Acknowledgments*:
The module was developed under the supervision of [Tiziano Squartini](https://www.imtlucca.it/it/tiziano.squartini) and [Miguel Ibáñez Berganza](https://networks.imtlucca.it/people/miguel) and [Tommaso Gili](https://networks.imtlucca.it/people/tommaso).
It was developed at [IMT School for Advanced Studies Lucca](https://www.imtlucca.it/en) and [Scuola Normale Superiore of Pisa](https://www.sns.it/it).
This work is supported 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. MDV also acknowledges support by the European Community programme under the funding schemes: ERC-2018-ADG G.A. 834756 “XAI: Science and technology for the eXplanation of AI decision making”.
Raw data
{
"_id": null,
"home_page": null,
"name": "siberia",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "maximum entropy methods, time series, network filtering, graph, network, entropy",
"author": null,
"author_email": "Marzio Di Vece <marzio.divece@sns.it>, Emanuele Agrimi <emanuele.agrimi@imtlucca.it>, Samuele Tatullo <samuele.tatullo@imtlucca.it>",
"download_url": "https://files.pythonhosted.org/packages/39/b1/f527bfa37dbb2184efe505cdc3ed693ea73d39067608721a020648d53078/siberia-0.0.1.tar.gz",
"platform": null,
"description": " [](https://www.gnu.org/licenses/gpl-3.0) \n [](https://arxiv.org/abs/2508.00542)\n\n\n# SIBERIA: SIgned BEnchmarks foR tIme series Analysis\n\nSIBERIA provides **maximum-entropy null models and validation methods for signed networks derived from time series**. \nIt enables the construction, filtering, and community detection of signed adjacency matrices based on validated co-fluctuations. \nThe library implements advanced null models (`bSRGM`, `bSCM`) to rigorously distinguish meaningful patterns from noise, supporting reproducible and interpretable time-series network analysis.\n\n\n\nSIBERIA includes methods to:\n\n- Compute binary **signature matrices** for co-fluctuations. \n- Fit maximum-entropy **null models** (`bSRGM`, `bSCM`). \n- Predict event probabilities from model parameters. \n- Validate signatures using **analytical statistics** and **FDR correction**. \n- Build **signed graphs** and filter them. \n- Perform **community detection** minimizing BIC or frustration. \n- Visualize results via heatmaps and network adjacency plots. \n\n---\n## Citation\n\nIf you use **SIBERIA** in your research, please cite the following paper:\n\n```bibtex\n@misc{divece2025assessingimbalancesignedbrain,\n title={Assessing (im)balance in signed brain networks}, \n author={Marzio Di Vece and Emanuele Agrimi and Samuele Tatullo and Tommaso Gili and Miguel Ib\u00e1\u00f1ez-Berganza and Tiziano Squartini},\n year={2025},\n eprint={2508.00542},\n archivePrefix={arXiv},\n primaryClass={physics.soc-ph},\n url={https://arxiv.org/abs/2508.00542}, \n}\n```\n\n\n## Contents\n- [Installation](#installation)\n- [Dependencies](#dependencies)\n- [Initialization](#initialization)\n- [Core Functionalities](#core-functionalities)\n - [Compute Signatures](#compute-signatures)\n - [Fit Null Models](#fit-null-models)\n - [Predict Event Probabilities](#predict-event-probabilities)\n - [Validate Signatures](#validate-signatures)\n - [Build and Filter Graphs](#build-and-filter-graphs)\n - [Community Detection](#community-detection)\n - [Plotting](#plotting)\n- [Documentation](#documentation)\n- [Credits](#credits)\n\n---\n\n\n## Installation\n\nsiberia can be installed via [pip](https://pypi.org/project/siberia/). Run:\n\n```bash\npip install siberia\n```\n\nTo upgrade to the latest version:\n\n```bash\npip install siberia --upgrade\n```\n\n## Dependencies\n\nSIBERIA requires the following libraries:\n\n- **numpy** for numerical operations\n- **scipy** for optimization and statistical functions\n- **pandas** for structured data handling\n- **fast-poibin** for Poisson-Binomial distributions\n- **joblib** for parallel computation\n- **statsmodels** for multiple testing corrections\n- **matplotlib** and **seaborn** for visualization\n- **tqdm** for progress bars\n- **numba** for accelerating heavy computations\n\nInstall them via:\n\n```bash\npip install numpy scipy pandas fast-poibin joblib statsmodels matplotlib tqdm numba\n```\n\n## How-to Guidelines\n\nThe main entry point of Siberia is the `TSeries` class, initialized with an `N \u00d7 T` float matrix representing `N` time series of length `T`.\n\n### Initialization\n\n```python\nfrom siberia import TSeries\n\n# Tij is a 2D numpy array of shape (N, T) with float values\nT = TSeries(data=Tij, n_jobs=4)\n```\n\nAfter initialization, you can already explore marginal statistics:\n\n```python\nT.ai_plus, T.ai_minus # row-wise positive/negative counts\nT.kt_plus, T.kt_minus # column-wise positive/negative counts\nT.a_plus, T.a_minus # total positive/negative counts\n```\n\n### Computing the Signature\n\nThe signature captures concordant and discordant motifs in your time series:\n\n```python\nbinary_signature = T.compute_signature()\n```\n\nThe signature matrix is computed as:\n\n- Concordant motifs = positive-positive + negative-negative\n- Discordant motifs = positive-negative + negative-positive\n- Binary signature = concordant \u2212 discordant\n\n### Fitting the Models\n\nYou can list available models:\n\n```python\nT.implemented_models\n```\n\nwhich returns:\n\n```python\n['bSRGM', 'bSCM']\n```\n\nChoose and fit a model:\n\n```python\nT.fit(model=\"bSCM\")\n```\n\nAfter fitting, the following attributes become available:\n\n```python\nT.ll # log-likelihood\nT.jac # Jacobian\nT.norm # infinite norm of the Jacobian\nT.norm_rel_error # relative error\nT.aic # Akaike Information Criterion\n```\n\n### Predicting Event Probabilities\n\nCompute the expected probability of observing positive and negative events:\n\n```python\npit_plus, pit_minus = T.predict()\n```\n\nThese matrices provide event probabilities under the null model.\n\n### Validating the Signature\n\nStatistical validation with False Discovery Rate (FDR) correction:\n\n```python\nfiltered_signature = T.validate_signature(fdr_correction_flag=True, alpha=0.05)\n```\n\nThis filters out non-significant entries from the signature matrix.\n\n### Building Signed Graphs\n\nConvert signatures into signed adjacency matrices:\n\n```python\nnaive_graph, filtered_graph = T.build_graph()\n```\n\n- **Naive Graph**: raw signature signs\n- **Filtered Graph**: FDR-validated signature signs\n\n### Plotting Signatures\n\nVisualize empirical vs. filtered signature matrices:\n\n```python\nT.plot_signature(export_path=\"results/signature\", show=True)\n```\n\nVisualize naive vs. filtered adjacency matrices:\n\n```python\nT.plot_graph(export_path=\"results/adjacency\", show=True)\n```\n\n### Community Detection\n\nSIBERIA includes community detection routines based on:\n\n- **BIC minimization**\n- **Frustration minimization**\n\nRun detection:\n\n```python\nstats = T.community_detection(\n trials=500,\n method=\"bic\", # or \"frustration\"\n show=True\n)\n```\n\nThe output dictionary contains:\n\n```python\nstats['naive'] # stats for naive graph\nstats['filtered'] # stats for filtered graph\nstats['method'] # chosen minimization method\n```\n\nBest community assignments:\n\n```python\nT.naive_communities\nT.filtered_communities\n```\n\n### Plotting Communities\n\nThe `plot_communities` function provides a visualization of adjacency matrices reordered by detected communities. \nIt highlights community partitions by drawing boxes around groups of nodes assigned to the same community. \n\n#### Usage\n\n```python\nT.plot_communities(graph_type=\"filtered\", export_path=\"results/communities\", show=True)\n```\n\n\n## Documentation\nYou can find the complete documentation of the MaxEntSeries library in [documentation](https://maxentseries.readthedocs.io/en/latest/index.html)\n\n## Credits\n\n*Author*:\n\n[Marzio Di Vece](https://www.sns.it/it/persona/marzio-di-vece) (a.k.a. [MarsMDK](https://github.com/MarsMDK))\n[Emanuele Agrimi](https://www.imtlucca.it/it/people/emanuele-agrimi) (a.k.a. [Emaagr](https://github.com/Emaagr))\n[Samuele Tatullo](https://www.imtlucca.it/it/people/samuele-tatullo)\n\n\n*Acknowledgments*:\nThe module was developed under the supervision of [Tiziano Squartini](https://www.imtlucca.it/it/tiziano.squartini) and [Miguel Ib\u00e1\u00f1ez Berganza](https://networks.imtlucca.it/people/miguel) and [Tommaso Gili](https://networks.imtlucca.it/people/tommaso).\nIt was developed at [IMT School for Advanced Studies Lucca](https://www.imtlucca.it/en) and [Scuola Normale Superiore of Pisa](https://www.sns.it/it).\nThis work is supported 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. MDV also acknowledges support by the European Community programme under the funding schemes: ERC-2018-ADG G.A. 834756 \u201cXAI: Science and technology for the eXplanation of AI decision making\u201d.\n",
"bugtrack_url": null,
"license": null,
"summary": "SIBERIA (SIgned BEnchmarks foR tIme series Analysis) provides maximum-entropy null models and validation methods for signed networks derived from time series.",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/MarsMDK/siberia"
},
"split_keywords": [
"maximum entropy methods",
" time series",
" network filtering",
" graph",
" network",
" entropy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9d6e094dd2a1de6453f1b736f9e2604a14ebeed7f21b85eb8e0259179bffc532",
"md5": "0b71fd3d907ff62f38e3656ac9a51b56",
"sha256": "6766267706dcfc26d88f975a712d123598f72b30e00f784548f5211bdf6ca7d3"
},
"downloads": -1,
"filename": "siberia-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b71fd3d907ff62f38e3656ac9a51b56",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 30379,
"upload_time": "2025-08-04T12:29:10",
"upload_time_iso_8601": "2025-08-04T12:29:10.982891Z",
"url": "https://files.pythonhosted.org/packages/9d/6e/094dd2a1de6453f1b736f9e2604a14ebeed7f21b85eb8e0259179bffc532/siberia-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "39b1f527bfa37dbb2184efe505cdc3ed693ea73d39067608721a020648d53078",
"md5": "37d003c0e45d4885bae372e3ce96fd44",
"sha256": "564e721b7124eae516a727121f6db42e3d3cfc18f04f8aaa04f7ad9de3052c2f"
},
"downloads": -1,
"filename": "siberia-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "37d003c0e45d4885bae372e3ce96fd44",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 34597,
"upload_time": "2025-08-04T12:29:12",
"upload_time_iso_8601": "2025-08-04T12:29:12.547535Z",
"url": "https://files.pythonhosted.org/packages/39/b1/f527bfa37dbb2184efe505cdc3ed693ea73d39067608721a020648d53078/siberia-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 12:29:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MarsMDK",
"github_project": "siberia",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "setuptools",
"specs": [
[
">=",
"61.2.0"
]
]
},
{
"name": "wheel",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "tqdm",
"specs": []
},
{
"name": "joblib",
"specs": []
},
{
"name": "numba",
"specs": []
},
{
"name": "statsmodels",
"specs": []
},
{
"name": "fast-poibin",
"specs": []
},
{
"name": "seaborn",
"specs": []
}
],
"lcname": "siberia"
}
JSON
