Metadata-Version: 2.4
Name: model-graph-drawer
Version: 0.1.0
Summary: Draw interaction graphs from systems biology reaction models
Author: William Lövfors
Maintainer: William Lövfors
License-Expression: MIT
Project-URL: Homepage, https://gitlab.liu.se/ISBgroup/projects/model-graph-drawer
Project-URL: Repository, https://gitlab.liu.se/ISBgroup/projects/model-graph-drawer
Project-URL: Bug Tracker, https://gitlab.liu.se/ISBgroup/projects/model-graph-drawer/-/issues
Keywords: systems biology,reaction network,interaction graph,visualization,ODE,sund
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx>=3.0
Requires-Dist: matplotlib>=3.5
Requires-Dist: numpy>=1.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# 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>

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

Requires Python ≥ 3.10.

### Dependencies

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

---

## Quick start

### Reaction-string format

```python
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:

```python
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

```python
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](https://gitlab.liu.se/ISBgroup/projects/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 |

```python
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

```python
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

```python
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](https://claude.ai) (Anthropic).
Parts of the code, documentation, and tests were written or refined using AI-assisted pair programming.
