msmu.pp.normalise

Normalize data in MuData object.

Parameters:

Name	Type	Description	Default
mdata	MuData	MuData object to normalize.	required
method	NormalisationMethod	Normalization method to use. Options are 'median', 'median_center', 'quantile', 'total_sum', 'pairwise_median'.	required
modality	str	Modality to normalize.	required
layer	str | None	Layer to normalize. If None, the default layer (.X) will be used.	None
group_obs	str | None	Column name in adata.obs defining sample groups. If provided, normalization is performed independently within each group. Missing group values are rejected. If None, no .obs grouping is applied.	None
group_var	str | None	Column name in adata.var defining feature groups (e.g., "filename" for fractionated TMT or label-free workflows). If provided, normalization is performed independently within each group. If None, no .var grouping is applied.	None
batch_key	str | None	Deprecated alias for group_obs.	None
fraction_key	str | None	Deprecated alias for group_var.	None
fraction	bool	Deprecated. If True, equivalent to group_var="filename".	False

Returns:

Type	Description
MuData	Normalized copy of the MuData object; the selected .X or layer is updated in the copy.

Notes

When both group_obs and group_var are provided, normalization is performed independently within each (observation group × feature group) block.

method="pairwise_median" aligns samples on the features they share: for every pair of samples it takes the median log2 difference over their co-observed features, and each sample's shift is the mean of its pairwise medians over all samples (the equal-weight least-squares solution, shifts summing to zero). It assumes that most of the features shared between two samples are unchanged. Per-sample medians of observed values are no longer aligned afterward; this is intended, as those differences reflect which features each sample observed rather than loading. A true global change between conditions is removed, as with median. Two samples of a block that observe no feature in common raise a ValueError naming them (for example PSMs or precursors across runs or TMT plexes): normalize within group_obs, or after summarizing to a level where the samples share features.

Every call records what was done to each sample of each block in adata.uns["normalisation"]: a summary table (sample, obs_group, var_group, method, layer, n_observed_features, shift_log2, location_before, location_after) and, per block, the per-sample vectors plus, for pairwise_median, the pair_median_log2 and pair_shared_count matrices the shifts were derived from. Records for the same layer are replaced on a repeated call.