Skip to content

gpgraph-v2

NetworkX-backed, Rust-accelerated graphs over genotype-phenotype maps. Lifts a gpmap-v2 GenotypePhenotypeMap into a NetworkX DiGraph, populates edges under Hamming or codon distance, and overlays fixation-probability edge weights for evolutionary trajectory analysis.

Genotype-phenotype graph laid out by Hamming distance, nodes colored by phenotype, edge widths set by SSWM fixation probability Genotype-phenotype graph laid out by Hamming distance, nodes colored by phenotype, edge widths set by SSWM fixation probability

  • Quickstart

    Build a graph from a GenotypePhenotypeMap, add a fixation model, and pull forward-path probabilities.

    Read the quickstart

  • Installation

    Install from PyPI. Matplotlib is an optional extra.

    Install gpgraph-v2

  • Concepts

    Graph model, neighbor kernels, and the fixation-model registry.

    Learn the model

  • Reference

    Per-module API for the graph, neighbors, fixation models, paths, and pyplot.

    Browse the reference

What it does

  • Lift a map into a graph. GenotypePhenotypeGraph.from_gpm(gpm) returns a NetworkX DiGraph with one node per genotype and directed edges between neighbors.
  • Plug in a fixation model. Pick from sswm, ratio, moran, mcclandish, or bring your own callable. add_model(column="phenotypes", model="sswm") populates the prob edge attribute in one vectorized numpy pass.
  • Enumerate trajectories. forward_paths, forward_paths_prob, and the flux helpers give you the shortest paths from WT to target and their probability mass.
  • Plot when needed. The optional gpgraph.pyplot subpackage draws the graph with a Hamming-layer layout and overlays path flux on the edges.

Why v2

  • Fast. Neighbor detection runs in Rust with rayon parallelism. Biallelic cutoff-1 and cutoff-2 hit a bit-flip fast path: O(N * L^cutoff) instead of O(N^2 * L).
  • Typed. Full type hints, mypy --strict in CI.
  • Modern tooling. uv plus maturin plus pyproject.toml. Releases via python-semantic-release. OIDC-based PyPI publishing.
  • Consumes gpmap-v2. Speaks the locked schema contract; reads binary_packed, n_mutations, and phenotypes.
  • No Cython, no setup.py, no .c blobs.

Live demo

A multi-page Streamlit tour is published at gpgraph-v2.streamlit.app (source under examples/streamlit/ in the repo).

Next steps