check_ranking#

sklr.utils.check_ranking(y: ArrayLike, *, allow_ties: bool = False, allow_incomplete: bool = False, input_name: str = 'y') → ndarray#

Input validation on the rankings of a target.

Each row of y is the ranking of a sample and each column a label, so that y[i, j] is the position of label j in ranking i, from 1 for the most preferred one. Tied labels share their position and the positions must be dense, without gaps between them. np.nan marks a label that is not ranked, and the positions of the ranked labels of each row must be dense from 1, whatever their number. See Ranking representation for the details.

Parameters:

yarray-like of shape (n_samples, n_labels): The rankings to check, with at least one sample and two labels.
allow_tiesbool, default=False: Whether to accept rankings with tied labels, that is, partial label rankings.
allow_incompletebool, default=False: Whether to accept incomplete rankings, with labels that are not ranked.
input_namestr, default=”y”: The name of the rankings in the error messages.

Returns:

y_convertedndarray of shape (n_samples, n_labels): The validated rankings, as a float64 array. It may be y itself if y is already a float64 array.

Raises:

TypeError: If y is a sparse matrix.
ValueError: If y does not encode rankings, because it is not a two-dimensional array of numbers with at least one sample and two labels or because the positions of some ranking are not dense from 1, or if y holds rankings with ties or incomplete rankings that are not allowed.

See also

type_of_ranking: Determine the type of rankings indicated by the target.
sklearn.utils.check_array: Input validation on an array, list, sparse matrix or similar.

Examples

>>> import numpy as np
>>> from sklr.utils import check_ranking
>>> check_ranking([[1, 2, 3], [3, 1, 2]])
array([[1., 2., 3.],
       [3., 1., 2.]])
>>> check_ranking([[1, 1, 2], [3, 1, 2]], allow_ties=True)
array([[1., 1., 2.],
       [3., 1., 2.]])
>>> check_ranking([[2, np.nan, 1], [3, 1, 2]], allow_incomplete=True)
array([[ 2., nan,  1.],
       [ 3.,  1.,  2.]])
>>> check_ranking([[1, 1, 2], [3, 1, 2]])
Traceback (most recent call last):
    ...
ValueError: Expected rankings without ties in y, got y[0] = [1 1 2].