{ "version": "1.3.0", "formula": { "total_score": "Σ(dimension_score × dimension_weight)", "explanation": "Weighted sum of 7 dimension scores. Weights sum to 1.0. Max possible = 100.", "max_possible": 100, "scoping_rule": "Coverage is capacity-weighted: it measures what share of the country's national reservoir storage capacity (Mm³) is publicly trackable. The other six quality dimensions describe the covered subset.", "weights_rationale": "Coverage is the most heavily weighted (30%) because it bounds everything else — a country cannot have good data on water it does not publicly report.", "dimensions": { "coverage": { "weight": 0.30, "scope": "All national reservoir storage capacity", "formula": "score = round(100 × covered_capacity_hm³ / total_national_capacity_hm³)", "notes": "Linear, capacity-weighted. Use ICOLD, AQUASTAT, or national dam-authority totals for the denominator. The numerator is the summed capacity of reservoirs whose levels appear in any structured public data source." }, "data_availability": { "weight": 0.20, "scope": "Reservoirs whose capacity is counted in coverage", "formula": "Categorical band based on publication completeness/granularity, weighted by capacity", "bands_apply_to": "the typical (median by capacity) covered reservoir" }, "technical_accessibility": { "weight": 0.15, "scope": "Reservoirs whose capacity is counted in coverage", "formula": "Categorical band based on the dominant access mechanism (API > structured DL > scrapable HTML > PDF > image > none)", "bands_apply_to": "the primary publishing channel for the COVERED capacity" }, "historical_depth": { "weight": 0.125, "scope": "Reservoirs whose capacity is counted in coverage", "formula": "Categorical band on MEDIAN years of accessible history (weighted by capacity)", "important": "Score the median across the covered capacity, not the deepest single station." }, "update_frequency": { "weight": 0.10, "scope": "Reservoirs whose capacity is counted in coverage", "formula": "Categorical band on the typical refresh cadence weighted by capacity" }, "methodological_transparency": { "weight": 0.075, "scope": "Reservoirs whose capacity is counted in coverage", "formula": "Categorical band on documentation quality" }, "language_usability": { "weight": 0.05, "scope": "All published portals/APIs/bulletins (independent of coverage)", "formula": "Categorical band on language availability and UI modernity" } } }, "consistency_rules": [ "A country with covered_capacity = 0 cannot meaningfully score the quality dimensions; default these to 0 except language_usability.", "If a country has zero national reservoir storage capacity (no impoundments — Vatican, Tuvalu, Bahrain etc.), the country is flagged as structural N/A and the coverage dimension is undefined (treated as 0). The narrative field should make this explicit.", "Run-of-river plants contribute ~0 to both numerator and denominator and effectively cancel out.", "Multiplicative penalties are NOT applied; the weighted sum is the only aggregation. Coverage's influence on the total is capped at its 30% weight." ], "quick_reference": { "summary": "Plug the 7 scores into the weighted sum. Coverage is capacity-weighted (Mm³).", "weights_table": [ { "dimension": "coverage", "weight": "30%" }, { "dimension": "data_availability", "weight": "20%" }, { "dimension": "technical_accessibility", "weight": "15%" }, { "dimension": "historical_depth", "weight": "12.5%" }, { "dimension": "update_frequency", "weight": "10%" }, { "dimension": "methodological_transparency","weight": "7.5%" }, { "dimension": "language_usability", "weight": "5%" } ] }, "worked_examples": [ { "label": "Example 1 — Spain (real country, A- tier)", "story": "MITECO covers ~56,000 of ~57,000 Mm³ total national capacity. Weekly cadence. Proprietary .mdb format. Spanish only. 38 years of history.", "scores": { "coverage": 98, "data_availability": 92, "technical_accessibility": 45, "historical_depth": 100, "update_frequency": 75, "methodological_transparency": 72, "language_usability": 42 }, "calculation": "0.30×98 + 0.20×92 + 0.15×45 + 0.125×100 + 0.10×75 + 0.075×72 + 0.05×42", "total": "29.40 + 18.40 + 6.75 + 12.50 + 7.50 + 5.40 + 2.10 = 82.05", "grade": "A-", "lesson": "Comprehensive capacity coverage + deep history carries Spain to A-. Limited only by proprietary format and Spanish-only delivery." }, { "label": "Example 2 — Jamaica (real country, capacity-weighted recovery)", "story": "Country has only 2 reservoirs (Mona 3.67 + Hermitage 1.78 Mm³, total ~5.5 Mm³). Under the OLD >10 hm³ threshold, both fell below cutoff → coverage = 0. Under capacity-weighted: NWC publishes both weekly → coverage ≈ 100% of national storage.", "scores": { "coverage": 100, "data_availability": 52, "technical_accessibility": 18, "historical_depth": 22, "update_frequency": 48, "methodological_transparency": 28, "language_usability": 82 }, "calculation": "0.30×100 + 0.20×52 + 0.15×18 + 0.125×22 + 0.10×48 + 0.075×28 + 0.05×82", "total": "30.00 + 10.40 + 2.70 + 2.75 + 4.80 + 2.10 + 4.10 = 56.85", "grade": "C", "lesson": "Jamaica genuinely publishes its full reservoir stock weekly — the old methodology unfairly scored it 0 because both reservoirs were below 10 hm³. Capacity-weighting correctly recognises 'they publish everything they have'." }, { "label": "Example 3 — Hypothetical 'big country with weak coverage'", "story": "200,000 Mm³ total national capacity. Only 60,000 Mm³ is publicly reported, but those reservoirs have great APIs, 25 years history, daily updates.", "scores": { "coverage": 30, "data_availability": 90, "technical_accessibility": 95, "historical_depth": 100, "update_frequency": 90, "methodological_transparency": 95, "language_usability": 100 }, "calculation": "0.30×30 + 0.20×90 + 0.15×95 + 0.125×100 + 0.10×90 + 0.075×95 + 0.05×100", "total": "9.00 + 18.00 + 14.25 + 12.50 + 9.00 + 7.13 + 5.00 = 74.88", "grade": "B", "lesson": "Coverage gap costs ~21 points vs perfect. Even with world-class quality on what is published, a country with 30% capacity coverage cannot crack the A tier." }, { "label": "Example 4 — Hypothetical 'wide but shallow' country", "story": "All reservoirs reported, but only via monthly PDFs, 5 years of history, local language. Total national capacity = 50,000 Mm³, all publicly tracked.", "scores": { "coverage": 100, "data_availability": 50, "technical_accessibility": 40, "historical_depth": 65, "update_frequency": 50, "methodological_transparency": 40, "language_usability": 40 }, "calculation": "0.30×100 + 0.20×50 + 0.15×40 + 0.125×65 + 0.10×50 + 0.075×40 + 0.05×40", "total": "30.00 + 10.00 + 6.00 + 8.13 + 5.00 + 3.00 + 2.00 = 64.13", "grade": "B-", "lesson": "Comprehensive reporting in poor formats earns a meaningful B-. Coverage matters most, but quality of delivery is still ~65% of the total weight." }, { "label": "Example 5 — Structural N/A (no reservoirs)", "story": "Country has no surface reservoirs — entirely desalination/groundwater economy (Bahrain, Tuvalu, Vatican).", "scores": { "coverage": 0, "data_availability": 0, "technical_accessibility": 0, "historical_depth": 0, "update_frequency": 0, "methodological_transparency": 0, "language_usability": 60 }, "calculation": "Only language_usability contributes", "total": "0.05 × 60 = 3.00", "grade": "F", "lesson": "Structural N/A. Flag clearly in country narrative — this is not a governance failure, the country has no reservoirs to report." }, { "label": "Example 6 — Strategic withholding of dominant reservoir", "story": "Country has 200,000 Mm³ total capacity. One reservoir (160,000 Mm³, 80% of total) is treated as a state secret. The remaining 40,000 Mm³ across smaller reservoirs is reported monthly.", "scores": { "coverage": 20, "data_availability": 45, "technical_accessibility": 25, "historical_depth": 55, "update_frequency": 50, "methodological_transparency": 30, "language_usability": 25 }, "calculation": "0.30×20 + 0.20×45 + 0.15×25 + 0.125×55 + 0.10×50 + 0.075×30 + 0.05×25", "total": "6.00 + 9.00 + 3.75 + 6.88 + 5.00 + 2.25 + 1.25 = 34.13", "grade": "F", "lesson": "Capacity-weighted coverage CORRECTLY punishes hiding the biggest reservoir. Under count-based methodology, reporting 19 of 20 reservoirs scored 95% — but capacity-weighted shows the truth: 80% of the country's water is invisible." } ], "common_pitfalls": [ "DO NOT use count-based coverage (% of reservoirs above some threshold). Use capacity-weighted coverage (% of national storage Mm³).", "DO NOT score historical_depth = 100 because one station has 90 years. Score the MEDIAN across the covered capacity.", "DO NOT inflate technical_accessibility for paid/login-gated APIs. A documented but auth-gated REST API is at most 80, not 100.", "DO NOT count tweets, social media posts, or one-off press releases as 'data'. The data must be structured and recurrent.", "DO acknowledge structural N/A explicitly in the country narrative — these are not governance failures." ] }