scdecon.simulation¶

simulation ¶

Pseudobulk simulation: synthetic bulk with known ground-truth proportions.

Operates purely on in-memory AnnData objects (no file I/O). See :func:~scdecon.simulation.pseudobulk.split_reference to create disjoint signature / held-out partitions and avoid leakage.

ProportionPrior ¶

Bases: StrEnum

Prior distribution used to draw per-sample cell-type proportions.

SimulationConfig `dataclass` ¶

SimulationConfig(n_samples: int = 100, n_cells_per_sample: int = 500, cell_type_key: str = 'cell_type', proportion_prior: ProportionPrior = ProportionPrior.DIRICHLET, dirichlet_alpha: float = 1.0, random_state: int = 0, counts_layer: str | None = None)

Immutable configuration for pseudobulk simulation.

Attributes:

Name	Type	Description
`n_samples`	`int`	Number of pseudobulk samples to generate.
`n_cells_per_sample`	`int`	Number of single cells summed into each pseudobulk sample.
`cell_type_key`	`str`	Column in `adata.obs` holding the cell-type annotation.
`proportion_prior`	`ProportionPrior`	Prior for drawing target proportions (:class:`ProportionPrior`).
`dirichlet_alpha`	`float`	Symmetric Dirichlet concentration (only used for the Dirichlet prior). `1.0` is uniform over the simplex; `< 1` favours sparser mixtures.
`random_state`	`int`	Seed for the simulation's random generator (full reproducibility).
`counts_layer`	`str \| None`	Name of the `adata.layers` entry holding raw counts to sum. `None` uses `adata.X` (expected to be raw counts).

__post_init__ ¶

__post_init__() -> None

Validate parameters, failing loudly on nonsensical values.

BaseSimulator ¶

Bases: ABC

Abstract strategy for generating pseudobulk datasets.

simulate `abstractmethod` ¶

simulate(adata: AnnData, config: SimulationConfig) -> PseudobulkDataset

Generate a :class:PseudobulkDataset from single-cell data.

CellSumSimulator ¶

Bases: BaseSimulator

Pseudobulk by summing raw counts of cells drawn at known proportions.

PseudobulkDataset `dataclass` ¶

PseudobulkDataset(bulk: DataFrame, proportions: DataFrame)

A simulated pseudobulk dataset with its ground-truth proportions.

Attributes:

Name	Type	Description
`bulk`	`DataFrame`	Summed raw counts, genes (index) x samples (columns).
`proportions`	`DataFrame`	Realised ground-truth proportions, cell types (index) x samples (columns). Each column is non-negative and sums to 1. The orientation matches :func:`scdecon.deconvolution.deconvolve` so metrics can compare them directly.

simulate_pseudobulk ¶

simulate_pseudobulk(adata: AnnData, config: SimulationConfig, simulator: BaseSimulator | None = None) -> PseudobulkDataset

Generate a pseudobulk dataset using simulator.

Parameters:

Name	Type	Description	Default
`adata`	`AnnData`	Single-cell data (raw counts in `.X` or `config.counts_layer`). Should be the held-out partition (see :func:`split_reference`) to avoid leakage with the signature.	required
`config`	`SimulationConfig`	Simulation parameters.	required
`simulator`	`BaseSimulator \| None`	Strategy to use. Defaults to :class:`CellSumSimulator`.	`None`

Returns:

Type	Description
`PseudobulkDataset`	Summed-count bulk (genes × samples) and realised proportions (cell types × samples).

Raises:

Type	Description
`ValueError`	If `config.cell_type_key` is absent, or `config.counts_layer` is set but missing from `adata.layers`.

split_reference ¶

split_reference(adata: AnnData, cell_type_key: str = 'cell_type', *, signature_fraction: float = 0.5, random_state: int = 0) -> tuple[anndata.AnnData, anndata.AnnData]

Split cells into disjoint signature and held-out partitions.

The split is deterministic (seeded) and stratified by cell type: each cell type is shuffled and split independently, so both partitions retain the cell-type structure. Use the signature partition to build the signature and the held-out partition to simulate pseudobulk, preventing leakage.