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.0 provides both a Python API and a headless command-line interface for reference-free and reference-based simulations.

SimSpace workflow

Installation

Install the released package:

pip install simspace

Or install the current source:

git clone https://github.com/TianxiaoNYU/simspace.git
cd simspace
pip install .

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.

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.0

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.0
File Size Uploaded Provenance Actions
simspace-0.4.0.tar.gz 188.7 kB Without provenance Details for simspace-0.4.0.tar.gz

Built distribution (wheel)

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

Total release size: 376.7 kB

Release files / simspace-0.4.0.tar.gz

Download URL simspace-0.4.0.tar.gz
Size 188.7 kB
Tags Source
SHA-256 checksum
How to use checksums
666a32339159a67b02fa0a89c3e52388336c80b04b1f5bc31203407931ba2927
BLAKE2b-256 checksum
How to use checksums
b7c1ce03b6ac9563e1e6ad7936e241db45f463ba2b0167649bdca7cdbb83864e
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.0-py3-none-any.whl

Download URL simspace-0.4.0-py3-none-any.whl
Size 188.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ce3179ebb92eb21349fa79654a51d3b96035d5017350eef9f79cc3cb33263416
BLAKE2b-256 checksum
How to use checksums
496b31aff5e117e61ff7ee0ea40aef168388866388eca1d40acafb628e721c51
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.0

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