Metadata-Version: 2.4
Name: asbm
Version: 0.1.8
Summary: Find group structures in networks
Author-Email: Maximilian Jerdee <mjerdee@umich.edu>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/maxjerdee/asbm
Project-URL: Bug Tracker, https://github.com/maxjerdee/asbm/issues
Project-URL: Discussions, https://github.com/maxjerdee/asbm/discussions
Project-URL: Changelog, https://github.com/maxjerdee/asbm/releases
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas>=2.2.0
Requires-Dist: networkx>=3.0
Requires-Dist: tqdm>=4.65.0
Description-Content-Type: text/markdown

# asbm

[![Documentation Status][rtd-badge]][rtd-link]
[![PyPI version][pypi-version]][pypi-link]
[![PyPI platforms][pypi-platforms]][pypi-link]

<!-- SPHINX-START -->

<!-- prettier-ignore-start -->
[actions-badge]:            https://github.com/maxjerdee/asbm/workflows/CI/badge.svg
[actions-link]:             https://github.com/maxjerdee/asbm/actions
[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/asbm
[conda-link]:               https://github.com/conda-forge/asbm-feedstock
[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
[github-discussions-link]:  https://github.com/maxjerdee/asbm/discussions
[paper-link]:               https://arxiv.org/abs/TODO
[pypi-link]:                https://pypi.org/project/asbm/
[pypi-platforms]:           https://img.shields.io/pypi/pyversions/asbm
[pypi-version]:             https://img.shields.io/pypi/v/asbm
[rtd-badge]:                https://readthedocs.org/projects/asbm/badge/?version=latest
[rtd-link]:                 https://asbm.readthedocs.io/en/latest/?badge=latest

<!-- prettier-ignore-end -->

## Infer network groups and properties with assortative stochastic block models

*Maximilian Jerdee*

This Python package uses Bayesian inference to find meaningful groupings of nodes in networks.

We implement a [general assortative SBM][paper-link] that unifies the standard SBM and the planted partition model under a common framework. Its parameters directly measure the violation of each model's assumptions: the assortative preference ρ_in/ρ_out captures departure from in/out symmetry, while per-group variation coefficients v_in and v_out measure heterogeneity across groups. The standard SBM, planted partition model, and the Zhang–Peixoto hybrid emerge as special cases, enabling exact Bayesian model comparison between them.

For each model, the package includes algorithms to:
- Find consensus estimates of the group structure
- Infer global network parameters (assortativity, group sizes)
- Score held-out edges via posterior predictive likelihood

## Installation

Implementations are available for Python, R, and Julia.

### Python

```bash
pip install asbm
```

Or build locally from the repository root:

```bash
pip install .
```

### R

```r
install.packages("asbm", repos = "https://maxjerdee.r-universe.dev")
```

### Julia

```julia
using Pkg
Pkg.add(url="https://github.com/maxjerdee/asbm", subdir="bindings/julia")
```

Building from source requires CMake and a C++17 compiler. Run `Pkg.build("ASBM")` after installation to compile the native library.

## Quickstart

### Python

```python
import asbm
import networkx as nx

G = nx.read_gml("examples/data/dolphins.gml", label="id")

config = asbm.Config(
    model="general_asbm",
    degree_correction=True,
)

result = asbm.fit(config, G)

print(result.mdl_partition)
print(result.mdl_value)
print(result.consensus_partition())
```

To score held-out edges:

```python
G_train = nx.read_gml("examples/data/train.gml")
G_test  = nx.read_gml("examples/data/test.gml")

result = asbm.fit(asbm.Config(model="general_asbm"), G_train)
score  = result.log_posterior_predictive(G_test)
```

### R

```r
library(asbm)
library(igraph)

G <- read_graph("examples/data/dolphins.gml", format = "gml")

result <- fit(G,
              model             = "general_asbm",
              degree_correction = TRUE,
              num_chains        = 4,
              samples_per_chain = 100,
              seed              = 42)

print(result$mdl_value)
print(result$mdl_partition)
print(result$consensus_partition)
```

### Julia

```julia
using ASBM, Graphs

g = cycle_graph(62)  # or load via GraphIO

result = fit(g;
    model             = "general_asbm",
    degree_correction = true,
    num_chains        = 4,
    samples_per_chain = 100,
    seed              = 42)

println(result.mdl_value)
println(result.mdl_partition)
println(result.consensus_partition)
```

For the full API, including posterior predictive evaluation and the samples schema, see the [package documentation][rtd-link].
