pybirewirex 0.2.0

Fast degree-preserving network rewiring — Python port of the BiRewire R package

PyBiRewireX

Python port of the BiRewire R package — fast degree-preserving network randomisation via the Switching Algorithm with NetworkX and igraph support.

Given a binary network (bipartite or undirected), PyBiRewireX generates rewired versions that are uniformly drawn from the space of all networks with the same degree sequence. This null model can be used to test whether observed network properties are trivially explained by degree alone.

---

Installation

pip install pybirewirex

With optional graph-object support (igraph / networkx):

pip install "pybirewirex[graph]"

Requirements: Python ≥ 3.10, a C compiler (for building the extension). Pre-built wheels are available for Linux x86_64/aarch64, macOS x86_64/arm64, and Windows x86_64.

---

Quick start

import numpy as np
import pybirewirex as pbr

# Any binary 2-D ndarray (bipartite incidence matrix)
matrix = (np.random.default_rng(0).random((100, 40)) < 0.2).astype(np.int16)

# Rewire — row and column sums preserved
rewired = pbr.rewire_bipartite(matrix, seed=42)

assert np.array_equal(matrix.sum(axis=1), rewired.sum(axis=1))  # row sums
assert np.array_equal(matrix.sum(axis=0), rewired.sum(axis=0))  # col sums

Undirected graphs work identically — pass a symmetric adjacency matrix:

rewired_graph = pbr.rewire_undirected(adjacency, seed=42)

scipy sparse matrices, igraph graphs, and networkx graphs are accepted transparently and returned in the same format.

---

Convergence analysis

The analytical bound N gives the minimum number of switching steps needed to reach the stationary distribution. analysis_bipartite tracks Jaccard similarity at every step iterations across n_networks independent runs, letting you verify that the chain has converged.

result = pbr.analysis_bipartite(
    matrix,
    n_networks = 10,   # independent rewiring runs
    step       = 1000, # record Jaccard every 1 000 steps
    seed       = 0,
)

print(f"Analytical bound N = {result.N}")
print(f"Scores shape: {result.scores.shape}")  # (10, n_steps)

---

R vignette — Python reproductions

The figures below reproduce the two main outputs from the BiRewire R package vignette (BiRewire.Rnw), generated by scripts/demo.py.

Analysis — birewire.analysis.bipartite

Jaccard similarity between the original network and its rewired snapshots, sampled every step switching steps across n_networks independent runs. The red line marks the analytical bound N.

Original BiRewire (R):

PyBiRewireX (Python):

Monitoring — birewire.visual.monitoring.bipartite

t-SNE visualisation of the Markov chain underlying the Switching Algorithm. Each point is a sampled network; colour encodes sampling order (blue = first, red = last). At small step counts the chain moves slowly (tight clusters); at k = N and beyond the samples are uniformly distributed (scattered cloud).

Original BiRewire (R):

PyBiRewireX (Python):

---

API reference

Function	Description
rewire_bipartite(matrix, ...)	Rewire bipartite network, preserving row and column sums
rewire_undirected(adjacency, ...)	Rewire undirected graph, preserving degree sequence
analysis_bipartite(matrix, ...)	Convergence analysis for bipartite rewiring
analysis_undirected(adjacency, ...)	Convergence analysis for undirected rewiring
AnalysisResult	Dataclass: .N (bound), .scores (n_networks × n_steps), .step

All rewiring functions share the same keyword arguments:

Argument	Type	Default	Description
max_iter	int | "n"	"n"	Switching steps; "n" auto-computes bound N
accuracy	float	1e-5	Target accuracy δ for bound formula
exact	bool	False	Use exact vs approximate bound formula
verbose	bool	True	Print progress to stderr
seed	int | None	None	RNG seed (None = random)

Full API docs at pybirewirex.readthedocs.io. WORK IN PROGRES!!!

---

Development

git clone https://github.com/lorenzoamir/PyBiRewire
cd PyBiRewire
pip install -e ".[dev]"
pytest            # run test suite
ruff check .      # lint
ruff format .     # format

Build the Jupyter tutorial notebook:

jupyter notebook notebooks/tutorial.ipynb

Build docs locally:

cd docs && make html

---

Citation

If you use PyBiRewireX in published research, please cite the original BiRewire paper:

Iorio, F., Bernardo-Faura, M., Gobbi, A., Cokelaer, T., Jurman, G. and Saez-Rodriguez, J., Efficient randomization of biological networks while preserving functional characterization of individual nodes. BMC Bioinformatics, 17(1), p.542. (2016). http://doi.org/10.1186/s12859-016-1402-1

---

License

GPL-3.0-or-later — see LICENSE.