diffsvg.tl.fit_model#

diffsvg.tl.fit_model(adata, model_setup, n_workers=1, progressbar=True, inplace=True, use_binned=True, stats_key='dsvg_stats', preds_key='dsvg_preds', curves_key='dsvg_curves', null_quantile=0.9, sample_kwargs=None, test='parallel', tau=None, predictive_seed=None, inference='auto', coefs_key='dsvg_coefs', two_stage=False, **pymc_kwargs)#

Fit every per-gene model from setup_model, in parallel, and summarize the result.

For each gene: (re-)builds its own private model and obtains the posterior (see inference), then samples the posterior predictive on the fixed anchor grid under both levels of condition, and tests the two curves against each other (see test).

Parameters:
adata

The same AnnData object model_setup.binned was built from; only used as the write target when inplace is True.

model_setup

Output of setup_model.

n_workers default: 1

Number of worker processes (joblib, loky backend). Each gene’s model lives entirely within one worker for its whole lifetime - genes are never split across workers or re-synced, so there is nothing to race. n_workers=1 runs sequentially in-process (no extra pickling at all).

use_binned default: True

Fit on the per-bin averages from diffsvg.pp.bin_obs (default), or on the raw per-cell values when False. Raw keeps every observation instead of collapsing each window to its mean, at the cost of a far larger design matrix - with spatial data that is mostly zero counts, which is what the binning is there to avoid, this is typically much slower per gene. Knots, degree and the condition encoding are identical either way, so the two are directly comparable. Bins built with window_radius=None are weighted by their cell counts, which makes the binned fit carry the same information as the per-cell one at the cost of the binned fit.

progressbar default: True

Show a tqdm progress bar over completed genes. Per-worker MCMC progress bars are always disabled (they would interleave garbage across processes); pass e.g. sample_kwargs={"progressbar": True} to override that only when n_workers=1.

inplace default: True

If True (default), write results to adata.varm/adata.uns (aligned to adata.var_names, with genes not in model_setup left as NaN) and return None. If False, leave adata untouched and return (stats_df, preds_df, curve_dfs); curve_dfs then also holds the coefficient tables under "beta" and "beta_1".

stats_key default: 'dsvg_stats'

adata.varm key for the per-gene summary statistics (n_genes x n; see diffsvg.pl.plot_volcano/diffsvg.pl.plot_pvalue_histogram). Its columns depend on test; which test ran (and its tau) is recorded in adata.uns[f"{stats_key}_params"].

preds_key default: 'dsvg_preds'

adata.varm key for the per-gene, per-bin predicted condition==1 minus condition==0 difference curve (n_genes x (n_bins + 1)).

curves_key default: 'dsvg_curves'

Prefix for six adata.varm entries (n_genes x (n_bins + 1) each), one per {"cond0", "cond1"} x {"mean", "ci_low", "ci_high"}: the per-condition predicted curves with a credible band, consumed by diffsvg.pl.plot_prediction_curve. The condition labels are also written to adata.uns[f"{curves_key}_condition_categories"].

null_quantile default: 0.9

No longer used by fit_model (kept for backwards compatibility). The panel-based empirical/Gamma nulls it configured were circular; test="wald" now has a per-gene p-value.

sample_kwargs default: None

Extra keyword arguments merged into the pymc.sample call (applied to every gene). Any extra keyword arguments to fit_model itself are forwarded the same way, so fit_model(..., chains=2) also works. With inference="exact" only draws, random_seed, n_grid and n_hyper apply.

test default: 'parallel'

Which test to run between the two condition curves:

  • "parallel" (default): whether the curves are parallel, i.e. differ only in level, via parallel_curves_test on the posterior of the interaction coefficients. The p-value is per gene, so it does not depend on the panel and works for a single gene. Columns shape_diff (how far from parallel), slope_diff (the linear trend of f1 - f0 over the anchor range, with a 94% credible interval slope_diff_ci_low/slope_diff_ci_high), parallel_stat, parallel_df, parallel_pval and parallel_pval_adj (Benjamini-Hochberg).

  • "wald": whether the curves are equal at all (level or shape), a tradeSeq-style functional Wald test on the posterior of the difference curve, chi-square with n_bsplines degrees of freedom (columns wald_stat, wald_pval, wald_df, wald_pval_adj and T, the mean squared difference). It has no tau, so with many cells nearly every gene with any difference becomes significant; rank by wald_stat rather than thresholding.

  • "level": whether the curves differ in level, i.e. in the mean of f1 - f0 over the anchor range, beyond tau (H0: |level| <= tau; noncentral chi-square with 1 degree of freedom). The complement of "parallel", which ignores the level. Columns level_diff (with a 94% credible interval), level_stat, level_pval and level_pval_adj.

  • "slope": whether the gap between the curves changes linearly along the anchor, i.e. whether one gradient is steeper than the other: the least-squares slope of f1 - f0 over [0, 1], H0: |slope| <= tau, 1 degree of freedom. With few replicates it has far more power than "parallel" (n_bsplines - 1 df) for gradients that steepen or flatten, and it misses non-monotone changes, which "parallel" covers. Columns slope_diff (with a 94% credible interval), slope_stat, slope_pval and slope_pval_adj.

With data binned with sample (several slides per condition) the model has a random level and a random curve per slide, so the covariance of the interaction coefficients holds the variation between slides, and the p-value uses an F reference with n_slides - 2 denominator degrees of freedom for every test (column *_df_denominator). The fitted curves are the population-level ones. Fit on bins (NUTS is fine) or on cells (use_binned=False).

Every test is computed over the anchor range where the cells are: the central 96% of them, cut to where both conditions have cells (anchor_support in the stored test parameters). Outside it the curves are extrapolated from the spline and the prior, and averaging over that part would make the test overconfident, most of all for cell types that occupy only part of the anchor range. Slopes and shape differences stay in units of the full [0, 1] range.

Both tests also write integral (the area between the curves), the categorical_beta summary and the sampler diagnostics. Binned fits with overlapping windows (diffsvg.pp.bin_obs’s default window_radius) treat neighbouring bins as independent although they share cells, which makes the model over-confident and the "parallel" p-values too small (a warning says so); contiguous bins (bin_obs(..., window_radius=None)) and fits on the cells (use_binned=False) do not have that problem.

tau default: None

For the "parallel", "level" and "slope" tests: the smallest difference that counts (shape_diff, level_diff or slope_diff). The p-value tests |difference| <= tau, so smaller differences do not become significant however many cells there are. Defaults to 0.1 for pooled data and to 0 for data binned with sample, where the variation between slides already calibrates the test and a positive tau only costs power.

two_stage default: False

With data binned with sample: compute the test from one curve per slide, comparing the slides’ summaries between the conditions (level or slope: t-test; shape: Hotelling’s T^2; n_slides - 2 denominator degrees of freedom). Every slide counts once and nothing is assumed about how slides differ, so the error rate holds when the joint model’s random curve is misspecified. The fitted curves and bands still come from the joint model. False (default) uses the joint model’s posterior for the test as well, which has more power with few slides. Use True when the cells cover only part of the anchor range (e.g. a cell type confined to some cortical layers); fit_model warns then.

predictive_seed default: None

Deprecated since version 0.1.0: It has no effect: the curves are the posterior of the mean function, computed without new random draws.

Deprecated, has no effect. The curves, their bands, integral and the Wald test are now computed from the posterior draws of the mean function (no observation noise), so they need no extra random draws.

inference default: 'auto'

How each gene’s posterior is obtained:

  • "nuts": MCMC with pymc.sample (needs the pymc extra), configured by sample_kwargs. Reports n_divergent, rhat_max and ess_bulk_min.

  • "exact": the exact posterior (see diffsvg.tl._exact): the coefficients are conjugate given the noise scale, which is integrated out numerically, as are the two slide scales. No Monte Carlo error and no sampler; needs the normal likelihood and normal coefficient priors. Reports exact_edge_mass.

  • "auto" (default): "exact" where the model allows it, "nuts" otherwise.

coefs_key default: 'dsvg_coefs'

Prefix for two adata.varm tables (n_genes x n_bsplines) with the posterior means of the spline coefficients, consumed by diffsvg.tl.cluster_curves: f"{coefs_key}_beta" (the main spline term; with the 0/1 condition coding this is the curve of condition 0, not a pooled one) and f"{coefs_key}_beta_1" (the interaction, how the curve of condition 1 differs from it).

Returns:

None or tuple[pandas.DataFrame, pandas.DataFrame, dict[str, pandas.DataFrame]]