Metadata-Version: 2.4
Name: kinetic-st
Version: 0.1.1
Summary: Kinetic-theory framework for multiscale modelling of spatial transcriptomics
Author: KineticST Project Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/whirlsyu/kinetic_st
Project-URL: Repository, https://github.com/whirlsyu/kinetic_st.git
Project-URL: Issues, https://github.com/whirlsyu/kinetic_st/issues
Keywords: spatial-transcriptomics,kinetic-theory,bioinformatics,single-cell
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: matplotlib>=3.7; extra == "dev"
Provides-Extra: demo
Requires-Dist: matplotlib>=3.7; extra == "demo"

# KineticST

Kinetic-theory framework for multiscale modelling of spatial transcriptomics.

Bridges microscopic cell-cell interactions to macroscopic tissue organisation
via a Boltzmann-like collision operator on latent cell states, integrated on
a spatial graph with stochastic dynamics and invariant-measure analysis.

## Installation

```bash
pip install kinetic-st
```

For development (editable install):

```bash
pip install -e .
```

## Quick start

```python
import numpy as np
from kinetic_st import KineticST, KineticSTConfig, generate_kinetic_simulation

# Synthetic data
sim = generate_kinetic_simulation(n_types=6, n_spots=1600, seed=42)

# Fit
model = KineticST(KineticSTConfig(n_steps=150, latent_dim=10, verbose=True))
model.fit(sim.Y, sim.coords)

# Results
labels = model.get_domain_labels()
field = model.get_expression_field()
print(model.summary())
```

## Pipeline stages

1. **Latent embedding** — PCA on log-CPM expression to a low-dimensional cell-state space
2. **Spatial graph** — kNN adjacency from coordinates
3. **Collision kernel** — ligand-receptor rule with irreversible attractor bias
4. **Kinetic integration** — deterministic (Boltzmann), stochastic (Euler-Maruyama), or time-sliced solver
5. **Moment closure** — macroscopic tissue expression fields via local KDE moments
6. **Invariant measure** — non-equilibrium steady-state estimation (KDE or GMM)
7. **Spatial domains** — segmentation via local invariant-measure divergence
8. **Supervised markers** — one-vs-rest z-scores on the dynamics-smoothed field

## License

MIT
