mtrs-sdibca-toolkit 1.4.0__tar.gz

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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 MTRS Toolkit Project
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,178 @@
1
+ Metadata-Version: 2.4
2
+ Name: mtrs-sdibca-toolkit
3
+ Version: 1.4.0
4
+ Summary: Reference implementation of transport scenario ranking stability (MTRS) and staged-delay benefit-cost analysis (SDI-BCA)
5
+ License: MIT
6
+ Project-URL: Homepage, https://github.com/liuyanxi-2026/mtrs-toolkit
7
+ Project-URL: Documentation, https://github.com/liuyanxi-2026/mtrs-toolkit#readme
8
+ Project-URL: Repository, https://github.com/liuyanxi-2026/mtrs-toolkit
9
+ Keywords: transport,policy-analysis,ranking-stability,benefit-cost-analysis,uncertainty
10
+ Classifier: Development Status :: 5 - Production/Stable
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Scientific/Engineering
15
+ Requires-Python: >=3.9
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Dynamic: license-file
19
+
20
+ # MTRS / SDI-BCA Toolkit
21
+
22
+ Reference implementation of two transport policy analysis methods:
23
+
24
+ - **MTRS** — *Multivariate Transport Ranking Stability test*: assesses how
25
+ stable a ranking of transport policy scenarios is under uncertainty,
26
+ decomposes ranking instability into six sources, and evaluates three
27
+ reporting rules (stable / reversal / non-transferable).
28
+ - **SDI-BCA** — *Staged-Delay-Inclusive Benefit-Cost Analysis*: evaluates
29
+ staged transport programmes whose benefit streams depend on the
30
+ operational state of prerequisite stages, so delays propagate through
31
+ the programme's dependency graph.
32
+
33
+ The MTRS procedure is introduced in Research Report No. 212 (May 2024);
34
+ SDI-BCA in Research Report No. 231 (June 2025).
35
+
36
+ **Project website:** <https://github.com/liuyanxi-2026/mtrs-toolkit/> · **Latest release:** v1.4.0
37
+ (2026-03-20) · **License:** MIT
38
+
39
+ The toolkit is pure Python (standard library only, Python ≥ 3.9) with no
40
+ runtime dependencies.
41
+
42
+ ---
43
+
44
+ ## MTRS overview
45
+
46
+ **Input**
47
+
48
+ - a decision matrix (scenarios × indicators) scoring policy scenarios on
49
+ transport indicators,
50
+ - nominal indicator weights and benefit directions (higher/lower-better),
51
+ - an uncertainty specification describing the six uncertainty sources:
52
+ model structure, parameter, data-year, policy-mapping, indicator-weight,
53
+ and metropolitan-area structure.
54
+
55
+ **Output**
56
+
57
+ - the base scenario ranking,
58
+ - the stability score `S = 1 - D / D_max`, where `D` is the mean total rank
59
+ displacement over the uncertainty ensemble and `D_max = floor(n²/2)` the
60
+ largest possible displacement between two rankings of `n` scenarios,
61
+ - a six-source variance decomposition of ranking instability,
62
+ - the reversal probability of the top-ranked scenario,
63
+ - the cross-area transfer failure rate (from the area-structure source),
64
+ - a verdict and a text/JSON report.
65
+
66
+ **Reporting rules (default thresholds, configurable)**
67
+
68
+ | Rule | Condition |
69
+ | --- | --- |
70
+ | Reportable as stable | `S ≥ 0.80` and no reversal risk |
71
+ | Reversal risk | top-rank flip probability `> 0.10` |
72
+ | Transferable across areas | transfer failure rate `≤ 0.30` |
73
+
74
+ The headline verdict is `REVERSAL` when reversal risk is detected,
75
+ `NON-TRANSFERABLE` when the ranking fails the cross-area check (or the
76
+ stability threshold) and `STABLE` otherwise.
77
+
78
+ ## SDI-BCA overview
79
+
80
+ Stages form a directed dependency graph. A stage opens when its own
81
+ construction is complete **and** every prerequisite stage is operational
82
+ (plus an optional handover lag). A delay on one stage therefore
83
+ propagates to all downstream stages — the *staged-delay inclusive*
84
+ property. For a delay schedule, the toolkit reports:
85
+
86
+ - base and delayed NPV, BCR, PV of benefits and costs,
87
+ - `ΔNPV` and `ΔBCR`,
88
+ - marginal NPV contribution of each delayed stage,
89
+ - the **staged-delay interaction term** — the part of `ΔNPV` not
90
+ attributable to any single delay, capturing overlapping delays that
91
+ interact through the dependency graph.
92
+
93
+ Cash-flow convention: years are offsets from a base year; construction
94
+ cost accrues uniformly over the construction period; benefits accrue from
95
+ the opening year with an optional linear ramp-up; discounting is
96
+ end-of-year (`PV = Σ CF_t / (1+r)^t`).
97
+
98
+ ## Installation
99
+
100
+ ```bash
101
+ git clone https://github.com/liuyanxi-2026/mtrs-toolkit.git
102
+ cd mtrs-sdibca-toolkit
103
+ pip install . # optional: the packages also run from the source tree
104
+ ```
105
+
106
+ There are no third-party dependencies.
107
+
108
+ ## Quick start
109
+
110
+ ```python
111
+ from mtrs import MTRSAnalysis, UncertaintySpec, render_text_report
112
+
113
+ matrix = [
114
+ [78, 64, 55, 42, 38, 71],
115
+ [69, 58, 61, 30, 44, 64],
116
+ [58, 71, 66, 35, 36, 52],
117
+ [64, 45, 41, 22, 40, 57],
118
+ [40, 40, 40, 26, 30, 40],
119
+ ]
120
+ analysis = MTRSAnalysis(
121
+ matrix,
122
+ scenario_names=["Metro extension", "BRT network",
123
+ "Road pricing + transit", "TOD intensification", "Baseline"],
124
+ indicator_names=["accessibility", "emissions", "time saving",
125
+ "cost per trip", "safety", "ridership"],
126
+ weights=[0.20, 0.15, 0.25, 0.15, 0.10, 0.15],
127
+ directions=[1, 1, 1, -1, 1, 1], # cost per trip is lower-better
128
+ spec=UncertaintySpec(parameter={"sigma": 0.06}),
129
+ )
130
+ result = analysis.run(n_draws=1000, seed=42)
131
+ print(render_text_report(result))
132
+ ```
133
+
134
+ ```python
135
+ from sdibca import SDIBCAModel, Stage
136
+
137
+ stages = [
138
+ Stage("BRT corridor", 0, 2, annual_cost=40, annual_benefit=35, ramp_up=1.0),
139
+ Stage("Fare integration", 1, 1, annual_cost=8, annual_benefit=10,
140
+ ramp_up=0.5, handover_lag=0.5, depends_on=("BRT corridor",)),
141
+ Stage("LRT extension", 3, 3, annual_cost=55, annual_benefit=60,
142
+ ramp_up=1.5, depends_on=("BRT corridor", "Fare integration")),
143
+ ]
144
+ model = SDIBCAModel(stages, discount_rate=0.05, horizon=20)
145
+ result = model.analyse({"BRT corridor": 1.0})
146
+ print(result.base["npv"], result.delayed["npv"], result.delta_npv)
147
+ ```
148
+
149
+ ## Examples and tests
150
+
151
+ ```bash
152
+ python3 examples/mtrs_example.py # full CSV-driven assessment + JSON report
153
+ python3 examples/sdibca_example.py # staged-delay worked example
154
+ python3 -m unittest discover -s tests -v
155
+ ```
156
+
157
+ The `examples/data/` directory contains the CSV inputs used by the
158
+ worked examples (`mtrs/io.py` documents the CSV layouts).
159
+
160
+ ## Package layout
161
+
162
+ ```
163
+ mtrs/ MTRS: core engine, uncertainty generators, metrics,
164
+ CSV input helpers, report rendering
165
+ sdibca/ SDI-BCA: stage graph, delay propagation, discounting
166
+ examples/ worked examples with CSV data
167
+ tests/ unit tests (unittest, no external test deps)
168
+ ```
169
+
170
+ ## Reproducibility
171
+
172
+ All randomness flows from a single `seed` passed to `MTRSAnalysis.run()`.
173
+ Identical inputs and seed reproduce identical results; the example
174
+ scripts pin their seeds.
175
+
176
+ ## License
177
+
178
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,159 @@
1
+ # MTRS / SDI-BCA Toolkit
2
+
3
+ Reference implementation of two transport policy analysis methods:
4
+
5
+ - **MTRS** — *Multivariate Transport Ranking Stability test*: assesses how
6
+ stable a ranking of transport policy scenarios is under uncertainty,
7
+ decomposes ranking instability into six sources, and evaluates three
8
+ reporting rules (stable / reversal / non-transferable).
9
+ - **SDI-BCA** — *Staged-Delay-Inclusive Benefit-Cost Analysis*: evaluates
10
+ staged transport programmes whose benefit streams depend on the
11
+ operational state of prerequisite stages, so delays propagate through
12
+ the programme's dependency graph.
13
+
14
+ The MTRS procedure is introduced in Research Report No. 212 (May 2024);
15
+ SDI-BCA in Research Report No. 231 (June 2025).
16
+
17
+ **Project website:** <https://github.com/liuyanxi-2026/mtrs-toolkit/> · **Latest release:** v1.4.0
18
+ (2026-03-20) · **License:** MIT
19
+
20
+ The toolkit is pure Python (standard library only, Python ≥ 3.9) with no
21
+ runtime dependencies.
22
+
23
+ ---
24
+
25
+ ## MTRS overview
26
+
27
+ **Input**
28
+
29
+ - a decision matrix (scenarios × indicators) scoring policy scenarios on
30
+ transport indicators,
31
+ - nominal indicator weights and benefit directions (higher/lower-better),
32
+ - an uncertainty specification describing the six uncertainty sources:
33
+ model structure, parameter, data-year, policy-mapping, indicator-weight,
34
+ and metropolitan-area structure.
35
+
36
+ **Output**
37
+
38
+ - the base scenario ranking,
39
+ - the stability score `S = 1 - D / D_max`, where `D` is the mean total rank
40
+ displacement over the uncertainty ensemble and `D_max = floor(n²/2)` the
41
+ largest possible displacement between two rankings of `n` scenarios,
42
+ - a six-source variance decomposition of ranking instability,
43
+ - the reversal probability of the top-ranked scenario,
44
+ - the cross-area transfer failure rate (from the area-structure source),
45
+ - a verdict and a text/JSON report.
46
+
47
+ **Reporting rules (default thresholds, configurable)**
48
+
49
+ | Rule | Condition |
50
+ | --- | --- |
51
+ | Reportable as stable | `S ≥ 0.80` and no reversal risk |
52
+ | Reversal risk | top-rank flip probability `> 0.10` |
53
+ | Transferable across areas | transfer failure rate `≤ 0.30` |
54
+
55
+ The headline verdict is `REVERSAL` when reversal risk is detected,
56
+ `NON-TRANSFERABLE` when the ranking fails the cross-area check (or the
57
+ stability threshold) and `STABLE` otherwise.
58
+
59
+ ## SDI-BCA overview
60
+
61
+ Stages form a directed dependency graph. A stage opens when its own
62
+ construction is complete **and** every prerequisite stage is operational
63
+ (plus an optional handover lag). A delay on one stage therefore
64
+ propagates to all downstream stages — the *staged-delay inclusive*
65
+ property. For a delay schedule, the toolkit reports:
66
+
67
+ - base and delayed NPV, BCR, PV of benefits and costs,
68
+ - `ΔNPV` and `ΔBCR`,
69
+ - marginal NPV contribution of each delayed stage,
70
+ - the **staged-delay interaction term** — the part of `ΔNPV` not
71
+ attributable to any single delay, capturing overlapping delays that
72
+ interact through the dependency graph.
73
+
74
+ Cash-flow convention: years are offsets from a base year; construction
75
+ cost accrues uniformly over the construction period; benefits accrue from
76
+ the opening year with an optional linear ramp-up; discounting is
77
+ end-of-year (`PV = Σ CF_t / (1+r)^t`).
78
+
79
+ ## Installation
80
+
81
+ ```bash
82
+ git clone https://github.com/liuyanxi-2026/mtrs-toolkit.git
83
+ cd mtrs-sdibca-toolkit
84
+ pip install . # optional: the packages also run from the source tree
85
+ ```
86
+
87
+ There are no third-party dependencies.
88
+
89
+ ## Quick start
90
+
91
+ ```python
92
+ from mtrs import MTRSAnalysis, UncertaintySpec, render_text_report
93
+
94
+ matrix = [
95
+ [78, 64, 55, 42, 38, 71],
96
+ [69, 58, 61, 30, 44, 64],
97
+ [58, 71, 66, 35, 36, 52],
98
+ [64, 45, 41, 22, 40, 57],
99
+ [40, 40, 40, 26, 30, 40],
100
+ ]
101
+ analysis = MTRSAnalysis(
102
+ matrix,
103
+ scenario_names=["Metro extension", "BRT network",
104
+ "Road pricing + transit", "TOD intensification", "Baseline"],
105
+ indicator_names=["accessibility", "emissions", "time saving",
106
+ "cost per trip", "safety", "ridership"],
107
+ weights=[0.20, 0.15, 0.25, 0.15, 0.10, 0.15],
108
+ directions=[1, 1, 1, -1, 1, 1], # cost per trip is lower-better
109
+ spec=UncertaintySpec(parameter={"sigma": 0.06}),
110
+ )
111
+ result = analysis.run(n_draws=1000, seed=42)
112
+ print(render_text_report(result))
113
+ ```
114
+
115
+ ```python
116
+ from sdibca import SDIBCAModel, Stage
117
+
118
+ stages = [
119
+ Stage("BRT corridor", 0, 2, annual_cost=40, annual_benefit=35, ramp_up=1.0),
120
+ Stage("Fare integration", 1, 1, annual_cost=8, annual_benefit=10,
121
+ ramp_up=0.5, handover_lag=0.5, depends_on=("BRT corridor",)),
122
+ Stage("LRT extension", 3, 3, annual_cost=55, annual_benefit=60,
123
+ ramp_up=1.5, depends_on=("BRT corridor", "Fare integration")),
124
+ ]
125
+ model = SDIBCAModel(stages, discount_rate=0.05, horizon=20)
126
+ result = model.analyse({"BRT corridor": 1.0})
127
+ print(result.base["npv"], result.delayed["npv"], result.delta_npv)
128
+ ```
129
+
130
+ ## Examples and tests
131
+
132
+ ```bash
133
+ python3 examples/mtrs_example.py # full CSV-driven assessment + JSON report
134
+ python3 examples/sdibca_example.py # staged-delay worked example
135
+ python3 -m unittest discover -s tests -v
136
+ ```
137
+
138
+ The `examples/data/` directory contains the CSV inputs used by the
139
+ worked examples (`mtrs/io.py` documents the CSV layouts).
140
+
141
+ ## Package layout
142
+
143
+ ```
144
+ mtrs/ MTRS: core engine, uncertainty generators, metrics,
145
+ CSV input helpers, report rendering
146
+ sdibca/ SDI-BCA: stage graph, delay propagation, discounting
147
+ examples/ worked examples with CSV data
148
+ tests/ unit tests (unittest, no external test deps)
149
+ ```
150
+
151
+ ## Reproducibility
152
+
153
+ All randomness flows from a single `seed` passed to `MTRSAnalysis.run()`.
154
+ Identical inputs and seed reproduce identical results; the example
155
+ scripts pin their seeds.
156
+
157
+ ## License
158
+
159
+ MIT — see [LICENSE](LICENSE).
@@ -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
+ ]