mantispy.tl.enrich#

mantispy.tl.enrich(adata, net=None, by='feature_group', method='ulm', methods=None, top_fraction=0.05, n_permutations=0, check_collinearity=True, copy=False, **decoupler_kwargs)[source]#

Score every profile against every feature set.

Parameters:
adata AnnData

Profiles to score. Normalize first, since the methods use the values as given.

net DataFrame | None (default: None)

A decoupler network with source, target and weight, for example prior-knowledge sets. Built from by when omitted.

by str | Sequence[str] (default: 'feature_group')

Passed to feature_sets() when net is not given.

method str (default: 'ulm')

One of METHODS. "ulm" fits a linear model per set and is the usual choice; "mlm" fits all sets jointly, which handles overlapping sets; "ora" is an over-representation test on the extremes; "aucell", "gsea", "gsva", "zscore" and "viper" are the remaining decoupler scorers. "consensus" runs a panel of the single methods and combines their calls, decoupler’s robustness feature.

methods Sequence[str] | None (default: None)

The panel for method="consensus", each entry one of the single methods (METHODS without "consensus"). Defaults to CONSENSUS_PANEL. Only used with method="consensus".

top_fraction float (default: 0.05)

Fraction of features, ranked by value, that ORA counts as extreme, whether method="ora" or "ora" sits in a consensus panel. The default 0.05 tests the top twentieth against the rest. Ignored when n_up is passed, and by the methods that use every feature.

n_permutations int (default: 0)

0 (the default) keeps the method’s own parametric p-values. A positive count replaces padj_<method> with two-sided permutation p-values, obtained by shuffling the network that many times and comparing each score against the null, at n_permutations times the scoring cost. Single methods only; a positive count with method="consensus" raises.

check_collinearity bool (default: True)

Warn when two feature sets are nearly collinear, since enrichment cannot then separate them. Off skips the check.

copy bool (default: False)

Return a modified copy instead of mutating in place.

decoupler_kwargs Any

Passed through to decoupler, e.g. tmin for the smallest usable set. For method="consensus" an args mapping of per-method keyword arguments (as decoupler.mt.decouple takes) is merged with the computed ORA n_up.

Return type:

AnnData | None

Returns:

None, or the modified copy. decoupler writes obsm["score_<method>"], and obsm["padj_<method>"] for the methods that produce one (all but "aucell" and "gsva", which write only the score). method="consensus" writes obsm["score_consensus"] and obsm["padj_consensus"] alongside each panel member’s own score_<method> (and its padj_<method>, except for the score-only "aucell" and "gsva"). All are frames indexed by set name. Each call first clears every score_*/padj_* frame in obsm: enrich owns that namespace and resets it, so chaining two single methods keeps only the last. Use method="consensus" with a panel to hold several methods’ scores at once.

Raises:

ValueError – method is not one of METHODS; methods is given with a non-consensus method, or names an entry that is not a single method; n_permutations is negative, or positive with method="consensus"; no feature set could be built from by; or top_fraction is outside (0, 1).