This repository contains the scDeepSim implementation and the experiments for evaluating controllable single-cell simulation. scDeepSim combines a structured variational autoencoder with latent diffusion to generate expression profiles and vary batch effects and trajectory structure for method benchmarking.
| Directory | Contents |
|---|---|
scdeepsim/src/scdeepsim/ |
Python package: VAE and diffusion models, data handling, and simulation controls. |
scdeepsim/tests/ |
Package and experiment tests. |
experiments/scripts/ |
Training, simulation, evaluation, and plotting entry points. |
experiments/configs/ |
Hydra configurations with data paths and experiment settings. |
experiments/src/ |
Shared preprocessing, comparator, metric, and benchmark utilities. |
experiments/notebooks/ |
Exploratory analyses and figures from saved results. |
experiments/environments/ |
Environment definitions for running the experiments. |
Start with the experiment guide. It provides environment setup, dataset sources, commands, and output locations for the four main experiments and the additional experiments:
| Experiment | Workflow |
|---|---|
| Simulation fidelity (Figure 2) | simulation_fidelity.py with the lung, pancreas, or immune config |
| Structured latent representations and batch interventions (Figure 3) | latent_predictability.py → eval_batch_dose_response.py |
| Batch integration (Figure 4) | benchmark_batch_integration.py |
| Trajectory inference (Figure 5) | prepare_ti_artifacts.py → prepare_ti_direction_artifacts.py → benchmark_ti.py with the direction config |
Scripts are under experiments/scripts/; trajectory scripts are in its
ti_benchmarking/ directory. Formal runs use the settings in
experiments/configs/. The scDiffusion comparator requires the
public upstream source and experiment patch.
Datasets, trained scDeepSim weights, and published-run sample archives are not bundled; follow the guide to obtain the inputs and generate the results.
With Python 3.10 or newer, install from the repository root:
python -m pip install -e ./scdeepsimReleased under the MIT License. Parts of the diffusion implementation were inspired by or adapted from lucidrains/denoising-diffusion-pytorch (MIT); see THIRD_PARTY_NOTICES.md.