mtrs-sdibca-toolkit 1.4.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mtrs/__init__.py +59 -0
- mtrs/core.py +312 -0
- mtrs/io.py +148 -0
- mtrs/metrics.py +89 -0
- mtrs/report.py +131 -0
- mtrs/uncertainty.py +210 -0
- mtrs_sdibca_toolkit-1.4.0.dist-info/METADATA +178 -0
- mtrs_sdibca_toolkit-1.4.0.dist-info/RECORD +14 -0
- mtrs_sdibca_toolkit-1.4.0.dist-info/WHEEL +5 -0
- mtrs_sdibca_toolkit-1.4.0.dist-info/licenses/LICENSE +21 -0
- mtrs_sdibca_toolkit-1.4.0.dist-info/top_level.txt +2 -0
- sdibca/__init__.py +19 -0
- sdibca/metrics.py +33 -0
- sdibca/model.py +239 -0
mtrs/__init__.py
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
"""MTRS: Multivariate Transport Ranking Stability test.
|
|
2
|
+
|
|
3
|
+
Reference implementation of the MTRS procedure for assessing the
|
|
4
|
+
stability of transport policy scenario rankings under six sources of
|
|
5
|
+
uncertainty:
|
|
6
|
+
|
|
7
|
+
1. model structure
|
|
8
|
+
2. parameter uncertainty
|
|
9
|
+
3. data-year (vintage) uncertainty
|
|
10
|
+
4. policy-mapping uncertainty
|
|
11
|
+
5. indicator-weight uncertainty
|
|
12
|
+
6. metropolitan-area structure (cross-area transferability)
|
|
13
|
+
|
|
14
|
+
The test decomposes ranking instability into per-source variance shares
|
|
15
|
+
and evaluates three reporting rules: when a ranking may be reported as
|
|
16
|
+
stable, when it may reverse, and when it cannot be transferred across
|
|
17
|
+
metropolitan-area structures.
|
|
18
|
+
|
|
19
|
+
Public API
|
|
20
|
+
----------
|
|
21
|
+
MTRSAnalysis configure and run the test
|
|
22
|
+
MTRSResult result object (decomposition + verdict)
|
|
23
|
+
UncertaintySpec definitions of the six uncertainty sources
|
|
24
|
+
load_matrix CSV helpers for decision matrices and inputs
|
|
25
|
+
load_vector
|
|
26
|
+
load_vintages
|
|
27
|
+
rank_vector ranking helper (ties -> average rank)
|
|
28
|
+
rank_displacement sum of absolute rank differences
|
|
29
|
+
kendall_tau_distance normalised Kendall tau distance
|
|
30
|
+
render_text_report plain-text assessment report
|
|
31
|
+
render_json_report machine-readable assessment report
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
__version__ = "1.4.0"
|
|
35
|
+
|
|
36
|
+
from .metrics import kendall_tau_distance, max_displacement, rank_displacement, rank_vector
|
|
37
|
+
from .io import load_matrix, load_vector, load_vintages, load_stages
|
|
38
|
+
from .uncertainty import UncertaintySpec
|
|
39
|
+
from .core import MTRSAnalysis, MTRSResult, SourceDecomposition, DEFAULT_THRESHOLDS
|
|
40
|
+
from .report import render_text_report, render_json_report
|
|
41
|
+
|
|
42
|
+
__all__ = [
|
|
43
|
+
"MTRSAnalysis",
|
|
44
|
+
"MTRSResult",
|
|
45
|
+
"SourceDecomposition",
|
|
46
|
+
"UncertaintySpec",
|
|
47
|
+
"DEFAULT_THRESHOLDS",
|
|
48
|
+
"rank_vector",
|
|
49
|
+
"rank_displacement",
|
|
50
|
+
"kendall_tau_distance",
|
|
51
|
+
"max_displacement",
|
|
52
|
+
"load_matrix",
|
|
53
|
+
"load_vector",
|
|
54
|
+
"load_vintages",
|
|
55
|
+
"load_stages",
|
|
56
|
+
"render_text_report",
|
|
57
|
+
"render_json_report",
|
|
58
|
+
"__version__",
|
|
59
|
+
]
|
mtrs/core.py
ADDED
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
"""Core MTRS analysis engine.
|
|
2
|
+
|
|
3
|
+
Given a decision matrix X (scenarios x indicators) and nominal indicator
|
|
4
|
+
weights w, the test
|
|
5
|
+
|
|
6
|
+
1. computes the base scenario ranking,
|
|
7
|
+
2. draws an ensemble of perturbed (X', w') realisations from each
|
|
8
|
+
active uncertainty source,
|
|
9
|
+
3. decomposes ranking instability into per-source variance shares,
|
|
10
|
+
4. evaluates the three reporting rules (stable / reversal /
|
|
11
|
+
non-transferable).
|
|
12
|
+
|
|
13
|
+
The stability score S is defined as
|
|
14
|
+
|
|
15
|
+
S = 1 - D / D_max
|
|
16
|
+
|
|
17
|
+
where D is the mean total rank displacement over the ensemble and
|
|
18
|
+
D_max = floor(n^2 / 2) is the largest possible displacement between two
|
|
19
|
+
permutations of n scenarios. S = 1 means every ensemble member reproduces
|
|
20
|
+
the base ranking exactly.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
import math
|
|
26
|
+
import random
|
|
27
|
+
from dataclasses import dataclass, field
|
|
28
|
+
from typing import List, Optional, Sequence
|
|
29
|
+
|
|
30
|
+
from .metrics import kendall_tau_distance, max_displacement, rank_displacement, rank_vector
|
|
31
|
+
from .uncertainty import UncertaintySpec, build_generators
|
|
32
|
+
|
|
33
|
+
#: Default decision-rule thresholds. Pass ``thresholds={...}`` to
|
|
34
|
+
#: :class:`MTRSAnalysis` to override.
|
|
35
|
+
DEFAULT_THRESHOLDS = {
|
|
36
|
+
#: minimum stability score S for a ranking reportable as stable
|
|
37
|
+
"stability_score": 0.80,
|
|
38
|
+
#: top-rank flip frequency above which a reversal is declared
|
|
39
|
+
"reversal_probability": 0.10,
|
|
40
|
+
#: share of area-structure draws that must fail for non-transferability
|
|
41
|
+
"transfer_failure_rate": 0.30,
|
|
42
|
+
#: per-draw displacement ratio (displacement / max displacement)
|
|
43
|
+
#: that counts as a transfer failure
|
|
44
|
+
"transfer_displacement": 0.25,
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
_VERDICT_DESCRIPTION = {
|
|
48
|
+
"STABLE": "the ranking is stable under the assessed uncertainty and may be reported as is",
|
|
49
|
+
"REVERSAL": "the ranking may reverse; do not report it as stable",
|
|
50
|
+
"NON-TRANSFERABLE": "the ranking is not transferable across metropolitan-area structures "
|
|
51
|
+
"(or does not meet the stability threshold); do not report or transfer it without further analysis",
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@dataclass
|
|
56
|
+
class SourceDecomposition:
|
|
57
|
+
"""Per-source ranking-instability statistics."""
|
|
58
|
+
|
|
59
|
+
name: str
|
|
60
|
+
draws: int
|
|
61
|
+
mean_displacement: float
|
|
62
|
+
displacement_variance: float
|
|
63
|
+
variance_share: float #: fraction of total variance explained, 0..1
|
|
64
|
+
mean_tau: float #: mean Kendall tau distance to the base ranking
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
@dataclass
|
|
68
|
+
class MTRSResult:
|
|
69
|
+
"""Outcome of an MTRS run."""
|
|
70
|
+
|
|
71
|
+
scenario_names: List[str]
|
|
72
|
+
indicator_names: List[str]
|
|
73
|
+
base_ranking: List[float]
|
|
74
|
+
stability_score: float
|
|
75
|
+
verdict: str
|
|
76
|
+
reversal_probability: float
|
|
77
|
+
transfer_failure_rate: Optional[float] #: None when not assessed
|
|
78
|
+
decomposition: List[SourceDecomposition]
|
|
79
|
+
rules: dict
|
|
80
|
+
n_draws: int
|
|
81
|
+
seed: int
|
|
82
|
+
thresholds: dict
|
|
83
|
+
active_sources: List[str]
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def _normalise_columns(matrix: Sequence[Sequence[float]]) -> List[List[float]]:
|
|
87
|
+
"""Min-max normalise each indicator column to [0, 1].
|
|
88
|
+
|
|
89
|
+
A constant column carries no ranking information and is mapped to
|
|
90
|
+
zero. (``direction`` is applied later, when scores are computed.)
|
|
91
|
+
"""
|
|
92
|
+
n = len(matrix)
|
|
93
|
+
m = len(matrix[0])
|
|
94
|
+
out = [[0.0] * m for _ in range(n)]
|
|
95
|
+
for j in range(m):
|
|
96
|
+
col = [matrix[i][j] for i in range(n)]
|
|
97
|
+
lo, hi = min(col), max(col)
|
|
98
|
+
if hi > lo:
|
|
99
|
+
span = hi - lo
|
|
100
|
+
for i in range(n):
|
|
101
|
+
out[i][j] = (matrix[i][j] - lo) / span
|
|
102
|
+
return out
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def _scores(normalised: Sequence[Sequence[float]], weights: Sequence[float],
|
|
106
|
+
directions: Sequence[float]) -> List[float]:
|
|
107
|
+
"""Weighted sum of indicator values, honouring benefit directions."""
|
|
108
|
+
return [
|
|
109
|
+
sum(w * d * v for w, d, v in zip(weights, directions, row))
|
|
110
|
+
for row in normalised
|
|
111
|
+
]
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def _top_index(scores: Sequence[float]) -> int:
|
|
115
|
+
"""Index of the top-ranked scenario (first maximum, no tie breaking)."""
|
|
116
|
+
return max(range(len(scores)), key=lambda i: scores[i])
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
class MTRSAnalysis:
|
|
120
|
+
"""Configure and run the Multivariate Transport Ranking Stability test.
|
|
121
|
+
|
|
122
|
+
Parameters
|
|
123
|
+
----------
|
|
124
|
+
matrix : sequence of sequences of numbers
|
|
125
|
+
Decision matrix, shape (scenarios, indicators). Values must be
|
|
126
|
+
finite.
|
|
127
|
+
scenario_names : sequence of str, optional
|
|
128
|
+
Defaults to ``S1..Sn``.
|
|
129
|
+
indicator_names : sequence of str, optional
|
|
130
|
+
Defaults to ``I1..Im``.
|
|
131
|
+
weights : sequence of numbers, optional
|
|
132
|
+
Nominal indicator weights; non-negative, normalised internally.
|
|
133
|
+
Defaults to equal weights.
|
|
134
|
+
directions : sequence of +1 / -1, optional
|
|
135
|
+
Benefit direction per indicator: +1 higher-better (default),
|
|
136
|
+
-1 lower-better (e.g. cost indicators).
|
|
137
|
+
spec : UncertaintySpec, optional
|
|
138
|
+
Uncertainty-source definitions. An empty spec runs the base
|
|
139
|
+
ranking only.
|
|
140
|
+
thresholds : dict, optional
|
|
141
|
+
Overrides for :data:`DEFAULT_THRESHOLDS`.
|
|
142
|
+
"""
|
|
143
|
+
|
|
144
|
+
def __init__(
|
|
145
|
+
self,
|
|
146
|
+
matrix: Sequence[Sequence[float]],
|
|
147
|
+
scenario_names: Optional[Sequence[str]] = None,
|
|
148
|
+
indicator_names: Optional[Sequence[str]] = None,
|
|
149
|
+
weights: Optional[Sequence[float]] = None,
|
|
150
|
+
directions: Optional[Sequence[float]] = None,
|
|
151
|
+
spec: Optional[UncertaintySpec] = None,
|
|
152
|
+
thresholds: Optional[dict] = None,
|
|
153
|
+
):
|
|
154
|
+
if len(matrix) < 2:
|
|
155
|
+
raise ValueError("at least two scenarios are required")
|
|
156
|
+
n = len(matrix)
|
|
157
|
+
m = len(matrix[0])
|
|
158
|
+
for row in matrix:
|
|
159
|
+
if len(row) != m:
|
|
160
|
+
raise ValueError("decision matrix must be rectangular")
|
|
161
|
+
for cell in row:
|
|
162
|
+
if not math.isfinite(float(cell)):
|
|
163
|
+
raise ValueError("decision matrix values must be finite")
|
|
164
|
+
self.matrix = [[float(c) for c in row] for row in matrix]
|
|
165
|
+
self.scenario_names = list(scenario_names) if scenario_names else [
|
|
166
|
+
"S%d" % (i + 1) for i in range(n)
|
|
167
|
+
]
|
|
168
|
+
if len(self.scenario_names) != n:
|
|
169
|
+
raise ValueError("scenario_names must match the number of matrix rows")
|
|
170
|
+
self.indicator_names = list(indicator_names) if indicator_names else [
|
|
171
|
+
"I%d" % (j + 1) for j in range(m)
|
|
172
|
+
]
|
|
173
|
+
if len(self.indicator_names) != m:
|
|
174
|
+
raise ValueError("indicator_names must match the number of matrix columns")
|
|
175
|
+
|
|
176
|
+
if weights is None:
|
|
177
|
+
weights = [1.0] * m
|
|
178
|
+
if len(weights) != m:
|
|
179
|
+
raise ValueError("weights must match the number of indicators")
|
|
180
|
+
if any(w < 0 for w in weights) or sum(weights) <= 0:
|
|
181
|
+
raise ValueError("weights must be non-negative and not all zero")
|
|
182
|
+
total = float(sum(weights))
|
|
183
|
+
self.weights = [w / total for w in weights]
|
|
184
|
+
|
|
185
|
+
if directions is None:
|
|
186
|
+
directions = [1.0] * m
|
|
187
|
+
if len(directions) != m or any(d not in (1.0, -1.0) for d in directions):
|
|
188
|
+
raise ValueError("directions must be a sequence of +1/-1 matching the indicators")
|
|
189
|
+
self.directions = [float(d) for d in directions]
|
|
190
|
+
|
|
191
|
+
self.spec = spec if spec is not None else UncertaintySpec()
|
|
192
|
+
self.thresholds = dict(DEFAULT_THRESHOLDS)
|
|
193
|
+
if thresholds:
|
|
194
|
+
self.thresholds.update(thresholds)
|
|
195
|
+
|
|
196
|
+
def run(self, n_draws: int = 1000, seed: int = 42) -> MTRSResult:
|
|
197
|
+
"""Run the ensemble analysis and return an :class:`MTRSResult`.
|
|
198
|
+
|
|
199
|
+
Parameters
|
|
200
|
+
----------
|
|
201
|
+
n_draws : int
|
|
202
|
+
Ensemble size per active uncertainty source.
|
|
203
|
+
seed : int
|
|
204
|
+
Random seed; identical inputs and seed reproduce identical
|
|
205
|
+
results.
|
|
206
|
+
"""
|
|
207
|
+
if n_draws < 1:
|
|
208
|
+
raise ValueError("n_draws must be at least 1")
|
|
209
|
+
|
|
210
|
+
rng = random.Random(seed)
|
|
211
|
+
n = len(self.matrix)
|
|
212
|
+
dmax = max_displacement(n)
|
|
213
|
+
|
|
214
|
+
normalised = _normalise_columns(self.matrix)
|
|
215
|
+
base_scores = _scores(normalised, self.weights, self.directions)
|
|
216
|
+
base_rank = rank_vector(base_scores)
|
|
217
|
+
base_top = _top_index(base_scores)
|
|
218
|
+
|
|
219
|
+
generators = build_generators(self.spec, self.matrix, self.weights)
|
|
220
|
+
th = self.thresholds
|
|
221
|
+
|
|
222
|
+
decomposition: List[SourceDecomposition] = []
|
|
223
|
+
all_displacements: List[float] = []
|
|
224
|
+
reversals = 0
|
|
225
|
+
total_draws = 0
|
|
226
|
+
transfer_failures = 0
|
|
227
|
+
transfer_draws = 0
|
|
228
|
+
|
|
229
|
+
for name, gen in generators.items():
|
|
230
|
+
displacements: List[float] = []
|
|
231
|
+
taus: List[float] = []
|
|
232
|
+
for _ in range(n_draws):
|
|
233
|
+
matrix_d, weights_d = gen(rng)
|
|
234
|
+
scores_d = _scores(_normalise_columns(matrix_d), weights_d, self.directions)
|
|
235
|
+
rank_d = rank_vector(scores_d)
|
|
236
|
+
disp = rank_displacement(base_rank, rank_d)
|
|
237
|
+
displacements.append(disp)
|
|
238
|
+
taus.append(kendall_tau_distance(base_rank, rank_d))
|
|
239
|
+
if _top_index(scores_d) != base_top:
|
|
240
|
+
reversals += 1
|
|
241
|
+
total_draws += 1
|
|
242
|
+
if name == "area_structure":
|
|
243
|
+
transfer_draws += 1
|
|
244
|
+
if disp / dmax > th["transfer_displacement"]:
|
|
245
|
+
transfer_failures += 1
|
|
246
|
+
|
|
247
|
+
mean = sum(displacements) / len(displacements)
|
|
248
|
+
var = sum((d - mean) ** 2 for d in displacements) / len(displacements)
|
|
249
|
+
decomposition.append(
|
|
250
|
+
SourceDecomposition(
|
|
251
|
+
name=name,
|
|
252
|
+
draws=n_draws,
|
|
253
|
+
mean_displacement=mean,
|
|
254
|
+
displacement_variance=var,
|
|
255
|
+
variance_share=0.0,
|
|
256
|
+
mean_tau=sum(taus) / len(taus),
|
|
257
|
+
)
|
|
258
|
+
)
|
|
259
|
+
all_displacements.extend(displacements)
|
|
260
|
+
|
|
261
|
+
total_variance = sum(sd.displacement_variance for sd in decomposition)
|
|
262
|
+
for sd in decomposition:
|
|
263
|
+
sd.variance_share = sd.displacement_variance / total_variance if total_variance > 0 else 0.0
|
|
264
|
+
|
|
265
|
+
mean_total_displacement = (
|
|
266
|
+
sum(all_displacements) / len(all_displacements) if all_displacements else 0.0
|
|
267
|
+
)
|
|
268
|
+
stability_score = max(0.0, 1.0 - mean_total_displacement / dmax)
|
|
269
|
+
reversal_probability = reversals / total_draws if total_draws else 0.0
|
|
270
|
+
transfer_failure_rate = (
|
|
271
|
+
transfer_failures / transfer_draws if transfer_draws else None
|
|
272
|
+
)
|
|
273
|
+
|
|
274
|
+
reversal_risk = reversal_probability > th["reversal_probability"]
|
|
275
|
+
transfer_assessed = transfer_failure_rate is not None
|
|
276
|
+
transferable = None
|
|
277
|
+
if transfer_assessed:
|
|
278
|
+
transferable = transfer_failure_rate <= th["transfer_failure_rate"]
|
|
279
|
+
|
|
280
|
+
if reversal_risk:
|
|
281
|
+
verdict = "REVERSAL"
|
|
282
|
+
elif transfer_assessed and not transferable:
|
|
283
|
+
verdict = "NON-TRANSFERABLE"
|
|
284
|
+
elif stability_score >= th["stability_score"]:
|
|
285
|
+
verdict = "STABLE"
|
|
286
|
+
else:
|
|
287
|
+
# Fails the stability threshold but shows no clear reversal:
|
|
288
|
+
# conservative default per the method's reporting rules.
|
|
289
|
+
verdict = "NON-TRANSFERABLE"
|
|
290
|
+
|
|
291
|
+
rules = {
|
|
292
|
+
"reportable_as_stable": (stability_score >= th["stability_score"]) and not reversal_risk,
|
|
293
|
+
"reversal_risk": reversal_risk,
|
|
294
|
+
"transferable_across_areas": transferable,
|
|
295
|
+
"stability_threshold_met": stability_score >= th["stability_score"],
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
return MTRSResult(
|
|
299
|
+
scenario_names=list(self.scenario_names),
|
|
300
|
+
indicator_names=list(self.indicator_names),
|
|
301
|
+
base_ranking=base_rank,
|
|
302
|
+
stability_score=stability_score,
|
|
303
|
+
verdict=verdict,
|
|
304
|
+
reversal_probability=reversal_probability,
|
|
305
|
+
transfer_failure_rate=transfer_failure_rate,
|
|
306
|
+
decomposition=decomposition,
|
|
307
|
+
rules=rules,
|
|
308
|
+
n_draws=n_draws,
|
|
309
|
+
seed=seed,
|
|
310
|
+
thresholds=dict(th),
|
|
311
|
+
active_sources=self.spec.active_sources(),
|
|
312
|
+
)
|
mtrs/io.py
ADDED
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
"""CSV input helpers for the toolkit.
|
|
2
|
+
|
|
3
|
+
Layout conventions
|
|
4
|
+
------------------
|
|
5
|
+
``load_matrix``
|
|
6
|
+
First row is a header naming the indicators; the first column names
|
|
7
|
+
the scenarios. Every remaining cell is a number.
|
|
8
|
+
|
|
9
|
+
scenario,ind_a,ind_b
|
|
10
|
+
Scenario 1,10,5
|
|
11
|
+
Scenario 2,6,9
|
|
12
|
+
|
|
13
|
+
``load_vector``
|
|
14
|
+
Two columns (name, value).
|
|
15
|
+
|
|
16
|
+
``load_vintages``
|
|
17
|
+
Like ``load_matrix`` but rows are data-year vintages and cells are
|
|
18
|
+
*relative* shifts applied to each indicator (0.03 means +3%).
|
|
19
|
+
|
|
20
|
+
``load_stages``
|
|
21
|
+
SDI-BCA stage definitions; ``depends_on`` is a ';'-separated list of
|
|
22
|
+
prerequisite stage names.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
import csv
|
|
28
|
+
from typing import Any, Dict, List, Sequence, Tuple
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _clean_rows(path: str) -> List[List[str]]:
|
|
32
|
+
with open(path, newline="", encoding="utf-8") as fh:
|
|
33
|
+
rows = list(csv.reader(fh))
|
|
34
|
+
rows = [r for r in rows if r and any(c.strip() for c in r)]
|
|
35
|
+
if not rows:
|
|
36
|
+
raise ValueError("empty CSV file: %s" % path)
|
|
37
|
+
return rows
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def load_matrix(path: str) -> Tuple[List[List[float]], List[str], List[str]]:
|
|
41
|
+
"""Read a decision matrix CSV.
|
|
42
|
+
|
|
43
|
+
Returns ``(matrix, row_names, column_names)`` where ``matrix`` is a
|
|
44
|
+
list of lists of floats.
|
|
45
|
+
"""
|
|
46
|
+
rows = _clean_rows(path)
|
|
47
|
+
if len(rows) < 2:
|
|
48
|
+
raise ValueError("matrix CSV needs a header row and at least one data row: %s" % path)
|
|
49
|
+
column_names = [c.strip() for c in rows[0][1:]]
|
|
50
|
+
if not column_names:
|
|
51
|
+
raise ValueError("matrix CSV needs indicator columns: %s" % path)
|
|
52
|
+
row_names: List[str] = []
|
|
53
|
+
matrix: List[List[float]] = []
|
|
54
|
+
for r in rows[1:]:
|
|
55
|
+
if len(r) - 1 != len(column_names):
|
|
56
|
+
raise ValueError(
|
|
57
|
+
"ragged row in %s: expected %d values, got %d (row %r)"
|
|
58
|
+
% (path, len(column_names), len(r) - 1, r[:1])
|
|
59
|
+
)
|
|
60
|
+
row_names.append(r[0].strip())
|
|
61
|
+
matrix.append([float(c) for c in r[1:]])
|
|
62
|
+
return matrix, row_names, column_names
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def load_vector(path: str) -> List[Tuple[str, float]]:
|
|
66
|
+
"""Read a two-column CSV (name, value) into a list of tuples.
|
|
67
|
+
|
|
68
|
+
An optional header row (whose second cell is not a number) is
|
|
69
|
+
skipped automatically.
|
|
70
|
+
"""
|
|
71
|
+
rows = _clean_rows(path)
|
|
72
|
+
data = rows
|
|
73
|
+
try:
|
|
74
|
+
float(rows[0][1])
|
|
75
|
+
except (ValueError, IndexError):
|
|
76
|
+
data = rows[1:] # header row detected
|
|
77
|
+
if not data:
|
|
78
|
+
raise ValueError("vector CSV needs at least one data row: %s" % path)
|
|
79
|
+
out = []
|
|
80
|
+
for r in data:
|
|
81
|
+
if len(r) < 2:
|
|
82
|
+
raise ValueError("vector CSV needs two columns: %s" % path)
|
|
83
|
+
out.append((r[0].strip(), float(r[1])))
|
|
84
|
+
return out
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def load_vintages(path: str) -> Tuple[List[Tuple[str, List[List[float]]]], List[str]]:
|
|
88
|
+
"""Read a stacked vintage-shift CSV.
|
|
89
|
+
|
|
90
|
+
Layout: ``vintage,scenario,ind_a,ind_b,...`` — one block of rows per
|
|
91
|
+
vintage, each row holding the per-scenario relative shifts for that
|
|
92
|
+
vintage. Returns ``(vintages, indicator_names)`` where each vintage
|
|
93
|
+
is ``(name, shift_matrix)`` and ``shift_matrix`` has the same shape
|
|
94
|
+
as the base decision matrix.
|
|
95
|
+
"""
|
|
96
|
+
rows = _clean_rows(path)
|
|
97
|
+
if len(rows) < 3:
|
|
98
|
+
raise ValueError("vintage CSV needs a header and at least two data rows: %s" % path)
|
|
99
|
+
indicator_names = [c.strip() for c in rows[0][2:]]
|
|
100
|
+
vintages: List[Tuple[str, List[List[float]]]] = []
|
|
101
|
+
current: List[List[float]] = []
|
|
102
|
+
current_name = None
|
|
103
|
+
for r in rows[1:]:
|
|
104
|
+
name = r[0].strip()
|
|
105
|
+
if len(r) - 2 != len(indicator_names):
|
|
106
|
+
raise ValueError("ragged vintage row in %s" % path)
|
|
107
|
+
shifts = [float(c) for c in r[2:]]
|
|
108
|
+
if current_name is None:
|
|
109
|
+
current_name = name
|
|
110
|
+
if name != current_name:
|
|
111
|
+
vintages.append((current_name, current))
|
|
112
|
+
current_name = name
|
|
113
|
+
current = []
|
|
114
|
+
current.append(shifts)
|
|
115
|
+
if current_name is not None:
|
|
116
|
+
vintages.append((current_name, current))
|
|
117
|
+
return vintages, indicator_names
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def load_stages(path: str) -> List[Dict[str, Any]]:
|
|
121
|
+
"""Read SDI-BCA stage definitions.
|
|
122
|
+
|
|
123
|
+
Columns: ``name,start_year,duration,annual_cost,annual_benefit,
|
|
124
|
+
ramp_up,handover_lag,depends_on``. ``depends_on`` is a ';'-separated
|
|
125
|
+
list of prerequisite stage names (may be empty).
|
|
126
|
+
"""
|
|
127
|
+
rows = _clean_rows(path)
|
|
128
|
+
header = [c.strip() for c in rows[0]]
|
|
129
|
+
required = {"name", "start_year", "duration", "annual_cost", "annual_benefit"}
|
|
130
|
+
missing = required - set(header)
|
|
131
|
+
if missing:
|
|
132
|
+
raise ValueError("stage CSV missing columns: %s" % ", ".join(sorted(missing)))
|
|
133
|
+
stages = []
|
|
134
|
+
for r in rows[1:]:
|
|
135
|
+
d = dict(zip(header, [c.strip() for c in r]))
|
|
136
|
+
stages.append(
|
|
137
|
+
{
|
|
138
|
+
"name": d["name"],
|
|
139
|
+
"start_year": int(float(d["start_year"])),
|
|
140
|
+
"duration": int(float(d["duration"])),
|
|
141
|
+
"annual_cost": float(d["annual_cost"]),
|
|
142
|
+
"annual_benefit": float(d["annual_benefit"]),
|
|
143
|
+
"ramp_up": float(d.get("ramp_up") or 0.0),
|
|
144
|
+
"handover_lag": float(d.get("handover_lag") or 0.0),
|
|
145
|
+
"depends_on": tuple(x for x in d.get("depends_on", "").split(";") if x),
|
|
146
|
+
}
|
|
147
|
+
)
|
|
148
|
+
return stages
|
mtrs/metrics.py
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
"""Ranking metrics used by the MTRS test.
|
|
2
|
+
|
|
3
|
+
All metrics operate on rank vectors. Ranks are 1-based and ties receive
|
|
4
|
+
the average of the ranks they span, so the metrics stay well defined for
|
|
5
|
+
tied scenario scores.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from typing import Sequence
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def rank_vector(scores: Sequence[float], descending: bool = True) -> "list[float]":
|
|
14
|
+
"""Return 1-based ranks for a sequence of scores.
|
|
15
|
+
|
|
16
|
+
With ``descending=True`` (the default) the largest score receives
|
|
17
|
+
rank 1, matching the convention "best scenario first". Ties are
|
|
18
|
+
assigned the average of the ranks they span.
|
|
19
|
+
|
|
20
|
+
>>> rank_vector([3.0, 1.0, 2.0])
|
|
21
|
+
[1.0, 3.0, 2.0]
|
|
22
|
+
>>> rank_vector([2.0, 2.0, 1.0])
|
|
23
|
+
[1.5, 1.5, 3.0]
|
|
24
|
+
"""
|
|
25
|
+
n = len(scores)
|
|
26
|
+
indexed = sorted(range(n), key=lambda i: scores[i], reverse=descending)
|
|
27
|
+
ranks = [0.0] * n
|
|
28
|
+
i = 0
|
|
29
|
+
while i < n:
|
|
30
|
+
j = i
|
|
31
|
+
while j + 1 < n and scores[indexed[j + 1]] == scores[indexed[i]]:
|
|
32
|
+
j += 1
|
|
33
|
+
avg = (i + 1 + j + 1) / 2.0
|
|
34
|
+
for k in range(i, j + 1):
|
|
35
|
+
ranks[indexed[k]] = avg
|
|
36
|
+
i = j + 1
|
|
37
|
+
return ranks
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def rank_displacement(a: Sequence[float], b: Sequence[float]) -> float:
|
|
41
|
+
"""Sum of absolute rank differences between two rank vectors.
|
|
42
|
+
|
|
43
|
+
Zero when the rankings are identical; at most
|
|
44
|
+
:func:`max_displacement` for a complete reversal.
|
|
45
|
+
"""
|
|
46
|
+
if len(a) != len(b):
|
|
47
|
+
raise ValueError("rank vectors must have equal length")
|
|
48
|
+
return sum(abs(x - y) for x, y in zip(a, b))
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def max_displacement(n: int) -> float:
|
|
52
|
+
"""Maximum sum of absolute rank differences between two permutations
|
|
53
|
+
of ``n`` items, i.e. the displacement between a ranking and its exact
|
|
54
|
+
reversal: ``floor(n^2 / 2)``.
|
|
55
|
+
|
|
56
|
+
>>> max_displacement(4)
|
|
57
|
+
8.0
|
|
58
|
+
>>> max_displacement(5)
|
|
59
|
+
12.0
|
|
60
|
+
"""
|
|
61
|
+
if n < 1:
|
|
62
|
+
raise ValueError("n must be positive")
|
|
63
|
+
return float((n * n) // 2)
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def kendall_tau_distance(a: Sequence[float], b: Sequence[float]) -> float:
|
|
67
|
+
"""Kendall tau distance in [0, 1] between two rank vectors.
|
|
68
|
+
|
|
69
|
+
0 for identical orderings, 1 for exact reversal. Pairs tied in both
|
|
70
|
+
vectors are ignored; pairs tied in exactly one vector count as half a
|
|
71
|
+
discordance (tau-b style handling).
|
|
72
|
+
"""
|
|
73
|
+
if len(a) != len(b):
|
|
74
|
+
raise ValueError("rank vectors must have equal length")
|
|
75
|
+
n = len(a)
|
|
76
|
+
pairs = 0
|
|
77
|
+
discordant = 0.0
|
|
78
|
+
for i in range(n):
|
|
79
|
+
for j in range(i + 1, n):
|
|
80
|
+
da = a[j] - a[i]
|
|
81
|
+
db = b[j] - b[i]
|
|
82
|
+
if da == 0 and db == 0:
|
|
83
|
+
continue # tied in both: carries no ordering information
|
|
84
|
+
pairs += 1
|
|
85
|
+
if da == 0 or db == 0:
|
|
86
|
+
discordant += 0.5 # tied in exactly one
|
|
87
|
+
elif da * db < 0:
|
|
88
|
+
discordant += 1.0
|
|
89
|
+
return discordant / pairs if pairs else 0.0
|