model-graph-drawer

Automatically draw interaction graphs for systems biology models.

Species (states) are rendered as bold text labels. Reactions are drawn as direct arrows between species, labelled with their rate constants. Modifier arrows (dashed red, + at the tip) are drawn from a species to the midpoint of the reaction whose rate it influences.

Installation

Source: https://gitlab.liu.se/ISBgroup/projects/model-graph-drawer

pip install model-graph-drawer
# or with uv
uv add model-graph-drawer

Requires Python ≥ 3.10.

Dependencies

Package	Version	Role
matplotlib	≥ 3.5	Rendering arrows, labels, and axes
networkx	≥ 3.0	Graph data structure and layout algorithms (Kamada–Kawai, spring, circular, spectral)
numpy	≥ 1.20	Vector geometry for arc midpoints, perpendicular calculations, and curvature

---

Quick start

Reaction-string format

from model_graph_drawer import Model, draw
import matplotlib.pyplot as plt

model = Model.from_reactions([
    "-> A   : k1",      # synthesis  (source)
    "A -> B : k2*A*C",  # A→B, rate depends on C  →  C is a modifier
    "B -> C : k3*B",
    "C ->   : k4*C",    # degradation (sink)
])

draw(model, title="A → B → C with C as modifier")
plt.show()

Or load from a multi-line string:

model = Model.from_text("""
    -> A   : k1
    A -> B : k2*A*C
    B -> C : k3*B
    C ->   : k4*C
""")

The shortcut model.draw(...) is equivalent to draw(model, ...).

sund model files

model = Model.from_sund("path/to/model.txt")
model.draw(title="My model")
plt.show()

---

Reaction format

[reactants] -> [products] : rate_expression

Example	Meaning
-> A : k1	Source — A is produced at rate k1
A -> B : k2*A*C	A is converted to B; C is a modifier
B -> C : k3*B	Simple first-order conversion
C -> : k4*C	Sink — C is degraded
A + B -> C : k*A*B	Bimolecular reaction

Modifier detection — any species that appears in the rate expression but is not a reactant is automatically detected as a modifier and drawn with a dashed arrow.

---

Relationship to sund

model-graph-drawer is a generic visualisation library — it works with any reaction network you can express in the reaction-string format. It also has first-class support for sund model files, developed by the same team.

When a sund .txt file is loaded, the parser extracts not only the reaction stoichiometry but also the INPUTS, OUTPUTS, and FEATURES sections, which are reflected in the graph as distinct visual styles:

Role	Visual style
Input (external signal)	Dashed green border
Output (exposed to other models)	Solid orange border
Feature (observable quantity)	Pale yellow background

model = Model.from_sund("path/to/model.txt")
model.draw(title="My sund model")

---

sund file format

The parser reads the STATES and VARIABLES sections of a .txt sund model file.

########## STATES
d/dt(R)  = r2 - r1
d/dt(Rp) = r1 - r2
...

########## VARIABLES
r1 = R*A*k1
r2 = Rp*k2

Stoichiometry is inferred from the signs in each d/dt expression. Identifiers in the rate expression that are neither species nor mathematical operators are used as reaction labels.

---

API

Model.from_reactions(reactions: list[str]) -> Model
Model.from_text(text: str) -> Model
Model.from_sund(path: str) -> Model

draw(
    model,
    *,
    ax=None,         # matplotlib Axes; created automatically when None
    figsize=(10, 7), # inches, used only when ax is None
    layout="kamada_kawai",
    title=None,
) -> plt.Axes

Layout options

Value	Description
"kamada_kawai" (default)	Minimises edge crossings
"spring"	Force-directed
"circular"	All nodes on a circle
"spectral"	Eigenvector-based

Programmatic access

import networkx as nx
from model_graph_drawer import build_graph

G = build_graph(model)   # nx.DiGraph with species + reaction nodes
# node attribute  node_type : 'species' | 'reaction'
# edge attribute  edge_type : 'consumption' | 'production' | 'modifier'

---

AI disclosure

This project was developed with the assistance of Claude (Anthropic). Parts of the code, documentation, and tests were written or refined using AI-assisted pair programming.