Skip to main content

SimSpace

Docs PyPI

SimSpace is a Python framework for generating spatial omics data with controllable tissue niches, cell-type organization, and molecular profiles. Version 0.4.1 provides both a Python API and a headless command-line interface for reference-free and reference-based simulations.

SimSpace workflow

Installation

We recommend using the supplied environment.yml to create a Conda environment for SimSpace:

git clone https://github.com/TianxiaoNYU/simspace.git
cd simspace
conda env create -f environment.yml
conda activate simspace

Install the released SimSpace package in this environment:

python -m pip install simspace

Optional R dependencies

The native molecular-profile generator does not require R. To run the optional scDesign3, SRTsim, or Splatter adapters in either SimSpace or the manuscript reproducibility workflows, install the corresponding R packages once in your normal local R environment. Do not create a separate R virtual environment. See Optional R molecular-profile adapters for the local installation commands.

Command-line quick start

Reference-free simulation

This command generates a new spatial layout and native Gamma--Poisson molecular profiles without a reference dataset:

simspace reference-free \
  --output-dir results/reference_free \
  --shape 100 100 \
  --n-niches 3 \
  --n-cell-types 8 \
  --neighbor-distance 3 \
  --cell-sweeps 4 \
  --niche-sweeps 6 \
  --jitter 0.2 \
  --n-genes 100 \
  --bg-ratio 0.6 \
  --lr-ratio 0.2 \
  --bg-param 1 0.5 \
  --marker-param 5 1.6 \
  --seed 42

Use simspace reference-free --help to see all supported options. To reuse or edit an existing spatial design, replace the random-parameter options with --params parameters.json.

Reference-based simulation

Reference-based simulation requires cell metadata with two numeric coordinate columns and one categorical cell-type column. A previously fitted parameter file gives the shortest workflow:

simspace reference-based \
  --reference-metadata data/reference_metadata.csv \
  --cell-type-column Cluster \
  --x-column x_centroid \
  --y-column y_centroid \
  --params data/fitted_params.json \
  --profile-model native \
  --shape 100 100 \
  --n-genes 100 \
  --output-dir results/reference_based \
  --seed 42

To calibrate spatial parameters from the supplied metadata instead, replace --params ... with, for example:

--fit-spatial --n-niches 2 --population-size 20 --generations 10

Calibration can be time-consuming, so the command requires an explicit choice between --params and --fit-spatial.

By default, --profile-model native generates Gamma--Poisson profiles after the reference-based spatial layout is created. To fit molecular profiles from a reference matrix, supply --reference-counts and select scdesign3 or srtsim; these two adapters require their corresponding R packages. The scDesign3 adapter automatically uses negative-binomial marginals for integer-valued counts and log-Gaussian marginals for nonnegative continuous intensities. Use --scdesign-family nb or --scdesign-family gaussian to override that detection when the measurement type is known.

Output files

Every successful command writes the same four files:

results/reference_free/
├── metadata.csv
├── molecular_profiles.csv.gz
├── spatial_scatter.png
└── parameters.json
File Contents
metadata.csv One row per cell with cell_id, x, y, niche, and cell_type
molecular_profiles.csv.gz One row per cell and one column per molecular feature, linked by cell_id
spatial_scatter.png Headless scatterplot of the simulated cell-type distribution
parameters.json Exact generated, supplied, or fitted spatial parameters for reuse

Example metadata:

cell_id,x,y,niche,cell_type
cell_000001,-0.04,0.17,1,CellType_3
cell_000002,0.91,-0.05,1,CellType_1
cell_000003,1.88,0.00,0,CellType_3

For two-dimensional simulations, x is the horizontal coordinate (the Python object's col) and y is the vertical coordinate (row). The cell IDs and row order are identical in the metadata and molecular-profile files. Existing output files are protected unless --overwrite is supplied.

Which parameters should I change?

Goal Main options
Change tissue size --shape ROWS COLS
Change organizational complexity --n-niches, --n-cell-types
Change local spatial scale --neighbor-distance, --neighbor-method
Change sampling depth --cell-sweeps, --niche-sweeps
Change cell retention and coordinate displacement --density-min, --density-max, --jitter
Change reference-free affinity ranges --theta-max, --niche-theta-max, --phi-min, --phi-max
Change molecular feature composition --n-genes, --bg-ratio, --lr-ratio, --bg-param, --marker-param
Change reference calibration --population-size, --generations, --mutation-rate, --crossover-rate, --replicates

Positive affinity values favor local co-occurrence, negative values favor separation, and the phi range controls overall spatial smoothness. Use a saved parameters.json when exact affinities or densities should be edited directly.

Background and batch execution

The CLI is noninteractive and uses headless plotting, so either simulation mode can run under nohup, a shell script, or a cluster scheduler:

mkdir -p logs
nohup simspace reference-free \
  --output-dir results/run_01 \
  --shape 100 100 \
  --n-niches 3 \
  --n-cell-types 8 \
  --n-genes 1000 \
  --seed 42 \
  > logs/run_01.log 2>&1 &

The process returns exit status 0 on success and a nonzero status with an error message on failure. The same approach applies to reference-based.

Python API quick start

The existing Python interface remains unchanged:

from simspace import spatial, util

params = util.generate_random_parameters(n_group=3, n_state=8, seed=42)
sim = util.sim_from_params(
    params,
    shape=(50, 50),
    custom_neighbor=spatial.generate_offsets(3, "manhattan"),
    seed=42,
)
sim.create_omics(n_genes=100)
sim.plot()

Advanced direct spatial-expression and observation-effect controls remain available through SimSpace.create_omics() in the Python API.

Tutorials and documentation

The notebooks provide step-by-step explanations but are not required for command-line execution.

Optional R molecular-profile adapters

SimSpace supports scDesign3, SRTsim, and Splatter as optional molecular-profile generators. Install these packages once in your normal local R environment; no separate R virtual environment is required.

  1. Install R 4.4 or a compatible version from CRAN.
  2. In the local R session, install scDesign3 and SRTsim:
if (!require("devtools", quietly = TRUE))
    install.packages("devtools")

devtools::install_github("SONGDONGYUAN1994/scDesign3")
devtools::install_github("xzhoulab/SRTsim")
  1. Install Splatter if that adapter is needed:
if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("splatter")

SimSpace uses these packages from the local R installation only when the corresponding optional adapter is requested. The native CLI molecular-profile model does not require R.

License and citation

SimSpace is released under the MIT License.

If you use SimSpace, please cite:

Zhao T, Zhang K, Hollenberg M, Zhou W, Fenyo D. SimSpace: a comprehensive in-silico spatial omics data simulation framework. bioRxiv. 2025. doi:10.1101/2025.07.18.665587

Questions can be directed to Tianxiao Zhao at Tianxiao.Zhao@nyulangone.org.

Metadata

Release files for simspace 0.4.1

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.4.1
File Size Uploaded Provenance Actions
simspace-0.4.1.tar.gz 191.1 kB Without provenance Details for simspace-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for simspace 0.4.1
File Interpreter ABI Platform Actions
simspace-0.4.1-py3-none-any.whl Python 3 none any Details for simspace-0.4.1-py3-none-any.whl

Total release size: 380.6 kB

Release files / simspace-0.4.1.tar.gz

Download URL simspace-0.4.1.tar.gz
Size 191.1 kB
Tags Source
SHA-256 checksum
How to use checksums
7cb819f690bb9bd43426e9dda7a9df6687d4cb1af75681b1380cb3a73af174f2
BLAKE2b-256 checksum
How to use checksums
cb8cf5cb1d003a341118480248a56b0602cec5f132c963cd54f8255bd8ee759b
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.4.1-py3-none-any.whl

Download URL simspace-0.4.1-py3-none-any.whl
Size 189.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bc89bad918c46aa8b5d9ed0c8d68cea665d2b1fc5ce4f7f4e5d6fdb2d4e0c675
BLAKE2b-256 checksum
How to use checksums
f496167f9b9dbe1bbf223c9efe62d29a2c0c7fffd96ea672014041dcfc2abd66
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.4.1

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