liana.multi.estimate_elbow

Contents

liana.multi.estimate_elbow#

liana.multi.estimate_elbow(X, k_range, verbose=False, **kwargs)#

Estimate the rank of an NMF factorization from the elbow of its error curve.

Parameters:

  • X – Non-negative matrix to factorize.

  • k_range – Ranks to fit. The elbow is located among these, so None is returned if no knee is found within them.

  • verbose (default: False) – Whether to show a progress bar and report the estimated rank.

  • kwargs – Keyword arguments passed to sklearn.decomposition.NMF.

Returns:

A tuple of the reconstruction error per rank (a DataFrame with columns k and error) and the estimated rank.

Examples

Called by liana.multi.nmf() when n_components is None. Unlike nmf it takes a plain non-negative matrix, not an AnnData. This one is built from two blocks, so its true rank is 2:

>>> import numpy as np
>>> import liana as li
>>> W = np.repeat(np.eye(2), 6, axis=0)
>>> H = np.array([[3., 2., 1., 0., 0., 0.],
...               [0., 0., 0., 1., 2., 3.]])
>>> errors, rank = li.multi.estimate_elbow(W @ H, k_range=range(1, 6),
...                                        random_state=0, max_iter=500)

rank is the knee of the error curve – 2 here, since the error collapses as soon as k reaches the true rank and cannot improve after.

If no knee can be located within k_range, rank comes back as None – widen the range. A k_range that starts above the true rank returns its own lowest value.

Contents