iscc.data.scRNA

scRNA(protocol='10x', n_cells=100, count_model='nb', batch_label=None, n_reads=None, lib_size_sigma=None, dispersion=None, sigma_batch=None, mu_lib=None, sigma_lib=None, ambient_frac=None, doublet_rate=None, dropout_mid=None, dropout_shape=None, well_sigma=None, depth_batch_sigma=None, kappa=None, seed=42)

Bases: Assay

scRNA-seq assay: applies a protocol-keyed Batch to a sample's cell_exp.

The protocol preset sets typical magnitudes for every technical knob below; any of them can be overridden explicitly (None keeps the preset value). Legacy aliases are accepted: n_reads maps onto mu_lib and lib_size_sigma onto sigma_lib.

Parameters:

Name	Type	Description	Default
protocol	str	Hyper-parameter preset selecting which technical components dominate: "10x" (droplet / UMI / 3': prominent ambient RNA + doublets, moderate depth) or "smartseq3" (plate / 5' UMI + full-length: higher sensitivity, lower dropout and amplification noise, extra well-in-plate nesting). Common spellings are accepted ("10X", "tenx", "droplet"; "smart-seq3", "ss3", "plate"). Sets the defaults of every hyper-parameter below.	"10x"
n_cells	int	Number of cells to sample and assay, capped at the number available. Ignored when cell_subset is passed to run.	100
count_model	str	Final count-emission model: "nb" negative-binomial (independent per-gene overdispersion, what estimate_rna fits) or "dm" Dirichlet-multinomial (a fixed library total with gene-gene competition for reads).	"nb"
batch_label	str	Label recorded for this batch/realization; defaults to f"batch{seed}".	None
n_reads	float	Legacy alias for mu_lib (mean library size).	None
lib_size_sigma	float	Legacy alias for sigma_lib (per-cell library-size LogNormal sd).	None
dispersion	float	Negative-binomial overdispersion phi (var = mu + phi*mu^2); used only when count_model="nb" (phi <= 0 collapses to Poisson). Default None -> preset (10x: 0.30, smartseq3: 0.15).	None
sigma_batch	float	Per-gene batch-factor LogNormal sd; beta_gb ~ LogNormal(0, sigma_batch^2) is shared across cells and reshapes the per-gene composition (Splatter batch.facScale). Larger -> stronger batch effect. Default None -> preset (0.10).	None
mu_lib	float	Mean library size (UMIs / cell) = sequencing depth; per-cell library ell_c ~ LogNormal(log mu_lib_b, sigma_lib^2). Default None -> preset (10x: 4000, smartseq3: 8000).	None
sigma_lib	float	Per-cell library-size LogNormal sd (cell-to-cell depth variation). Default None -> preset (10x: 0.35, smartseq3: 0.45).	None
ambient_frac	float	Fraction of each cell's library drawn as ambient "soup" — Poisson counts from the pooled expression profile added to every cell. Default None -> preset (10x: 0.05, smartseq3: 0.005).	None
doublet_rate	float	Fraction of barcodes merged with a random partner cell (two cells combined into one). Default None -> preset (10x: 0.05, smartseq3: 0.01).	None
dropout_mid	float	Logistic dropout midpoint in expected-count space (Splatter-style zero-inflation keyed to mean count); 0 disables dropout. Default None -> preset (10x: 1.5, smartseq3: 0.0, i.e. disabled).	None
dropout_shape	float	Logistic dropout steepness (active only when dropout_mid > 0). Default None -> preset (1.0).	None
well_sigma	float	Per-cell "well" / plate-position LogNormal sd — an extra per-cell multiplier nesting a plate-position effect inside the batch (Smart-seq3); 0 disables. Default None -> preset (10x: 0.0, smartseq3: 0.15).	None
depth_batch_sigma	float	Per-batch depth-shift LogNormal sd, so different seeds (batches) differ in realized depth. Default None -> preset (0.05).	None
kappa	float	Dirichlet concentration for the "dm" count model only: large kappa -> proportions ~ composition (multinomial/Poisson-like), small kappa -> lumpy, over-dispersed proportions. Default None -> preset (50.0).	None
seed	int	RNG seed. Fixes both the technical signature of the batch (per-gene factor, depth, ambient soup) and the sampled-cell selection; two instances with the same hyper-parameters and different seeds are two batches (same biology, different technical noise).	42

Methods:

Name	Description
run	Assay single-cell RNA expression for the sampled cells.

run

run(cell_data, cell_subset=None, **kwargs)

Assay single-cell RNA expression for the sampled cells.

Draws per-cell UMI counts from each cell's expression state through one sequencing batch: per-gene capture factor, library size, negative-binomial overdispersion, ambient soup, dropout, and doublets.

Parameters:

Name	Type	Description	Default
cell_data	dict	Per-cell ground-truth tables from the sampling stage; uses the expression table cell_exp.	required
cell_subset	array-like of cell IDs	Fix the assayed cells so that several batches share the same biology. By default every sampled cell is used.	None

Returns:

Type	Description
scRNA	self, with the cell-by-gene UMI matrix in observed_counts and the QC/ground-truth table in obs. Call to_anndata or write to export.

Technology presets

Pass protocol= to select a platform preset, or override individual knobs. Two presets are built in; the rest are parameter starting points you can set explicitly, or fit from a real dataset with estimate_rna.

Platform	protocol	Profile
10x Chromium 3′ / 5′	"10x"	Droplet UMI: mu_lib ≈ 4000, dropout_mid = 1.5 (real dropout), ambient_frac = 0.05, doublet_rate = 0.05, no per-well term.
Smart-seq3	"smartseq3"	Plate UMI: deeper (mu_lib ≈ 8000), no dropout (dropout_mid = 0), low ambient (0.005), well_sigma = 0.15.
Smart-seq3xpress	"smartseq3" + lower mu_lib (~3000–5000)	Miniaturised Smart-seq3 — same plate profile, shallower per cell.
Smart-seq2	"smartseq3" + dispersion ≈ 0.4	Plate, no UMIs → read counts carry more amplification noise (raise dispersion); full-length gene-body coverage is not modelled.