SimSpace
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.
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.
- Install R 4.4 or a compatible version from CRAN.
- 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")
- 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.