lineage-simulator 0.1.1

A Single-Cell Lineage Simulator with Fate-Aware Gene Expression

LineageSim: A Single-Cell Lineage Simulator with Fate-Aware Gene Expression

A simulator for single-cell lineage tracing data that generates fate-aware gene expression — progenitor cells carry transcriptomic signatures of their descendants' fates, capturing a key property of real developmental data.

Installation

Requires Python >= 3.11.

Install as a package and import directly in your code:

# Using pip
pip install lineage-simulator

# Using uv
uv add lineage-simulator

Then in your code

from lineagesim.simulator import LineageSim

For development:

uv sync

CLI Usage

# See all available options
uv run lineagesim generate --help

# Generate with default parameters
uv run lineagesim generate -o dataset.h5ad

# An example showing full control of simulation parameters
uv run lineagesim generate \
    --n-cells 4096 --n-genes 500 --n-cif 32 \
    --beta 0.3 --sigma 0.5 --commit-depth 7 \
    --gene-effect-prob 0.3 --scale-s 1.0 \
    --protocol UMI --skip-technical-noise \
    --seed 42 -o dataset.h5ad

Python Quickstart

from lineagesim.simulator import LineageSim

sim = LineageSim()
tree, expression = sim.generate_dataset(
    n_cells=8192,
    n_genes=1000,
    beta=0.2,
)
# tree: dict mapping cell IDs to metadata (fate, parent, depth, etc.)
# expression: (n_cells, n_genes) array of observed counts

Parameters

generate_dataset() accepts the following parameters:

Parameter	Type	Default	Description
n_cells	int	8192	Number of cells to simulate
n_genes	int	1000	Number of genes to simulate
n_CIF	int	32	Number of Cell Identity Factors (latent dimensions)
sigma	float	0.2	Brownian motion noise std dev
beta	float	0.2	Fate signal strength
gene_effect_prob	float	0.3	Probability that a CIF affects a gene
scale_s	float	1.0	Transcription rate scaling factor
protocol	str	"UMI"	Sequencing protocol ("UMI" or "nonUMI")
skip_technical_noise	bool	False	If True, return true counts without technical noise
commit_depth	int	7	Depth at which fate commitment occurs

Contribution Guide

PRs are welcome!

License

MIT