Parameter Reference¶

This page is a one-stop cheatsheet mapping every internal parameter name in SCRIBE's generative model to its mathematical symbol, its role in the likelihood equations, the parameterization(s) it belongs to, and its biological interpretation. Prior hyperparameters and dataset-level extensions are covered at the end.

For guidance on choosing a model, see Model Selection. For the scribe.fit() keyword arguments that configure these parameters, see The scribe.fit() Interface.

Descriptive parameter names

When inspecting results, pass descriptive_names=True to get_map(), get_distributions(), or get_posterior_samples() to get self-documenting keys (e.g., dispersion instead of r, capture_prob instead of p_capture). See the Results Class for the full mapping.

Color legend¶

The equations below use a consistent color code so you can track each parameter across model variants.

Color	Parameter	Meaning
\(\color{#e07a5f}{r_g}\)	`r`	Gene-specific dispersion (burst rate)
\(\color{#3d85c6}{p}\)	`p`	Success probability
\(\color{#81b29a}{\mu_g}\)	`mu`	Biological mean expression
\(\color{#f2cc8f}{\phi}\)	`phi`	Odds \((1-p)/p\)
\(\color{#9b59b6}{\nu^{(c)}}\)	`p_capture`	Cell-specific capture probability
\(\color{#e74c3c}{\pi_g}\)	`gate`	Per-gene zero-inflation probability
\(\color{#f39c12}{\kappa_g}\)	`bnb_concentration`	BNB concentration (tail heaviness)

Core likelihood equations¶

Each model variant adds one structural layer. The equations below highlight exactly where each parameter sits.

NBDM (base Negative Binomial)¶

\[ u_g \;\sim\; \text{NB}\!\bigl(\color{#e07a5f}{r_g},\;\color{#3d85c6}{p}\bigr) \]

Gene-specific dispersion \(\color{#e07a5f}{r_g}\) controls per-gene overdispersion; a single success probability \(\color{#3d85c6}{p}\) is shared across genes. The joint distribution across genes factorizes into a Negative Binomial for totals and a Dirichlet-Multinomial for compositions (see Theory).

NBVCP (+ variable capture)¶

\[ \hat{p}^{(c)} = \frac{\color{#3d85c6}{p}\;\color{#9b59b6}{\nu^{(c)}}}{1 - \color{#3d85c6}{p}\,(1 - \color{#9b59b6}{\nu^{(c)}})}, \qquad u_g^{(c)} \;\sim\; \text{NB}\!\bigl(\color{#e07a5f}{r_g},\;\hat{p}^{(c)}\bigr) \]

The cell-specific capture probability \(\color{#9b59b6}{\nu^{(c)}}\) absorbs library-size variation. Genes are modelled independently given \(\color{#9b59b6}{\nu^{(c)}}\).

ZINB / ZINBVCP (+ zero inflation)¶

\[ u_g^{(c)} \;\sim\; \color{#e74c3c}{\pi_g}\;\delta_0 \;+\; (1 - \color{#e74c3c}{\pi_g})\;\text{NB}\!\bigl(\color{#e07a5f}{r_g},\;\hat{p}^{(c)}\bigr) \]

The per-gene gate \(\color{#e74c3c}{\pi_g}\) mixes a point mass at zero (technical dropout) with the NB (or NBVCP) count distribution. In ZINBVCP, \(\hat{p}^{(c)}\) includes the capture factor as above; in ZINB, \(\hat{p}^{(c)} = \color{#3d85c6}{p}\).

TwoState (Poisson-Beta compound)¶

\[ \color{#9b59b6}{p_g^{(c)}} \;\sim\; \text{Beta}\!\bigl(\alpha_g, \beta_g\bigr), \qquad u_g^{(c)} \;\sim\; \text{Poisson}\!\bigl(\hat r_g \, \color{#9b59b6}{p_g^{(c)}}\,\color{#9b59b6}{\nu^{(c)}}\bigr) \]

A non-bursty two-state promoter at steady state. The latent \(\color{#9b59b6}{p_g^{(c)}} \in [0, 1]\) is the memory-weighted ON fraction of the promoter for gene \(g\) in cell \(c\), drawn independently per \((g, c)\). The natural rate parameters are \(\alpha_g = k^+_g\) (ON rate), \(\beta_g = k^-_g\) (OFF rate), and \(\hat r_g\) (Poisson rate scale); their relationship to the sampled coordinates depends on the parameterization (see below). The capture factor \(\color{#9b59b6}{\nu^{(c)}}\) multiplies the rate (closure under binomial thinning).

The NB is recovered as a limiting case at large \(k^-\) — the two-state likelihood nests inside the NB family rather than competing with it. See Two-state promoter.

BNB overdispersion (any model + `overdispersion="bnb"`)¶

\[ \tilde{p} \;\sim\; \text{Beta}\!\bigl(\alpha_{gc},\;\color{#f39c12}{\kappa_g}\bigr), \qquad u_g^{(c)} \;\sim\; \text{NB}\!\bigl(\color{#e07a5f}{r_g},\;\tilde{p}\bigr) \]

where \(\alpha_{gc}\) is set to preserve the NB mean: \(\alpha_{gc} = \hat{p}^{(c)} \cdot \color{#f39c12}{\kappa_g}\,/\,(1 - \hat{p}^{(c)})\). As \(\color{#f39c12}{\kappa_g} \to \infty\) the Beta concentrates at \(\hat{p}^{(c)}\) and the BNB recovers the NB.

Mixture models (any model + `n_components=K`)¶

With \(K\) components, gene-specific parameters gain a component axis. Each cell's count is drawn from a mixture:

\[ u_g^{(c)} \;\sim\; \sum_{k=1}^{K} w_k \;\cdot\; f_k\!\bigl(u_g^{(c)} \;\mid\; \theta_g^{(k)}\bigr), \]

where \(w_k\) are the mixing weights and \(\theta_g^{(k)}\) includes the component-specific gene parameters. The mixture_params argument controls which parameters vary by component (default: "all" — every parameter including gate). Accepts semantic shorthands: "all", "biological" (core params only, excluding gate/capture), "mean", "prob", "gate", or an explicit list of internal parameter names.

For NB-family models, "biological" resolves to the core NB parameters (r, p/phi, mu). For TwoState-family models, "biological" resolves to the parameterization-specific extras (e.g. mu, burst_size, k_off for two_state_natural; mu, excess_fano, concentration for two_state_mean_fano). The factory automatically rewrites extra-parameter names to match the active parameterization, so mixture_params=["mu", "burst_size"] works for two_state_natural / two_state_ratio, and mixture_params=["mu", "excess_fano"] for two_state_mean_fano / two_state_moment_delta.

Parameterization mappings¶

The NB distribution can be parameterized in three equivalent ways. The parameterization argument to scribe.fit() controls which variables are sampled (free parameters the optimizer targets) and which are derived (deterministic functions of the sampled parameters).

Conversion table¶

Parameterization	`parameterization=`	Sampled	Derived	Conversion
Canonical	`"canonical"` (alias `"standard"`)	\(\color{#e07a5f}{r_g}\), \(\color{#3d85c6}{p}\)	---	---
Mean probs	`"mean_prob"` (alias `"linked"`)	\(\color{#81b29a}{\mu_g}\), \(\color{#3d85c6}{p}\)	\(\color{#e07a5f}{r_g}\)	\(r_g = \mu_g\,(1-p)\,/\,p\)
Mean odds	`"mean_odds"` (alias `"odds_ratio"`)	\(\color{#81b29a}{\mu_g}\), \(\color{#f2cc8f}{\phi}\)	\(\color{#3d85c6}{p}\), \(\color{#e07a5f}{r_g}\)	\(p = 1/(1+\phi)\), \(r_g = \mu_g \cdot \phi\)

All three produce the same NB distribution for any given \((\mu_g, r_g, p)\) triple --- they differ only in which quantities the optimizer directly targets.

Conversion diagram¶

graph LR
    Canon["Canonical<br/>r_g, p"] -->|"mu_g = r_g * p / (1-p)"| MeanP["Mean probs<br/>mu_g, p"]
    MeanP -->|"r_g = mu_g * (1-p) / p"| Canon
    MeanP -->|"phi = (1-p) / p"| MeanO["Mean odds<br/>mu_g, phi"]
    MeanO -->|"p = 1 / (1+phi)"| MeanP
    Canon -->|"phi = (1-p)/p<br/>mu_g = r_g / phi"| MeanO
    MeanO -->|"r_g = mu_g * phi"| Canon

How capture parameters change with parameterization¶

The VCP capture parameter name depends on the parameterization:

Parameterization	Capture parameter	Symbol	Domain
Canonical, Mean probs	`p_capture`	\(\nu^{(c)}\)	\((0, 1)\)
Mean odds	`phi_capture`	\(\phi^{(c)}_{\text{cap}}\)	\((0, \infty)\)
Biology-informed (any)	`eta_capture`	\(\eta_c = \log(M_c / L_c)\)	\((0, \infty)\)

Exact relationships:

\[ \nu^{(c)} = \exp(-\eta_c), \qquad \phi^{(c)}_{\text{cap}} = \exp(\eta_c) - 1. \]

When the biology-informed capture prior is enabled (via priors={"organism": "human"}), eta_capture is the sampled site and p_capture or phi_capture is registered as a deterministic.

TwoState parameterizations¶

The TwoState family (twostate / twostatevcp) has its own four parameterizations of the gene-level shape. All four sample mu (gene mean expression) plus two additional per-gene parameters; the likelihood is identical, only the sampled coordinates differ. All four are mean-preserving by construction.

Parameterization	`parameterization=`	Sampled extras	Derived (deterministic)
Natural	`"two_state_natural"` (alias `natural`)	`burst_size` (\(b_g\)), `k_off` (\(k^-_g\))	`k_on`, `alpha`, `beta`, `r_hat`
Ratio	`"two_state_ratio"` (alias `ratio`)	`burst_size`, `switching_ratio` (\(s_g = k^-_g/k^+_g\))	`k_on`, `k_off`, `alpha`, `beta`, `r_hat`
Mean-Fano	`"two_state_mean_fano"` (aliases `mean_fano`, `fano`)	`excess_fano` (\(F_g = \text{Var}/\mu - 1\)), `concentration` (\(\kappa_g = \alpha_g + \beta_g\))	`burst_size`, `k_on`, `k_off`, `alpha`, `beta`, `r_hat`
Moment-delta	`"two_state_moment_delta"` (aliases `moment_delta`, `delta`)	`excess_fano`, `inv_concentration` (\(\delta_g = 1/(\kappa_g + 1) \in (0,1)\))	`concentration`, `burst_size`, `k_on`, `k_off`, `alpha`, `beta`, `r_hat`

Forward maps:

two_state_natural: \(\alpha_g = \mu_g/b_g\), \(\beta_g = k^-_g\), \(\hat r_g = \mu_g + b_g\, k^-_g\).
two_state_ratio: \(\alpha_g = \mu_g/b_g\), \(\beta_g = s_g\,\mu_g/b_g\), \(\hat r_g = \mu_g\,(1 + s_g)\).
two_state_mean_fano: \(\text{denom} = \mu_g + F_g(\kappa_g + 1)\); \(\alpha_g = \kappa_g \mu_g/\text{denom}\), \(\beta_g = \kappa_g F_g(\kappa_g + 1)/\text{denom}\), \(\hat r_g = \text{denom}\).
two_state_moment_delta: \(\text{denom} = \mu_g \delta_g + F_g\); \(\alpha_g = \mu_g(1-\delta_g)/\text{denom}\), \(\beta_g = F_g(1-\delta_g)/(\delta_g\,\text{denom})\), \(\hat r_g = \text{denom}/\delta_g\).

The capture parameter for twostatevcp is always p_capture (in \((0, 1)\)) regardless of which TwoState parameterization is chosen. Biology-informed capture priors are supported (priors={"capture_efficiency": (log_M0, sigma_M)}); the closure under binomial thinning makes the prior math likelihood-agnostic.

Master parameter table¶

Parameter name	Symbol	Role	Domain	Models	Parameterization
`r`	\(\color{#e07a5f}{r_g}\)	Gene-specific NB dispersion (burst rate). Higher \(r_g\) means less overdispersion	\(\mathbb{R}^+\)	All	Sampled in canonical; derived in mean_prob and mean_odds
`p`	\(\color{#3d85c6}{p}\)	NB success probability. Shared across genes in NBDM; gene-specific \(p_g\) when hierarchical	\((0, 1)\)	All	Sampled in canonical and mean_prob; derived in mean_odds
`mu`	\(\color{#81b29a}{\mu_g}\)	Biological mean expression per gene (before capture)	\(\mathbb{R}^+\)	All	Sampled in mean_prob and mean_odds; not directly in canonical
`phi`	\(\color{#f2cc8f}{\phi}\)	Odds of success probability: \(\phi = (1-p)/p\)	\(\mathbb{R}^+\)	All	Sampled only in mean_odds
`gate`	\(\color{#e74c3c}{\pi_g}\)	Per-gene zero-inflation probability (technical dropout)	\((0, 1)\)	ZINB, ZINBVCP	All parameterizations
`p_capture`	\(\color{#9b59b6}{\nu^{(c)}}\)	Cell-specific capture probability (library-size factor)	\((0, 1)\)	NBVCP, ZINBVCP, TwoStateVCP	Canonical, mean_prob; always for TwoState
`phi_capture`	\(\phi^{(c)}_{\text{cap}}\)	Cell-specific capture odds	\(\mathbb{R}^+\)	NBVCP, ZINBVCP	Mean odds only
`eta_capture`	\(\eta_c\)	Latent log-ratio \(\log(M_c / L_c)\) under biology-informed prior	\(\mathbb{R}^+\)	NBVCP, ZINBVCP	Any (when biology-informed prior is active)
`bnb_concentration`	\(\color{#f39c12}{\kappa_g}\)	Beta concentration controlling BNB tail heaviness. \(\kappa_g \to \infty\) recovers NB	\((2, \infty)\)	Any + `overdispersion="bnb"`	All parameterizations
`mixing_weights`	\(w_k\)	Dirichlet-distributed component probabilities	Simplex	Any + `n_components >= 2`	All parameterizations
`z`	\(\underline{z}^{(c)}\)	Per-cell latent embedding (VAE only)	\(\mathbb{R}^d\)	Any + `inference_method="vae"`	All parameterizations
`burst_size`	\(b_g\)	TwoState NB-limit mean burst size	\(\mathbb{R}^+\)	TwoState	Sampled in natural, ratio; derived in mean_fano, moment_delta
`k_off`	\(k^-_g\)	TwoState OFF rate (non-dim by mRNA decay). Large \(k^-\) approaches the NB limit	\(\mathbb{R}^+\)	TwoState	Sampled in natural; derived otherwise
`switching_ratio`	\(s_g = k^-_g / k^+_g\)	TwoState dimensionless regime ratio	\(\mathbb{R}^+\)	TwoState	Sampled in ratio
`excess_fano`	\(F_g = \text{Var}/\mu - 1\)	TwoState excess Fano factor — directly bounds PPC width per gene	\(\mathbb{R}^+\)	TwoState	Sampled in mean_fano, moment_delta
`concentration`	\(\kappa_g = \alpha + \beta\)	TwoState Beta concentration. Large \(\kappa\) approaches the NB limit	\(\mathbb{R}^+\)	TwoState	Sampled in mean_fano; derived in moment_delta
`inv_concentration`	\(\delta_g = 1/(\kappa_g+1)\)	TwoState bounded shape coordinate. \(\delta \to 0\) is the NB limit	\((0, 1)\)	TwoState	Sampled in moment_delta

Derived quantities (not directly sampled)¶

Quantity	Formula	Appears in
\(\hat{p}^{(c)}\)	\(\dfrac{p \cdot \nu^{(c)}}{1 - p\,(1 - \nu^{(c)})}\)	NBVCP / ZINBVCP effective success probability
\(\omega_g\)	\(\dfrac{r_g + 1}{\kappa_g - 2}\)	BNB excess dispersion fraction (prior applied to this)
\(\alpha_{gc}\)	\(\dfrac{\hat{p}^{(c)} \cdot \kappa_g}{1 - \hat{p}^{(c)}}\)	BNB Beta shape (mean-preserving)

Constrained vs. unconstrained mode¶

By default, parameters are sampled in their constrained domain (e.g., \(p \in (0,1)\) via a Beta distribution). With unconstrained=True, all parameters are lifted to \(\mathbb{R}\) via standard transforms and sampled as Normals:

Parameter	Transform	Unconstrained name
\(p \in (0,1)\)	logit	`p_unconstrained`
\(\mu \in \mathbb{R}^+\)	log	`mu_unconstrained`
\(\phi \in \mathbb{R}^+\)	log	`phi_unconstrained`
\(r \in \mathbb{R}^+\)	log	`r_unconstrained`
\(\pi_g \in (0,1)\)	logit	`gate_unconstrained`

Unconstrained mode is required for hierarchical priors and BNB overdispersion, and is the natural setting for normalizing flow guides.

The TwoState family follows the same pattern. Under unconstrained=False (the default), positive parameters use LogNormalSpec and the bounded inv_concentration ∈ (0, 1) uses BetaSpec. Under unconstrained=True, positive parameters use PositiveNormalSpec / SoftplusNormalSpec (Normal + softplus/exp) and inv_concentration uses SigmoidNormalSpec (Normal + sigmoid).

TwoState Parameter	`unconstrained=True`	`unconstrained=False`
`mu`, `burst_size`, `k_off`, `switching_ratio`, `excess_fano`, `concentration`	`PositiveNormalSpec` (Normal + softplus/exp)	`LogNormalSpec`
`inv_concentration` ∈ (0, 1)	`SigmoidNormalSpec` (Normal + sigmoid)	`BetaSpec`

Hierarchical prior hyperparameters¶

Hierarchical priors operate on the unconstrained transforms of gene-level parameters (logit for probabilities, log for positive quantities). All three prior families share the same template:

\[ \theta_g = \mu_{\text{pop}} + \sigma_g \cdot z_g, \qquad z_g \sim \mathcal{N}(0, 1), \]

where \(\sigma_g\) is the family-specific per-element scale.

Gaussian hierarchy¶

A single shared scale for all genes:

\[ \sigma_g = \sigma \quad \forall\, g, \qquad \sigma \sim \text{Softplus}(\mathcal{N}(\mu_\sigma, s_\sigma)). \]

No user-configurable hyperparameters beyond the choice "gaussian" itself.

Regularized Horseshoe¶

Per-gene local scales plus a global scale and regularization slab:

\[ \theta_g = \mu_{\text{pop}} + \color{#3d85c6}{\tau} \cdot \tilde{\lambda}_g \cdot z_g, \qquad \tilde{\lambda}_g = \frac{\color{#81b29a}{c}\,\lambda_g}{\sqrt{\color{#81b29a}{c}^2 + \color{#3d85c6}{\tau}^2 \lambda_g^2}} \]

`scribe.fit()` parameter	Symbol	Default	Role
`horseshoe_tau0`	\(\color{#3d85c6}{\tau_0}\)	`1.0`	Scale of Half-Cauchy prior on global \(\tau\). Controls overall sparsity level
`horseshoe_slab_df`	\(\nu\)	`4`	Degrees of freedom for Inv-Gamma slab on \(c^2\). Lower = heavier tails
`horseshoe_slab_scale`	\(s\)	`2.0`	Scale of the slab. Bounds the maximum effective local scale

Normal-Exponential-Gamma (NEG)¶

Gamma-Gamma hierarchy with a finite peak at zero (SVI-friendly):

\[ \zeta_g \sim \text{Gamma}(\color{#f2cc8f}{a},\; \color{#e07a5f}{\tau}), \qquad \psi_g \mid \zeta_g \sim \text{Gamma}(\color{#81b29a}{u},\; \zeta_g), \qquad \theta_g \sim \mathcal{N}(\mu_{\text{pop}},\; \sqrt{\psi_g}). \]

`scribe.fit()` parameter	Symbol	Default	Role
`neg_u`	\(\color{#81b29a}{u}\)	`1.0`	Inner Gamma shape. \(u=1\) gives NEG (finite peak); \(u=0.5\) recovers horseshoe (infinite spike)
`neg_a`	\(\color{#f2cc8f}{a}\)	`1.0`	Outer Gamma shape. Controls concentration near zero
`neg_tau`	\(\color{#e07a5f}{\tau}\)	`1.0`	Global rate for the outer Gamma. Higher = stronger global shrinkage

Mean anchoring prior¶

Anchors the gene mean \(\mu_g\) to a data-implied value to resolve the multiplicative degeneracy between expression and capture:

\[ \hat{\mu}_g = \frac{\bar{u}_g + \epsilon}{\bar{\nu}}, \qquad \log(\mu_g) \sim \mathcal{N}(\log(\hat{\mu}_g),\; \sigma_\mu^2). \]

`scribe.fit()` parameter	Symbol	Default	Role
`expression_anchor`	---	`False`	Enable mean anchoring
`expression_anchor_sigma`	\(\sigma_\mu\)	`0.3`	Width of the anchor. Smaller = tighter regularization toward data mean

See Theory: Anchoring Priors.

Biology-informed capture prior¶

Anchors the capture probability to the ratio of library size to total mRNA content:

\[ \eta_c \sim \mathcal{N}^{+}\!\bigl(\log M_0 - \log L_c,\; \sigma_M^2\bigr), \qquad \nu_c = \exp(-\eta_c). \]

`scribe.fit()` parameter	Symbol	Default	Role
`priors={"organism": "human"}`	\(M_0\)	---	Sets organism-specific expected total mRNA (e.g., 200,000 for human/mouse)
`priors={"capture_efficiency": (log_M0, sigma_M)}`	\(\log M_0, \sigma_M\)	---	Direct specification of capture prior parameters

See Theory: Anchoring Priors.

Which prior applies where¶

Hierarchical priors are selected via the *_prior arguments. Each argument targets a specific parameter at a specific level:

`scribe.fit()` argument	Target parameter	Level	Accepted values	Requires
`prob_prior`	\(p_g\) (gene-specific)	Gene	`"gaussian"`, `"horseshoe"`, `"neg"`	---
`expression_prior`	\(\mu_g^{(k)}\) (across components)	Gene x component	`"gaussian"`, `"horseshoe"`, `"neg"`	`n_components >= 2`, `unconstrained=True`
`zero_inflation_prior`	\(\pi_g\)	Gene	`"gaussian"`, `"horseshoe"`, `"neg"`	ZI model
`overdispersion_prior`	\(\kappa_g\) (via \(\omega_g\))	Gene	`"horseshoe"`, `"neg"`	`overdispersion="bnb"`
`expression_dataset_prior`	\(\mu_g^{(d)}\)	Gene x dataset	`"gaussian"`, `"horseshoe"`, `"neg"`	`dataset_key`
`prob_dataset_prior`	\(p^{(d)}\) or \(p_g^{(d)}\)	Dataset (or gene x dataset)	`"gaussian"`, `"horseshoe"`, `"neg"`	`dataset_key`
`zero_inflation_dataset_prior`	\(\pi_g^{(d)}\)	Gene x dataset	`"gaussian"`, `"horseshoe"`, `"neg"`	`dataset_key`, ZI model
`overdispersion_dataset_prior`	\(\kappa_g^{(d)}\)	Gene x dataset	`"gaussian"`, `"horseshoe"`, `"neg"`	`overdispersion="bnb"`, `dataset_key`
`regime_dataset_prior`	TwoState regime coord \(\delta_g^{(d)}\) / \(k^{-(d)}_g\) / \(\kappa_g^{(d)}\) / \(s_g^{(d)}\)	Gene x dataset	`"gaussian"`, `"horseshoe"`, `"neg"`	`dataset_key`, TwoState model

In a crossed multi-factor design (dataset_key=[...] or hierarchy=[...]), each *_dataset_prior also accepts a dict {factor_name: family} to set the prior family per factor; a bare string broadcasts to all factors.

Dataset-level parameters¶

When fitting multiple datasets jointly (dataset_key="batch"), single-dataset parameters gain a dataset axis. The naming convention follows:

Single-dataset	Multi-dataset	Hierarchy argument
\(\mu_g\)	\(\mu_g^{(d)}\)	`expression_dataset_prior`
\(p\) or \(p_g\)	\(p^{(d)}\) or \(p_g^{(d)}\)	`prob_dataset_prior` + `prob_dataset_mode`
\(\pi_g\)	\(\pi_g^{(d)}\)	`zero_inflation_dataset_prior`
\(\kappa_g\)	\(\kappa_g^{(d)}\)	`overdispersion_dataset_prior`
TwoState regime coord (\(\delta_g\) / \(k^-_g\) / \(\kappa_g\) / \(s_g\))	per-dataset	`regime_dataset_prior`
\(\log M_0\)	\(\log M_0^{(d)}\)	`capture_scaling_prior` (captures dataset-level total mRNA scaling)

The leaf index \(d\) runs over the present combinations of grouping factors, so a list dataset_key=["treatment", "sample"] still produces a single dataset axis (one leaf per realised combination).

Crossed multi-factor parameters¶

With more than one grouping factor, the expression target gains an additive decomposition rather than one free value per leaf:

\[ \log \mu_g^{(\ell)} = \log \mu_g^{\mathrm{pop}} + \sum_f \alpha_g^{(f)}\!\big[\mathrm{level}_f(\ell)\big], \]

introducing one effect parameter per factor level (gathered onto the leaf):

Parameter	Effect type	Set by
\(\alpha_g^{(f)}\) for a fixed factor	fixed-scale Gaussian, no learned shrinkage (the contrast of interest)	`GroupLevel(effect_type="fixed")` (+ optional `fixed_scale`)
\(\alpha_g^{(f)}\) for a random factor	zero-mean NCP with a learned scale (`"gaussian"`/`"horseshoe"`/`"neg"`)	`GroupLevel(effect_type="random")` (default)

The technical parameters (\(p\), gate, regime) keep the single-axis per-leaf hierarchy above. The fitted effects are inspectable via results.get_factor_effect(factor); see Theory: crossed and nested designs.

TwoState multi-dataset hierarchy¶

For the TwoState family, the mean \(\mu_g\) and the regime coordinate (the NB↔bursty axis — k_off / switching_ratio / concentration / inv_concentration, depending on the parameterization) are the natural candidates for a cross-dataset hierarchy. Linking both encodes the prior that two conditions share biology and bursting regime, so genuine differences stand out:

expression_dataset_prior links \(\mu_g^{(d)}\) across datasets (shared expression).
regime_dataset_prior links the regime coordinate across datasets (shared bursting regime). It targets the active parameterization's regime coordinate by default; override with regime_dataset_target.
overdispersion_dataset_independent (default True) leaves the overdispersion coordinate (burst_size / excess_fano) free per dataset — it is well identified by each dataset's variance and, because the reparameterization is mean-preserving, cannot contaminate the shared \(\mu_g\). Set False to share one gene-level value across datasets.

The prob_dataset_mode argument controls the granularity of the dataset-specific \(p\):

Mode	Meaning
`"scalar"`	One \(p^{(d)}\) per dataset, shared across genes
`"gene_specific"` (default)	Independent \(p_g^{(d)}\) per gene per dataset
`"two_level"`	Each dataset has its own \((\mu_p^{(d)}, \sigma_p^{(d)})\), from which gene-level \(p_g^{(d)}\) are drawn

See Theory: Hierarchical Priors --- Multi-dataset.

Quick-look matrix¶

Which parameters appear in which model configuration:

NB-family models¶

Parameter	NBDM	NBVCP	ZINB	ZINBVCP	+ BNB	+ Mixture
`r` / `r_g`	yes	yes	yes	yes	yes	per-component
`p`	yes	yes	yes	yes	yes	yes
`mu`	MP/MO	MP/MO	MP/MO	MP/MO	MP/MO	per-component
`phi`	MO	MO	MO	MO	MO	MO
`gate`	---	---	yes	yes	yes	per-component
`p_capture` / `phi_capture`	---	yes	---	yes	yes	yes
`eta_capture`	---	opt	---	opt	opt	opt
`bnb_concentration`	---	---	---	---	yes	per-component
`mixing_weights`	---	---	---	---	---	yes
`z` (VAE latent)	VAE	VAE	VAE	VAE	VAE	VAE

TwoState-family models¶

Parameter	TwoState	TwoStateVCP	+ Mixture
`mu`	yes	yes	per-component
`burst_size` (natural, ratio)	yes	yes	per-component
`k_off` (natural only)	yes	yes	per-component
`switching_ratio` (ratio only)	yes	yes	per-component
`excess_fano` (mean_fano, moment_delta)	yes	yes	per-component
`concentration` (mean_fano only)	yes	yes	per-component
`inv_concentration` (moment_delta only)	yes	yes	per-component
`p_capture`	---	yes	yes
`mixing_weights`	---	---	yes

Legend: "yes" = always present; "MP/MO" = only with mean_prob or mean_odds parameterization; "MO" = only with mean_odds; "opt" = optional (biology-informed prior); "VAE" = only with inference_method="vae"; "per-component" = one per mixture component.

For the full derivations behind these equations, see the Theory section. For practical guidance on configuring these parameters via scribe.fit(), see The scribe.fit() Interface.