msmu.tl.run_de

Run Differential Expression Analysis (DEA) between two groups in a MuData object.

The analysis reads as four stages: (1) data validation — prepare the inputs once and let the engine mask the usable features; (2) test — the engine-specific statistic; (3) fold change — engine-independent group centres and the log2 fold change; (4) fold-change guidance line.

Parameters:

Name	Type	Description	Default
mdata	MuData	MuData object containing the data.	required
modality	str	Modality name within the MuData to analyze.	required
category	str	Observation category to define groups.	required
ctrl	str	Name of the control group.	required
expr	str | None	Name of the experimental group. If None, all other groups are used (not supported for stat_method="limma", which needs an explicit group).	None
layer	str | None	Layer to use for quantification aggregation. If None, the default layer (.X) will be used. Defaults to None.	None
min_pct	float	Minimum non-missing coverage required in every group (design cell), not in at least one, applied as a count: a feature needs max(1, ceil(min_pct * n)) non-missing values in each group. The default 0.0 imposes only the estimability floor — every group needs at least one non-missing value (limma additionally requires residual df >= 1) — so every feature whose contrast can be estimated is tested. Raise it as an opt-in stringency knob to also demand a minimum coverage per group (e.g. 0.5 is 2 of 3, 2 of 4, 3 of 5); choose it from the coverage you observe (pct_ctrl / pct_expr), not from which features come out significant. Features below the threshold are not tested: they stay in the result as rows with repr_* / pct_* filled but p_value / q_value set to NaN. Requiring both groups is what makes the contrast estimable without imputation; the consequence is that on/off features (present in one group, absent in the other) are reported this way rather than receiving a p-value — read them off pct_ctrl / pct_expr.	0.0
stat_method	Literal['welch', 'student', 'wilcoxon', 'limma']	Statistical test to use. Defaults to "limma" (empirical-Bayes moderated-t, recommended for the small sample sizes where a permutation null is degenerate). The permutation engines "welch"/"student"/"wilcoxon" always run a label-permutation test. The fold-change central tendency follows the test: welch/student/limma are mean-based, wilcoxon median-based (so significance and effect size stay on the same scale). For wilcoxon the fold change is the median difference, a pragmatic proxy for the Hodges-Lehmann shift the rank-sum statistic localizes.	'limma'
n_resamples	int	Number of label permutations for the permutation engines (welch/student/ wilcoxon); must be a positive integer (e.g. 1000). Ignored by limma (which does not permute). It is not an on/off switch — for a parametric analysis use stat_method="limma".	1000
log_transformed	bool	If True, data is assumed to be log-transformed. Defaults to True.	True
interaction	str | None	limma only — obs column of a second factor. If set, tests the interaction (difference-in-differences) of expr - ctrl across two of its levels.	None
interaction_levels	list | None	limma only — the two interaction levels to contrast.	None
covariates	list[str] | None	limma only — obs columns to adjust for.	None
p_adjust	str	Multiple-testing correction for the q-value. Default "auto" uses each engine's native default: limma adjusts its moderated p-values with Benjamini-Hochberg ("bh"), the permutation engines use "empirical" (an FDR built from the label-permutation null). The R p.adjust / limma adjust.method family — "bh", "by", "holm", "hochberg", "hommel", "bonferroni" (case-insensitive) — is accepted by both engines and applied identically to their p-values. "empirical" is permutation-only (limma has no null distribution to build it from, so limma + "empirical" raises). There is no "no correction" option — the uncorrected values are the p_value column.	'auto'
_force_resample	bool	If True, forces resampling even if the number of resamples exceeds the number of combinations.	False

Returns:

Type	Description
DeaResult	DeaResult containing DE analysis results.