Metadata-Version: 2.4
Name: sogen-bio
Version: 0.1.0
Summary: Generative modeling of omics readouts from spatial niche context, for single- and multi-modal spatial omics data.
Author-email: "Bao Lab, Fudan University" <fbao0110@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/BaoLab-fudan/soGEN
Project-URL: Repository, https://github.com/BaoLab-fudan/soGEN
Project-URL: Issues, https://github.com/BaoLab-fudan/soGEN/issues
Keywords: spatial transcriptomics,spatial omics,generative model,single-cell,multi-modal,bioinformatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
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
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=1.12
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Provides-Extra: examples
Requires-Dist: scikit-learn>=1.0; extra == "examples"
Requires-Dist: jupyter; extra == "examples"
Requires-Dist: matplotlib; extra == "examples"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# soGEN

**soGEN** generates realistic omics readouts (RNA, surface protein, chromatin accessibility, ...)
from spatial niche context — e.g. the multi-scale neighborhood composition around each cell or
spot — using zero-inflated / count / continuous likelihood models. It supports both **single-modal**
(one omics readout) and **multi-modal** (two jointly modeled readouts) generation.

Full documentation: **https://baolab-fudan.github.io/soGEN/** · Demo notebooks: [single-modal](examples/demo_1_single_modal.ipynb) · [multi-modal](examples/demo_2_multimodal.ipynb)

## Installation

```bash
pip install sogen-bio
```

Requires Python >= 3.9 and PyTorch (installed automatically as a dependency).

## Quickstart

```python
from sogen import soGEN

# niches: list of niche/context feature matrices (DataFrame or array), one row per spot/cell
# x: target omics matrix (DataFrame or array), one row per spot/cell, one column per feature
model = soGEN(niches, x, mode="ZINB", device="cpu")
model.fit(niches, x, epochs=300, lr=1e-4, batch_size=256)

generated = model.generate(niches_new)   # DataFrame, same columns as x
model.save_model("model.pt")
```

For two jointly modeled omics readouts (e.g. RNA + protein):

```python
from sogen import soGEN_multimodal

model = soGEN_multimodal(niches, x1, x2, mode="ZINBZIPoisson", device="cpu")
model.fit(niches, x1, x2, epochs=300, lr=5e-4, batch_size=256)

x1_gen, x2_gen = model.generate(niches_new)
```

See [`examples/demo_1_single_modal.ipynb`](examples/demo_1_single_modal.ipynb) (Visium spatial
transcriptomics) and [`examples/demo_2_multimodal.ipynb`](examples/demo_2_multimodal.ipynb)
(spatial CITE-seq, RNA + protein) for complete, runnable walkthroughs on real data, including
how to build niche features from spatial coordinates and cluster labels.

## Choosing a distribution mode

| Data type | Single-modal `mode` | Multi-modal `mode` (x1, x2) |
|---|---|---|
| Sparse counts (RNA, ATAC) | `ZINB`, `NB` | `ZINBGaussian`, `ZINBPoisson`, `ZINBZIPoisson` |
| Moderately sparse counts (protein, ATAC) | `ZIPoisson`, `Poisson` | `ZIPoissonGaussian`, `PoissonGaussian` |
| Continuous (imaging features, embeddings) | `Gaussian` | combine with any of the above |

## Development

```bash
git clone https://github.com/BaoLab-fudan/soGEN.git
cd soGEN
pip install -e ".[dev,examples]"
python -m pytest tests/
```

## Citation

If you use soGEN in your research, please cite the accompanying manuscript (Bao Lab, Fudan
University). Citation details will be added upon publication.

## License

MIT — see [LICENSE](LICENSE).
