edge-of-chaos
Build a stability matrix from a gene regulatory network (real or randomly generated) and check whether it sits at the edge of chaos, based on the May-Wigner random matrix model.
Overview
Install
pip install edge-of-chaos
Quick usage (E. coli / RegulonDB)
A RegulonDB-format parser is included for E. coli. It turns a RegulonDB TSV into a stability matrix:
import numpy as np
from edge_of_chaos import (
parse_regulondb_lines,
filter_edges,
deduplicate_edges,
build_gene_index,
weighted_matrix,
is_stable,
)
raw = parse_regulondb_lines("ecoli_grn.tsv")
edges = deduplicate_edges(filter_edges(raw))
index = build_gene_index(edges)
rng = np.random.default_rng(0)
A = weighted_matrix(edges, index, sigma=0.3, rng=rng)
is_stable(A)
Using your own network
parse_regulondb_lines only understands RegulonDB's TSV format. For any other organism or dataset, write your own parser that produces a list of Edge objects. Everything after that point (build_gene_index, weighted_matrix, etc.) works the same regardless of where the edges came from.
import numpy as np
from edge_of_chaos import Edge, build_gene_index, weighted_matrix
edges = [
Edge(regulator="geneA", target="geneB", sign=1, confidence="C"),
Edge(regulator="geneB", target="geneC", sign=-1, confidence="C"),
Edge(regulator="geneC", target="geneA", sign=-1, confidence="C"),
]
index = build_gene_index(edges)
rng = np.random.default_rng(0)
A = weighted_matrix(edges, index, sigma=0.3, rng=rng)
sign is 1 or -1. confidence can be any string your own parser uses, it isn't read by anything downstream.
signed_matrix vs weighted_matrix
signed_matrix puts only the sign of each edge (1 or -1) in the matrix, no magnitude. weighted_matrix does the same but also draws a random magnitude for each edge, scaled by sigma. Use signed_matrix if you just want to look at the network's sign structure. Use weighted_matrix for stability checks, since the May-Wigner result is about the magnitudes, not just the signs.
from edge_of_chaos import signed_matrix, weighted_matrix
S = signed_matrix(edges, index) # entries are -1, 0, or 1
A = weighted_matrix(edges, index, sigma=0.3, rng=rng) # entries are signed random magnitudes
Self-loop nudge
self_loop_nudged_matrix builds the same matrix as weighted_matrix, except self-loop edges (regulator == target) get a fixed magnitude, sigma * nudge_scale, instead of a fresh random draw each time.
from edge_of_chaos import self_loop_nudged_matrix
A = self_loop_nudged_matrix(edges, index, sigma=0.3, rng=rng, nudge_scale=0.5)
nudge_scale (default 0.5) sets that fixed strength relative to sigma.
Checking stability
from edge_of_chaos import is_stable, spectral_abscissa, stable_fraction
is_stable(A) # True/False
spectral_abscissa(A) # largest real part among A's eigenvalues
# fraction of random matrices that come out stable at a given sigma
sampler = lambda sigma, rng: weighted_matrix(edges, index, sigma, rng)
stable_fraction(lambda r: sampler(0.3, r), trials=50, rng=np.random.default_rng(0))
Finding the critical sigma
theory.critical_sigma gives May's closed-form prediction for the sigma at which a network of a given size and connectance crosses from stable to unstable. It assumes a homogeneous, fully random network.
For a real network, the actual critical sigma can be different, so empirical_critical_sigma finds it directly: it bisects on sigma, running many random trials at each candidate value, until it finds where the fraction of stable trials crosses 0.5.
from edge_of_chaos import critical_sigma
from edge_of_chaos.stability import empirical_critical_sigma
n, C = len(index), 0.05
theory_sigma = critical_sigma(n, C)
sampler = lambda sigma, rng: weighted_matrix(edges, index, sigma, rng)
empirical_sigma = empirical_critical_sigma(sampler, low=0.01, high=1.0, rng=np.random.default_rng(0))
Tests
pytest
License
MIT
Metadata
Release files for edge-of-chaos 0.1.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| edge_of_chaos-0.1.4.tar.gz | 126.1 kB | With provenance | Details for edge_of_chaos-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| edge_of_chaos-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for edge_of_chaos-0.1.4-py3-none-any.whl |
Total release size: 135.9 kB
Release files / edge_of_chaos-0.1.4.tar.gz
| Download URL | edge_of_chaos-0.1.4.tar.gz |
|---|---|
| Size | 126.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5e581a1607f4b63d3009427a7832263a206f657da2d65f05580899181afe41c8
|
|
BLAKE2b-256 checksum How to use checksums |
1a4351df2203478fa23040f99c5307cbb0d35df6b943c59b1416e91f1ca741e2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logRelease files / edge_of_chaos-0.1.4-py3-none-any.whl
| Download URL | edge_of_chaos-0.1.4-py3-none-any.whl |
|---|---|
| Size | 9.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d1f2743bb878a66fbdf47a98ee2d95a3ee55647773b31385c9601ca880a0a7e6
|
|
BLAKE2b-256 checksum How to use checksums |
b841eb6749721ed04a3d73fb897072cb9c4aa112c52f0a8769609cf9a6689964
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logSecurity for edge-of-chaos 0.1.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for edge_of_chaos-0.1.4.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.