smallest_weight_perturbation

mcda.smallest_weight_perturbation(scores, polarity, weights='equal', method='saw', bounds=None, fragility_threshold=0.05, search_range=1.0, tolerance=1e-09, normalization=None, baselines=None, targets=None, missing='error')

Compute the smallest single-weight change that swaps each pair of tools.

For every ordered pair where tool a is currently above tool b, the function looks for the criterion whose weight, when changed alone (and kept non-negative), flips the pair ordering with the smallest absolute change. It reports that criterion, the signed change, and the resulting weight.

SAW path (exact). For SAW the composite difference between two tools is a linear function of the weights:

C_a - C_b = sum_k w_k * (x_ak - x_bk)

where x is the normalized matrix. The smallest change to weight k alone that brings this difference to zero is

delta_k = (C_b - C_a) / (x_ak - x_bk)

when the denominator is non-zero. This closed form is exact and fast.

Numeric path (to a tolerance). For TOPSIS, VIKOR, PROMETHEE II and COMET the composite is not linear in the weights, so no closed form exists. For each criterion the function defines the signed rank gap

g(delta) = C_a(w + delta * e_k) - C_b(w + delta * e_k)

where e_k is the unit vector on criterion k and the composite comes from the actual aggregation. The pair is currently ordered so g(0) > 0. The search scans delta over a capped range on both sides, in the feasible direction that keeps w_k + delta >= 0, to find a sign change of g. When a sign change is bracketed, bisection refines the crossing to tolerance on delta. The criterion with the smallest feasible |delta| is reported. When no single-weight change within search_range flips the pair on any criterion the criterion is reported as -1.

Parameters

Name	Type	Description	Default
scores		Array-like of shape (n_tools, n_metrics).	required
polarity	Sequence[str]	Length n_metrics sequence of polarity strings.	required
weights		Forwarded to run. "equal", "entropy", or an explicit array.	'equal'
method	str	Any of the five methods supported by run: "saw" (closed-form path), or "topsis", "vikor", "promethee_ii", "comet" (numeric path).	'saw'
bounds		Optional declared bounds, forwarded to run.	None
normalization		Optional per-metric normalization context forwarded to run. Default None keeps the run defaults. Pass the values from beam.mcda.registry_context so the perturbation search rests on the same normalized matrix as the headline ranking.	None
baselines		Optional per-metric normalization context forwarded to run. Default None keeps the run defaults. Pass the values from beam.mcda.registry_context so the perturbation search rests on the same normalized matrix as the headline ranking.	None
targets		Optional per-metric normalization context forwarded to run. Default None keeps the run defaults. Pass the values from beam.mcda.registry_context so the perturbation search rests on the same normalized matrix as the headline ranking.	None
fragility_threshold	float	Absolute weight delta below which the top-rank flip is flagged as fragile in top_rank_is_fragile. Default 0.05, i.e. five percentage points of a weight in [0, 1].	0.05
search_range	float	Numeric path only. Largest absolute single-weight change considered. Defaults to 1.0, the full span of a weight in [0, 1]. Ignored by the SAW path, which has no range cap.	1.0
tolerance	float	Numeric path only. Bisection tolerance on the weight change delta. Defaults to 1e-9. Ignored by the SAW path.	1e-09

Returns

Type	Description
WeightPerturbationReport