skcriteria.utils.rank module

Functions for calculate and compare ranks (ordinal series).

skcriteria.utils.rank.rank_values(arr, reverse=False)

Evaluate an array and return a 1 based ranking.

Parameters:

• arr ((numpy.ndarray, numpy.ndarray)) – A array with values

• reverse (bool default False) – By default (False) the lesser values are ranked first (like in time lapse in a race or Golf scoring) if is True the data is highest values are the first.

Returns:

Array of rankings the i-nth element has the ranking of the i-nth element of the row array.

Return type:

numpy.ndarray

Examples

>>> from skcriteria.util.rank import rank_values
>>> # the fastest (the lowest value) goes first
>>> time_laps = [0.59, 1.2, 0.3]
>>> rank_values(time_laps)
array([2, 3, 1])
>>> # highest is better
>>> scores = [140, 200, 98]
>>> rank_values(scores, reverse=True)
array([2, 1, 3])

skcriteria.utils.rank.is_rank(values)

Check if an array represents a valid, dense ranking.

This function validates if an array corresponds to a 1-based, dense ranking. A dense ranking has no gaps between the rank values. For example, if the maximum rank is 4, then ranks 1, 2, and 3 must also be present.

The input values are first converted to integers. For example, an input of [1.0, 2.5, 3.1] will be evaluated as [1, 2, 3].

Parameters:

values (array-like) – Array to validate. The values will be coerced to integers.

Returns:

True if values represents a valid rank, otherwise False.

Return type:

bool

Examples

>>> from skcriteria.utils.rank import is_rank
>>> is_rank([1, 2, 3, 2])
True

>>> is_rank([1.0, 2.5, 3.9]) # Coerced to [1, 2, 3]
True

>>> is_rank([1, 4, 4])  # Fails: Gaps are present (2 and 3 are missing).
False

>>> is_rank([2, 3, 4])  # Fails: The ranking must be 1-based.
False

skcriteria.utils.rank.dominance(array_a, array_b, reverse=False)

Calculate the dominance or general dominance between two arrays.

Parameters:

• array_a – The first array to compare.

• array_b – The second array to compare.

• reverse (bool (default=False)) – array_a[i] ≻ array_b[i] if array_a[i] > array_b[i] if reverse is False, otherwise array_a[i] ≻ array_b[i] if array_a[i] < array_b[i]. Also reverse can be an array of boolean of the same shape as array_a and array_b to revert every item independently. In other words, reverse assume the data is a minimization problem.

Returns:

dominance – Named tuple with 4 parameters:

• eq: How many values are equals in both arrays.

• aDb: How many values of array_a dominate those of the same

  position in array_b.

• bDa: How many values of array_b dominate those of the same

  position in array_a.

• eq_where: Where the values of array_a are equals those of the same

  position in array_b.

• aDb_where: Where the values of array_a dominates those of the same

  position in array_b.

• bDa_where: Where the values of array_b dominates those of the same

  position in array_a.

Return type:

_Dominance