Metadata-Version: 2.4
Name: wmsm
Version: 0.1.0
Summary: wMSM, weighted MultiScale Model for multiscale network reconstruction
Author-email: Mattia Marzi <mattia.marzi@imtlucca.it>
License: MIT License
        
        Copyright (c) 2026 Mattia Marzi
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/mattiamarzi/wmsm
Project-URL: Repository, https://github.com/mattiamarzi/wmsm
Project-URL: Issues, https://github.com/mattiamarzi/wmsm/issues
Keywords: networks,reconstruction,gravity-model,coarse-graining,weighted-networks
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=2.0
Requires-Dist: numba>=0.57
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: notebooks
Requires-Dist: jupyter>=1.0; extra == "notebooks"
Dynamic: license-file

# wMSM

`wmsm` is a research package for reconstructing weighted networks across aggregation levels with the **weighted MultiScale Model** (wMSM).

The package is designed for settings in which the binary density is observable only at a coarse scale, while node strengths are available at the finer scale where the network must be reconstructed. The key idea is to calibrate the binary parameter on the aggregate layer and transfer it unchanged to the target layer, because the wMSM probability law is closed under coarse graining with additive strengths.

The repository also includes CReMB, a fine-scale benchmark based on the density-corrected Gravity Model topology and the Conditional Reconstruction Method for weights.

## Installation

```bash
pip install wmsm
```

For development:

```bash
git clone https://github.com/mattiamarzi/wmsm
cd wmsm
pip install -e ".[dev,notebooks]"
pytest -q
```

## Quick start

```python
import numpy as np

from wmsm import load_synthetic_itn_like, link_count
from wmsm import wmsm, cremb
from wmsm.metrics import reconstruction_summary

# Bundled anonymized ITN-like example.
data = load_synthetic_itn_like()
W_country = data["W_country"]
W_macro = data["W_macro"]

A_country = (W_country > 0).astype(float)
A_macro = (W_macro > 0).astype(float)

s_country = W_country.sum(axis=1)
s_macro = W_macro.sum(axis=1)
W_total = W_country.sum()

# wMSM, calibrated on macro-regions and transferred to countries.
L_macro = link_count(A_macro, directed=False, include_diagonal=True)
delta = wmsm.fit_delta_from_strengths(
    s_macro,
    None,
    L_macro,
    directed=False,
    include_diagonal=True,
)
rho = wmsm.rho_from_total_weight(delta, W_total)
P_wmsm = wmsm.probability_matrix_from_strengths(
    s_country,
    None,
    delta=delta,
    directed=False,
    include_diagonal=False,
)
Wexp_wmsm = wmsm.expected_weights_matrix_from_strengths(
    s_country,
    None,
    delta=delta,
    rho=rho,
    directed=False,
    include_diagonal=False,
)

# CReMB, calibrated directly on the country layer.
L_country = link_count(A_country, directed=False, include_diagonal=False)
z = cremb.fit_delta_from_strengths(
    s_country,
    None,
    L_country,
    directed=False,
    include_diagonal=False,
)
P_cremb = cremb.probability_matrix_from_strengths(
    s_country,
    None,
    delta=z,
    directed=False,
    include_diagonal=False,
)
Wexp_cremb = cremb.expected_weights_matrix_from_strengths(
    s_country,
    None,
    directed=False,
    include_diagonal=False,
)

summary_wmsm = reconstruction_summary(
    A_country,
    W_country,
    P_wmsm,
    Wexp_wmsm,
    directed=False,
    include_diagonal=False,
)
summary_cremb = reconstruction_summary(
    A_country,
    W_country,
    P_cremb,
    Wexp_cremb,
    directed=False,
    include_diagonal=False,
)

print(summary_wmsm["ARE_k"], summary_wmsm["MRE_k"], summary_wmsm["TPR"])
print(summary_cremb["ARE_k"], summary_cremb["MRE_k"], summary_cremb["TPR"])
```

## Repository layout

```text
src/wmsm/wmsm.py      wMSM calibration and first moments
src/wmsm/cremb.py      CReMB benchmark calibration and first moments
src/wmsm/metrics.py    diagnostics used in the paper
datasets/               anonymized synthetic example dataset
notebooks/              end-to-end reproducible examples
docs/                   usage notes, API reference, and equations
tests/                  automated tests for the package workflow
```

## Documentation

See:

- `docs/usage.md`
- `docs/api_quick_reference.md`
- `docs/math.md`

## Citation

The companion paper is currently in preparation. Until the public bibliographic record is available, please cite the repository and use the placeholder `CITATION.cff` file.

## License

MIT, see `LICENSE`.
