skcriteria.ranksrev.rank_invariant_check module

Tools for evaluating the stability of MCDA method’s best alternative.

According to this criterion, the best alternative identified by the method should remain unchanged when a non-optimal alternative is replaced by a worse alternative, provided that the relative importance of each decision criterion remains the same.

skcriteria.ranksrev.rank_invariant_check.maximum_abs_noises(*, dm, rank, last_diff_strategy)[source]

Calculate the absolute difference between the alternatives in order.

This difference is used as a maximum possible noise to worsen an alternative.

The last alternative in the ranking has no next alternative to compare, so the value calculated by last_diff_strategy is applied as the abs difference (the default is the np.nanmedian).

Parameters:

  • dm (skcriteria.core.data.DecisionMatrix) – The decision matrix from which the maximum possible absolute noises of each alternative are to be extracted.

  • rank (skcriteria.agg.Rank) – Ranking of alternatives.

  • last_diff_strategy (callable) – Function applied, column-wise, to the noise bounds of every alternative but the worst one, to obtain the bound of the worst alternative (which has no “next worse” alternative to compare against). RankInvariantChecker.last_diff_strategy resolves the "median"/"mean" aliases to this callable.

Returns:

Maximum absolute noise – Each row contains the maximum possible absolute noise to worsen the current alternative (mutate) with respect to the next (mute_next).

Return type:

pandas.DataFrame

skcriteria.ranksrev.rank_invariant_check.mutate_dm(*, dm, mutate, alternative_max_abs_noise, random)[source]

Create a new decision matrix by replacing a suboptimal alternative with a slightly worse one.

The algorithm operates as follows:

  • A random uniform noise [0, b] is generated, where b is the absolute difference in value of the criterion to be modified with respect to the immediately worse alternative.

  • Negative sign is assigned to criteria to be maximized.

  • The noise is applied to the alternative to be worsened (‘mutated’).

This algorithm is designed in such a way that the ‘worsened’ alternative is not worse than the immediately worse one in the reference ranking.

Notes

Without capping, b can be larger than the value being worsened (e.g. when the last_diff_strategy median is used for the worst-ranked alternative in a criterion with heavy-tailed/outlier values, or when two consecutively-ranked alternatives differ wildly in a single criterion). That would let the noise push the value through zero and flip its sign, which most MCDA methods (e.g. entropy-based weighters) do not expect. Capping b at abs(current_value) keeps the noised value on the same side of zero.

Parameters:

  • dm (skcriteria.core.data.DecisionMatrix) – The original decision matrix.

  • mutate (str) – The alternative to mutate.

  • alternative_max_abs_noise (pandas.Series) – The maximum possible noise with which the alternative to mutate can be made worse, without being worse than the immediately worse alternative.

  • random (numpy.random.default_rng) – Random number generator.

Returns:

  • mutated_dm (skcriteria.DecisionMatrix) – Decision matrix with the ‘mutate’ alternative “worsened”.

  • noise (pandas.Series) – Noise used to worsen the alternative.

class skcriteria.ranksrev.rank_invariant_check.RankInvariantChecker(dmaker, *, repeat=1, allow_missing_alternatives=False, last_diff_strategy='median', random_state=None)[source]

Bases: SKCMethodABC

Stability evaluator of MCDA method’s best alternative.

According to this criterion, the best alternative identified by the method should remain unchanged when a non-optimal alternative is replaced by a worse alternative, provided that the relative importance of each decision criterion remains the same.

To illustrate, suppose that the MCDA method has ranked a set of alternatives, and one of the alternatives, \(A_j\), is replaced by another alternative, \(A_j'\), which is less desirable than Ak. The MCDA method should still identify the same best alternative when the alternatives are re-ranked using the same method. Furthermore, the relative rankings of the remaining alternatives that were not changed should also remain the same.

The current implementation worsens each non-optimal alternative repeat times, and stores each resulting output in a collection for comparison with the reference ranking. In essence, the test is run once for each suboptimal alternative.

This class assumes that there is another suboptimal alternative \(A_j\) that is just the next worst alternative to \(A_k\), so that \(A_k \succ A_j\). Then it generates a mutation \(A_k'\) such that \(A_k'\) is worse than \(A_k\) but still better than \(A_j\) (\(A_k \succ A_k' \succ A_j\)). In the case that the worst alternative is reached, its degradation is limited by default with respect to the median of all limits of the previous alternatives mutations, in order not to break he distribution of each criterion.

Parameters:

  • dmaker (Decision maker - must implement the evaluate() method) – The MCDA method, or pipeline to evaluate.

  • repeat (int, default = 1) –

    How many times to mutate each suboptimal alternative.

    The total number of rankings returned by this method is given by the number of alternatives in the decision matrix minus one multiplied by repeat.

  • allow_missing_alternatives (bool, default = False) –

    dmaker can somehow return rankings with fewer alternatives than the original ones (using a pipeline that implements a filter, for example). By setting this parameter to True, the invariance test allows for missing alternatives in a ranking to be added with a value of the maximum value of the ranking obtained + 1.

    On the other hand, if the value is False, when a ranking is missing an alternative, the test will fail with a ValueError.

    If more than one alternative is removed, all of them are added with the same value

  • last_diff_strategy (str or callable (default: "median").) – True if any mutation is allowed that does not possess all the alternatives of the original decision matrix.

  • random_state (int, numpy.random.default_rng or None (default: None)) – Controls the random state to generate variations in the sub-optimal alternatives.

property dmaker

The MCDA method, or pipeline to evaluate.

property repeat

How many times to mutate each suboptimal alternative.

property allow_missing_alternatives

True if any mutation is allowed that does not possess all the alternatives of the original decision matrix.

property last_diff_strategy

Since the least preferred alternative has no lower bound (since there is nothing immediately below it), this function calculates a limit ceiling based on the bounds of all the other suboptimal alternatives.

property random_state

Controls the random state to generate variations in the sub-optimal alternatives.

evaluate(dm)[source]

Executes a the invariance test.

Parameters:

dm (DecisionMatrix) – The decision matrix to be evaluated.

Returns:

An object containing multiple rankings of the alternatives, with information on any changes made to the original decision matrix in the extra_ attribute. Specifically, the extra_ attribute contains a an object in the key rank_inv_check that provides information on any changes made to the original decision matrix, including the the noise applied to worsen any sub-optimal alternative.

Return type:

RanksComparator