mantispy.pp.outliers

mantispy.pp.outliers(adata, method='ecod', contamination=0.01, score_cutoff=None, key='selected', by=None, seed=0, ecod_aggregation='pyod', key_added='qc_outlier', copy=False)

Flag outlying cells.

Every method produces a score where higher means more outlying, and the same thresholding applies to all of them, so contamination is the flagged fraction whichever method is used.

Parameters:

adata AnnData

Object to flag.

method str (default: 'ecod')

"ecod" [Li et al., 2023] needs no tuning and is interpretable per feature, "isolation_forest" catches outliers defined by feature interactions, and "mad" takes the largest robust z-score across features, which is easy to explain but sees each feature alone.

contamination float (default: 0.01)

Fraction of cells to flag, rounded up to a whole cell within each by group, so a non-empty group always flags its most outlying cell and the flagged fraction is higher than asked for in a group smaller than 1 / contamination. Ignored when score_cutoff is given.

score_cutoff float | None (default: None)

Threshold the score absolutely instead of by quantile. With method="mad" the score is a robust z-score, so score_cutoff=5 gives the usual rule.

key str | None (default: 'selected')

Input: the name of a boolean var column; only the features it flags are scored, usually "selected". Falls back to every feature when the column is absent. Not the output name, which is key_added.

by str | None (default: None)

Threshold within each group of this obs column, e.g. per plate, rather than globally.

seed int (default: 0)

Seed for isolation_forest.

ecod_aggregation str (default: 'pyod')

How "ecod" combines features. "pyod" sums each feature’s larger tail, or both tails where its skewness is zero or undefined, as pyod and scmorph do, so no score depends on which way round a feature is measured. "paper" is Algorithm 1 of Li et al. [2023], the largest of the left-tail, right-tail and skew-directed sums.

key_added str (default: 'qc_outlier')

Output: the prefix for the results, written to obs[key_added] and obs[key_added + "_score"].

copy bool (default: False)

Return a modified copy instead of mutating in place.

Return type:

AnnData | None

Returns:

None, or the modified copy. Writes the boolean obs[key_added] and the score itself to obs[key_added + "_score"].

Raises:

ValueError – If method or ecod_aggregation is unknown, or contamination is outside (0, 1) and no score_cutoff is given.