structboost.sim_scrnaseq_data

structboost.sim_scrnaseq_data(*, n=1000, n_genes=50, stageno=10, stagep=None, stagen=None, stageoverlap=None, hierarchy=True, markers_per_level=None, imbalanced=False, base_mean=2.0, gene_mean_shape=4.0, effect_size=10.0, effect_size_sd=0.0, dispersion=0.2, lib_size_sd=0.0, n_batches=1, batch_effect_sd=0.0, ambient_frac=0.0, dropout_mid=None, dropout_shape=-1.0, seed=1)[source]

Simulate negative-binomial scRNA-seq counts with block/stage structure.

Cells are assigned to stageno contiguous stages in row order. Each stage over-expresses a sliding window of stagep marker genes by a factor of effect_size; consecutive windows share stageoverlap genes. Counts are drawn from a gamma-Poisson (negative binomial) mixture, so Var[c] = mu + dispersion * mu**2.

All technical effects are neutral by default, so the base call produces clean, well-separated block structure.

Parameters:

  • n (int) – Number of cells.

  • n_genes (int) – Number of genes.

  • stageno (int) – Number of stages (cell populations).

  • stagep (int | None) – Marker genes per stage. Defaults to n_genes // stageno.

  • stagen (int | None) – Cells per stage. Defaults to n // stageno. Must be None when imbalanced=True.

  • stageoverlap (int | None) – Marker genes shared between consecutive stages. Must be < stagep.

  • imbalanced (bool) – If True, draw stage sizes from a symmetric Dirichlet instead of using equal sizes.

  • base_mean (float) – Expected baseline expression mean across genes. Gene means are drawn as Gamma(gene_mean_shape, base_mean / gene_mean_shape).

  • gene_mean_shape (float) – Shape of the gene-mean gamma; the coefficient of variation of gene means is 1 / sqrt(gene_mean_shape).

  • effect_size (float) – Marker-to-background mean ratio. This is the signal-strength knob: lower values make stages harder to separate.

  • effect_size_sd (float) – Log-normal spread of the per-gene fold change around effect_size. 0.0 gives every marker gene exactly effect_size.

  • dispersion (float) – Negative-binomial overdispersion; the biological coefficient of variation is sqrt(dispersion). This is the noise knob, orthogonal to effect_size. 0.0 gives exact Poisson counts.

  • lib_size_sd (float) – Log-normal standard deviation of the per-cell size factor. 0.0 gives uniform sequencing depth.

  • n_batches (int) – Number of technical batches. Cells are assigned round-robin, so batch is orthogonal to stage.

  • batch_effect_sd (float) – Log-normal standard deviation of the per-gene, per-batch multiplicative shift. The shifts are normalized to unit geometric mean per gene, so enabling batch effects does not move marginal gene means.

  • ambient_frac (float) – Fraction of each cell’s counts replaced by draws from a pooled ambient profile. Library size is preserved exactly.

  • dropout_mid (float | None) – Midpoint of the mean-dependent logistic dropout curve, on the log-mean scale. None disables dropout entirely.

  • dropout_shape (float) – Steepness of the dropout curve. Negative values (the default) mean high-expression genes drop out less.

  • seed (int) – Random seed. Independent sub-streams are spawned per component, so changing one parameter does not perturb the others’ draws.

  • hierarchy (tuple[int, ...] | bool | None)

  • markers_per_level (tuple[int, ...] | None)

Returns:

SimulationResult – Counts plus the ground truth (stage labels, marker mask, gene means).

Raises:

ValueError – If any parameter is out of range or the stage layout does not fit in n_genes.

Return type:

SimulationResult

References

The count model reimplemented here — gamma-distributed gene means, gamma-Poisson counts, log-normal library sizes, multiplicative batch effects and mean-dependent logistic dropout — follows Splatter: Zappia, L., Phipson, B. & Oshlack, A. (2017). Splatter: simulation of single-cell RNA sequencing data. Genome Biology 18, 174.

Examples

>>> from structboost import sim_scrnaseq_data
>>> res = sim_scrnaseq_data(n=100, n_genes=20, stageno=4, seed=0)
>>> res.counts.shape
(100, 20)
>>> res.marker_mask.shape
(4, 20)