Skip to main content

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

Overview Diagram

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.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for edge-of-chaos 0.1.3
File Size Uploaded Provenance Actions
edge_of_chaos-0.1.3.tar.gz 126.1 kB With provenance Details for edge_of_chaos-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for edge-of-chaos 0.1.3
File Interpreter ABI Platform Actions
edge_of_chaos-0.1.3-py3-none-any.whl Python 3 none any Details for edge_of_chaos-0.1.3-py3-none-any.whl

Total release size: 135.9 kB

Release files / edge_of_chaos-0.1.3.tar.gz

Download URL edge_of_chaos-0.1.3.tar.gz
Size 126.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a16900534c2994be543e62f287c8b2be2a16a6d35b5768c9adf7666e7cb3602e
BLAKE2b-256 checksum
How to use checksums
1e9dfc83365b2e9d3d3ede83be7b8f8d0659f699f17a4ee2e04d51664d0f5325
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 log

Release files / edge_of_chaos-0.1.3-py3-none-any.whl

Download URL edge_of_chaos-0.1.3-py3-none-any.whl
Size 9.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2098d5a95ebc5025c409efe4960ab1e64c85103a2cab8d46e9d680370f5f13ba
BLAKE2b-256 checksum
How to use checksums
719fa7060ce9310776a895629337492b6ba2f7752f97a032b38976d1564ffd09
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 log

Security for edge-of-chaos 0.1.3

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.

Select from 2 files

Attestation for edge_of_chaos-0.1.3.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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page