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 fixedanchorgrid under both levels ofcondition, and tests the two curves against each other (seetest).- Parameters:
- adata
The same
AnnDataobjectmodel_setup.binnedwas built from; only used as the write target wheninplaceisTrue.- model_setup
Output of
setup_model.- n_workers default:
1 Number of worker processes (
joblib,lokybackend). 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=1runs 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 whenFalse. 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 withwindow_radius=Noneare 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
tqdmprogress 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 whenn_workers=1.- inplace default:
True If
True(default), write results toadata.varm/adata.uns(aligned toadata.var_names, with genes not inmodel_setupleft asNaN) and returnNone. IfFalse, leaveadatauntouched and return(stats_df, preds_df, curve_dfs);curve_dfsthen also holds the coefficient tables under"beta"and"beta_1".- stats_key default:
'dsvg_stats' adata.varmkey for the per-gene summary statistics (n_genes x n; seediffsvg.pl.plot_volcano/diffsvg.pl.plot_pvalue_histogram). Its columns depend ontest; which test ran (and itstau) is recorded inadata.uns[f"{stats_key}_params"].- preds_key default:
'dsvg_preds' adata.varmkey for the per-gene, per-bin predictedcondition==1minuscondition==0difference curve (n_genes x (n_bins + 1)).- curves_key default:
'dsvg_curves' Prefix for six
adata.varmentries (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 bydiffsvg.pl.plot_prediction_curve. The condition labels are also written toadata.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.samplecall (applied to every gene). Any extra keyword arguments tofit_modelitself are forwarded the same way, sofit_model(..., chains=2)also works. Withinference="exact"onlydraws,random_seed,n_gridandn_hyperapply.- 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, viaparallel_curves_teston 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. Columnsshape_diff(how far from parallel),slope_diff(the linear trend off1 - f0over the anchor range, with a 94% credible intervalslope_diff_ci_low/slope_diff_ci_high),parallel_stat,parallel_df,parallel_pvalandparallel_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 withn_bsplinesdegrees of freedom (columnswald_stat,wald_pval,wald_df,wald_pval_adjandT, the mean squared difference). It has notau, so with many cells nearly every gene with any difference becomes significant; rank bywald_statrather than thresholding."level": whether the curves differ in level, i.e. in the mean off1 - f0over the anchor range, beyondtau(H0: |level| <= tau; noncentral chi-square with 1 degree of freedom). The complement of"parallel", which ignores the level. Columnslevel_diff(with a 94% credible interval),level_stat,level_pvalandlevel_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 off1 - f0over[0, 1],H0: |slope| <= tau, 1 degree of freedom. With few replicates it has far more power than"parallel"(n_bsplines - 1df) for gradients that steepen or flatten, and it misses non-monotone changes, which"parallel"covers. Columnsslope_diff(with a 94% credible interval),slope_stat,slope_pvalandslope_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 withn_slides - 2denominator 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_supportin 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), thecategorical_betasummary and the sampler diagnostics. Binned fits with overlapping windows (diffsvg.pp.bin_obs’s defaultwindow_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_difforslope_diff). The p-value tests|difference| <= tau, so smaller differences do not become significant however many cells there are. Defaults to0.1for pooled data and to0for data binned withsample, where the variation between slides already calibrates the test and a positivetauonly 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 - 2denominator 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. UseTruewhen the cells cover only part of the anchor range (e.g. a cell type confined to some cortical layers);fit_modelwarns 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,
integraland 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 withpymc.sample(needs thepymcextra), configured bysample_kwargs. Reportsn_divergent,rhat_maxandess_bulk_min."exact": the exact posterior (seediffsvg.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. Reportsexact_edge_mass."auto"(default):"exact"where the model allows it,"nuts"otherwise.
- coefs_key default:
'dsvg_coefs' Prefix for two
adata.varmtables (n_genes x n_bsplines) with the posterior means of the spline coefficients, consumed bydiffsvg.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) andf"{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]]