SimSpace
SimSpace is a Python framework for simulating spatial omics data with realistic cellular distributions and tissue organization. Designed for benchmarking spatial analysis methods, SimSpace enables generation of synthetic datasets that preserve spatial autocorrelation, cell-cell interactions, and spatial proximities using a Markov Random Field (MRF) model.
For full figure reproduction (all analyses and scripts) for the SimSpace manuscript, see: https://github.com/TianxiaoNYU/simspace-reproducibility
📦 Installation
To install the latest version of SimSpace, we recommend using conda to setup the environment:
git clone https://github.com/TianxiaoNYU/simspace.git
- Create a conda environment for simspace
cd simspace
conda env create -f environment.yml
conda activate simspace
- Install simspace from PyPi
pip install simspace
🧬 Optional: Setting Up the R Environment for Omics Simulation
SimSpace supports external omics profile simulation via R-based tools, including scDesign3, SRTsim, and splatter. These tools are optional but recommended if you want to simulate gene expression profiles in addition to spatial patterns.
To enable this functionality, please install the required R packages manually in your system R environment:
Steps:
- Ensure that R (version 4.4 or compatible) is installed on your system. You can download it from CRAN.
- Open an R session and install the required packages:
if (!require("devtools", quietly = TRUE))
install.packages("devtools")
devtools::install_github("SONGDONGYUAN1994/scDesign3")
devtools::install_github("xzhoulab/SRTsim")
if (!require("devtools", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install(c("splatter"))
Once installed, SimSpace will automatically use these tools when relevant R-based simulations are requested.
📖 Documentation
Full documentation for SimSpace is available at:
The documentation includes:
- Installation instructions (Python + optional R setup)
- Tutorials (reference-free & reference-based simulation)
- API reference for all modules and functions
📘 Tutorials
To get started with SimSpace, we provide detailed tutorials covering both reference-based and reference-free simulation modes.
- Step-by-step tutorials can be found in
tutorials.md - Executable notebooks are located in the
tutorials/directory
These resources walk through how to configure and run simulations as well as visualize outputs.
🚀 Quick Start
Here’s a basic example to simulate a 2D tissue with 3 spatial niches and 8 cell types:
from simspace import util, spatial
# Define simulation parameters
params = util.generate_random_parameters(
n_group=3,
n_state=8,
seed=42)
# Run simulation
sim = util.sim_from_params(
params,
shape=(50, 50), # shape of the simulation grid
custom_neighbor=spatial.generate_offsets(3, 'manhattan'),
seed=42
)
# Visualize
sim.plot()
# Check and save the simulated spatial data
sim.meta.head()
# sim.meta.to_csv('simspace.csv')
Optional direct spatial expression and observation effects
The built-in reference-free Gamma--Poisson generator keeps its original phenotype-conditioned behavior by default. Direct coordinate-conditioned expression, capture loss, background contamination, and excess dropout are available only when explicitly configured:
sim.create_omics(
n_genes=1000,
direct_spatial_effects={
"genes": ["Gene_0", "Gene_1"],
"basis": "linear",
"coefficients": {
"Gene_0": [1.0, 0.0],
"Gene_1": [0.0, -1.0],
},
"coordinate_scaling": "unit_range",
},
technical_noise={
"capture_efficiency": 0.8,
"ambient_rate": 2.0,
"seed": 101,
},
dropout={
"mode": "mean_dependent",
"intercept": 0.5,
"slope": -1.0,
"seed": 102,
},
store_intermediate=True,
)
The supported spatial bases are linear, radial, hotspot, and
structure_distance. With all new arguments omitted, create_omics() uses
the unchanged legacy execution path. When store_intermediate=True, SimSpace
retains the latent mean, baseline and observed counts, spatial-gene truth, and
dropout realization for benchmarking.
🙋♀️ About
Developed by Tianxiao Zhao at NYU Grossman School of Medicine. Should you have any questions, please contact Tianxiao Zhao at Tianxiao.Zhao@nyulangone.org
🔗 References
If you use SimSpace in your work, please cite the work on BioRxiv: Zhao T, Zhang K, Hollenberg M, Zhou W, Fenyo D. SimSpace: a comprehensive in-silico spatial omics data simulation framework. bioRxiv. 2025:2025.07.18.665587.
Metadata
Release files for simspace 0.3.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| simspace-0.3.4.tar.gz | 180.3 kB | Without provenance | Details for simspace-0.3.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| simspace-0.3.4-py3-none-any.whl | Python 3 | none | any | Details for simspace-0.3.4-py3-none-any.whl |
Total release size: 361.6 kB
Release files / simspace-0.3.4.tar.gz
| Download URL | simspace-0.3.4.tar.gz |
|---|---|
| Size | 180.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5c521ea001eb9e97671e8ad8b13e132e8faeb726b6358ae9b573d256b9b962ea
|
|
BLAKE2b-256 checksum How to use checksums |
fba996741b00612eeab9d802825282fe9433345ab4105d67c9c9b6b51a6ac1ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.13
|
Release files / simspace-0.3.4-py3-none-any.whl
| Download URL | simspace-0.3.4-py3-none-any.whl |
|---|---|
| Size | 181.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
84463b58e7c72ff3e1d5116a87d88141f225c4ae4196d460fc9274db275fb98b
|
|
BLAKE2b-256 checksum How to use checksums |
4c69cab8625ce12dc8d7861b4bc5e7bd1b4492925681eab75a456073bbb756b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.13
|
Security for simspace 0.3.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.