https://github.com/emcramer/tmelandscape
https://github.com/emcramer/tmelandscape
Last synced: 22 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/emcramer/tmelandscape
- Owner: emcramer
- License: bsd-3-clause
- Created: 2026-05-12T23:49:25.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-14T23:28:55.000Z (about 1 month ago)
- Last Synced: 2026-05-16T20:48:17.000Z (about 1 month ago)
- Language: Python
- Size: 2.46 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.cff
- Agents: AGENTS.md
Awesome Lists containing this project
README
# tmelandscape
[](LICENSE)
**tmelandscape** generates tumor microenvironment (TME) state landscapes from agent-based model (ABM) simulation ensembles. It implements the parameter sampling, spatial-statistic summarisation, time-delay embedding, and clustering steps of the trajectory-landscape pipeline described in EM. Cramer, LM. Heiser and YH. Chang, "Trajectory Landscapes for Therapeutic Strategy Design in Agent-Based Tumor Microenvironment Models," in _IEEE Control Systems Letters_, [doi: 10.1109/LCSYS.2026.3697136]().
> **Status:** pre-alpha (v0.0.1). API is not yet stable.
## Pipeline scope
`tmelandscape` implements steps **1**, **3**, **4**, and **5** below; step 2 (running ABM simulations) is handled by a separate tool.
1. **Sample** ABM parameter space (Latin Hypercube via [pyDOE3](https://pypi.org/project/pyDOE3/)) and pair with initial cell positions from [`tissue_simulator`](https://github.com/emcramer/tissue_simulator). Produces a sweep manifest.
2. *(External)* **Run** PhysiCell simulations for each manifest row. Out of scope.
3. **Summarise** each simulation with spatial statistics via [`spatialtissuepy`](https://github.com/emcramer/spatialtissuepy); aggregate into a chunked Zarr store.
4. **Embed** the spatial-statistic time series with time-delay (Takens) embedding; optimise dimension via False Nearest Neighbours and lag via mutual information.
5. **Cluster** the embedding to identify discrete TME states (default: hierarchical agglomerative + Ward).
## Quick start
```bash
# 1. Install uv (https://docs.astral.sh/uv/)
# 2. Sync the environment
uv sync --all-extras
# 3. Run tests
uv run pytest
# 4. Serve the docs locally
uv run mkdocs serve
# 5. Start the MCP server (for LLM agents)
uv run tmelandscape-mcp
```
## Documentation
Full docs live at (once published). Locally:
```bash
uv run mkdocs serve
```
Key documents:
- [Project roadmap](docs/development/ROADMAP.md)
- [Current status / handoff](docs/development/STATUS.md)
- [Architecture Decision Records](docs/adr/)
- [Agent handoff conventions](AGENTS.md)
## License
BSD 3-Clause. See [LICENSE](LICENSE).
## Citing
See [CITATION.cff](CITATION.cff) for the software citation; cite the following manuscripts for the methodology:
> 1. Cramer, E., Heiser, L. M. & Chang, Y. H. Trajectory Landscapes for Therapeutic Strategy Design in Agent-Based Tumor Microenvironment Models. Preprint at https://doi.org/10.48550/arXiv.2603.18333 (2026).
> 2. Cramer, E. M. et al. Tumor-immune trajectory context connects static tissue architecture to clinical outcomes. 2026.03.26.714521 Preprint at https://doi.org/10.64898/2026.03.26.714521 (2026).