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 centers 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	.obs column containing the group labels.	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 containing intensities. If None, uses .X. Defaults to None.	None
min_pct	float	Minimum observed fraction required in every compared group or design cell. Defaults to 0.0; the selected test must still be estimable. Features below this threshold have NaN in p_value and q_value.	0.0
stat_method	Literal['welch', 'student', 'wilcoxon', 'limma']	Statistical method: "limma" (moderated-t, default), or "welch", "student", or "wilcoxon" (label permutation).	'limma'
n_resamples	int	Number of label permutations; must be a positive integer for permutation methods. Defaults to 1000. Ignored by limma.	1000
log_transformed	bool	Whether input is already log2-transformed. Defaults to True. Limma expects log2-transformed input.	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	Correction for q_value: "auto", "bh", "by", "bonferroni", "holm", "hochberg", "hommel", or "empirical". Defaults to "auto": "bh" for limma and "empirical" for permutation methods. "empirical" is permutation-only.	'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.

Notes

The returned result provides .to_df() with features, repr_ctrl, repr_expr, pct_ctrl, pct_expr, log2fc, statistic, p_value, and q_value. .plot_volcano(...) delegates to plot_volcano, which uses raw p-values. The analysis returns a result object rather than a new MuData.

Examples:

import msmu as mm
result = mm.tl.run_de(mdata, modality="protein", category="condition", ctrl="control", expr="treated", stat_method="welch")
table = result.to_df()
fig = result.plot_volcano(log2fc_threshold=1.)