Metadata-Version: 2.5
Name: viva-mgen
Version: 0.1.0
Summary: Viva-native (process-bigraph) reproduction of the Karr et al. 2012 Mycoplasma genitalium whole-cell model
Project-URL: Homepage, https://github.com/vivarium-collective/viva-Mgen
Project-URL: Issues, https://github.com/vivarium-collective/viva-Mgen/issues
Author-email: Eran Agmon <agmon.eran@gmail.com>
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Requires-Dist: bigraph-schema
Requires-Dist: cobra
Requires-Dist: jsonschema[format-nongpl]>=4.21
Requires-Dist: numpy
Requires-Dist: plotly
Requires-Dist: process-bigraph>=1.11.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: scipy
Requires-Dist: viva-parsimony>=0.1.0
Provides-Extra: dev
Requires-Dist: matplotlib; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Provides-Extra: workspace
Requires-Dist: bigraph-viz>=2.0.3; extra == 'workspace'
Requires-Dist: jinja2>=3.1; extra == 'workspace'
Requires-Dist: matplotlib; extra == 'workspace'
Requires-Dist: pypdf>=4.0; extra == 'workspace'
Requires-Dist: vivarium-workbench; extra == 'workspace'
Requires-Dist: xarray; extra == 'workspace'
Requires-Dist: zarr; extra == 'workspace'
Description-Content-Type: text/markdown

# viva-mgen

<!-- BEGIN:badges -->
<!-- generated by `vivarium-workbench gen-readme` — edit the source, not this table -->

[![CI](https://github.com/vivarium-collective/viva-Mgen/actions/workflows/workspace-ci.yml/badge.svg)](https://github.com/vivarium-collective/viva-Mgen/actions/workflows/workspace-ci.yml)
[![read-only workbench](https://img.shields.io/badge/read--only_workbench-live-2ea44f)](https://vivarium-collective.github.io/viva-mgen/workbench/)
<!-- END:badges -->

<!-- BEGIN:dashboard -->
<!-- generated by `vivarium-workbench gen-readme` — edit the source, not this table -->

> ### 🔬 [Explore the interactive read-only dashboard →](https://vivarium-collective.github.io/viva-mgen/dashboard/)
>
> Every composite, study, and result — browsable in your browser, no install required.
> Published from `main` by the `publish-dashboard` workflow (allow a few minutes after the first push).
<!-- END:dashboard -->

A **viva-native (process-bigraph) clean-room reproduction** of the Karr et al.
2012 *Cell* whole-cell model of *Mycoplasma genitalium*
([A Whole-Cell Computational Model Predicts Phenotype from Genotype](https://www.cell.com/fulltext/S0092-8674(12)00776-3)).
Each cellular submodel is re-expressed as a native process-bigraph `Process`,
composed through shared cell-variable stores, and exercised by a showcase
**investigation with one study per figure** of the paper.

> **This is a reproduction, not the original.** Every process class is named
> `*ReproductionProcess` and is a from-scratch Python reimplementation of the
> corresponding Karr 2012 submodel — it is **not** the original MATLAB code and
> does **not** bridge to it. Fidelity is honest and per-study (see below):
> some figures are reproduced at full fidelity, others at reduced/representative
> fidelity, and each study says which.

## What it reproduces

The original whole-cell model integrates 28 submodels over 16 cell variables,
requires a MySQL knowledge base, and runs ~8–10 h per cell on a cluster. This reproduction now implements **all ~28 submodels** as reduced-but-genuine
process-bigraph Processes (29 `*ReproductionProcess` classes across
`viva_mgen/processes/`: metabolism, mass/growth, transcription, translation,
RNA/protein decay, replication, replication-initiation, DNA supercoiling/
condensation/segregation/damage/repair, transcriptional regulation, RNA
processing/modification, tRNA aminoacylation, protein processing I/II,
translocation, folding, modification, activation, complexation, ribosome &
terminal-organelle assembly, FtsZ polymerization, cytokinesis, host
interaction). The headline studies exercise this core:

| Submodel (reproduction) | Reproduces | Fidelity |
|---|---|---|
| `MetabolismFbaReproductionProcess` | FBA metabolism over the published Suthers 2009 **iPS189** network | full (the real reconstruction the WCM used) |
| `MassGrowthReproductionProcess` | mass accumulation, dry-mass composition, ~9 h doubling | full (fitted constants) |
| `TranscriptionReproductionProcess` | stochastic mRNA synthesis | reduced (representative gene panel) |
| `TranslationReproductionProcess` | stochastic protein synthesis | reduced |
| `RnaDecayReproductionProcess` / `ProteinDecayReproductionProcess` | Poisson decay | reduced |
| `ReplicationReproductionProcess` | dNTP-buffered three-phase cell cycle | reduced mechanism (genuine dynamics) |

### Data provenance

* **Metabolic network** — Suthers et al. 2009 *M. genitalium* reconstruction
  **iPS189** (BioModels `MODEL1507180052`, `datasets/ips189.sbml.xml`; 351
  reactions, 126 genes), the model the WCM's metabolism submodel was built on.
* **Gene list + reference essentiality** — extracted from the Karr 2012 repo
  (`datasets/genes.csv`, 525 genes).
* **Fitted constants** — mass fractions, cell-cycle length (32400 s ≈ 9 h),
  maintenance and exchange bounds, taken verbatim from the repo's
  `parameters.json` (`viva_mgen/constants.py`).

The original knowledge base's per-species / kinetic tables are locked inside
undecodable MATLAB MCOS objects; the iPS189 network and the paper stand in for
those.

## The investigation: one study per figure

`workspace/investigations/mgen/` binds seven studies, one per figure:

| Study | Figure | What it shows |
|---|---|---|
| `fig1-architecture` | Fig 1 | the integrated cell as composed pbg processes over shared stores |
| `fig2-growth` | Fig 2 | ~9 h doubling, dry-mass composition, growth curve |
| `fig3-expression` | Fig 3 | bursty low-copy mRNA, accumulating protein |
| `fig4-cell-cycle` | Fig 4 | emergent inverse initiation↔replication duration control |
| `fig5-energy` | Fig 5 | ATP/GTP production and expression energy budget |
| `fig6-gene-essentiality` | Fig 6 | in-silico single-gene KO vs reference essentiality |
| `fig7-kinetic-parameters` | Fig 7 | growth vs kinetic-parameter (kcat proxy) sweeps |

The workspace's investigations:

<!-- BEGIN:investigations -->
<!-- generated by `vivarium-workbench gen-readme` — edit the source, not this table -->

| Investigation | Research question |
|---|---|
| [viva-Mgen: reproducing the Karr 2012 M. genitalium whole-cell model, one study per figure _(running)_](https://vivarium-collective.github.io/viva-mgen/dashboard/reports/investigation-mgen.html) | Can the core cellular processes of the Karr et al. 2012 Mycoplasma genitalium whole-cell model be re-expressed as native process-bigraph Processes — composed through shared cell-variable stores — and… |
| [Structural model of M. genitalium — reproducing Maritan 2022 with viva-parsimony _(running)_](https://vivarium-collective.github.io/viva-mgen/dashboard/reports/investigation-structural-model.html) | Can the Maritan et al. 2022 3D whole-cell structural model of Mycoplasma genitalium be reproduced with viva-parsimony (the parsimony cellPACK-style engine) in place of CellPACK — packing the same mol… |
<!-- END:investigations -->

## Installation

    # development (editable)
    uv venv .venv && source .venv/bin/activate
    uv pip install -e ".[dev]"
    pytest

Once installed, processes register via `viva_mgen.core.build_core()`.

## Quick start

```python
from process_bigraph import Composite, gather_emitter_results
from viva_mgen.core import build_core
from viva_mgen.composites import fig2_growth

core = build_core()
sim = Composite({"state": fig2_growth(core)}, core=core)
sim.run(600.0)
print(gather_emitter_results(sim)[("emitter",)][-1])
```

Run a study locally:

    python workspace/studies/fig2-growth/sims/run.py

## API reference

| Class | Ports (in → out) |
|---|---|
| `MetabolismFbaReproductionProcess` | `nutrient_scale` → `growth_rate`, `growth_fraction`, `atp_production`, `gtp_production`, `feasible` |
| `MassGrowthReproductionProcess` | `growth_fraction`, `mass` → `mass`, `mass_fractions`, `volume`, `division` |
| `TranscriptionReproductionProcess` | `ntp`, `rna_pol` → `rna_counts`, `ntp` |
| `TranslationReproductionProcess` | `rna_counts`, `gtp` → `protein_counts`, `gtp` |
| `RnaDecayReproductionProcess` | `rna_counts` → `rna_counts` |
| `ProteinDecayReproductionProcess` | `protein_counts` → `protein_counts` |
| `ReplicationReproductionProcess` | `dntp_synthesis_scale` → replication phase/fraction/dNTP/durations |

## Limitations

* Reduced core, not the full 28-submodel model: chromosome occupancy (Fig 3
  original), 128-cell populations (Fig 3/4/5 distributions), and the full
  3,011-strain deletion scan (Fig 6/7) are represented at reduced fidelity —
  each study states its scope.
* Expression uses a representative gene panel, not all ~480 genes.
* Essentiality (Fig 6) is computed for the ~125 metabolic genes iPS189 covers
  (the paper notes metabolic genes are the most debilitating).

## License

MIT. The original whole-cell model and iPS189 are likewise MIT / CC-licensed;
see their upstreams.
