sogen-bio 0.1.0

Generative modeling of omics readouts from spatial niche context, for single- and multi-modal spatial omics data.

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 · multi-modal

Installation

pip install sogen-bio

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

Quickstart

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):

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 (Visium spatial transcriptomics) and 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

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.