Skip to main content

SimSpace

Docs PyPI

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.

SimSpace Workflow

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:

  1. Ensure that R (version 4.4 or compatible) is installed on your system. You can download it from CRAN.
  2. 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:

➡️ simspace.readthedocs.io

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)

Source distribution for simspace 0.3.4
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)

Table of built distributions (wheels) for simspace 0.3.4
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page