model.json

{
  "_comment": "Single source of truth for GRIME's scoring model (Phase 5). scripts/check_model.py asserts the Python constants match this; keep them in sync.",
  "n_parameters": 27,
  "subscore_weights": {
    "generation": 0.3,
    "flow": 0.25,
    "impact": 0.3,
    "feasibility": 0.15
  },
  "parameter_weights": {
    "generation": {
      "population_density": 0.18,
      "impervious_pct": 0.2,
      "road_density_km_km2": 0.1,
      "tri_facility_density": 0.18,
      "npdes_points": 0.12,
      "cso_density": 0.12,
      "litter_complaint_density": 0.1
    },
    "flow": {
      "usgs_mean_q_cfs": 0.22,
      "flow_velocity_ms": 0.16,
      "stream_order": 0.14,
      "catchment_area_km2": 0.18,
      "flood_q10_cfs": 0.14,
      "seasonal_cv": 0.1,
      "runoff_coeff_C": 0.06
    },
    "impact": {
      "water_intake_score": 0.22,
      "protected_area_score": 0.16,
      "ej_index": 0.18,
      "estuary_dist_km": 0.14,
      "beach_dist_km": 0.12,
      "tourism_amenity_density": 0.1,
      "superfund_score": 0.08
    },
    "feasibility": {
      "road_access_score": 0.25,
      "channel_width_score": 0.2,
      "velocity_feasibility": 0.2,
      "land_ownership": 0.15,
      "bank_slope_score": 0.1,
      "bridge_proximity_bonus": 0.1
    }
  },
  "hard_gates": {
    "flow_velocity_ms_max": 3.0,
    "channel_width_m_min": 0.5,
    "channel_width_m_max": 50.0,
    "land_ownership_min_exclusive": 0.0,
    "note": "apply_hard_gates (core/scoring.py) is the gate in use: velocity strictly < 3.0 m/s, width inclusive [0.5, 50.0], ownership strictly > 0. A second helper, passes_hard_gates (core/feasibility.py), is defined but called by no entry point and differs only at exactly 3.0 m/s. Fix-pass-2 Phase 3 adds the navigability gate: candidates within navigable_waterway_min_distance_m of a USACE National Waterway Network segment are excluded (a stationary net on legally navigable water \u2014 Section 10 \u2014 is unsafe/illegal); rows with no NWN data (NaN) pass, matching the gates-fire-only-on-real-values convention.",
    "navigable_waterway_min_distance_m": 100.0
  },
  "spacing_m": {
    "pipeline_along_stream": 200,
    "explorer_same_stream": 500,
    "explorer_cross_stream": 300
  },
  "occlusion": {
    "catch_efficiency_eta": 0.65
  },
  "runoff_coefficient": {
    "formula": "C = intercept + slope * impervious_pct",
    "intercept": 0.05,
    "slope": 0.009,
    "min": 0.05,
    "max": 0.95
  },
  "curves": {
    "velocity_transport_favorability": {
      "formula": "exp(-((v - center) / width)^2)",
      "center": 0.9,
      "width": 0.6,
      "applies": "Flow sub-score only (M5): flow_velocity_ms is mapped through this peaked curve before MinMax normalization; the raw velocity still feeds velocity_feasibility and the hard gate.",
      "construct": "Transport/delivery favorability (does the flow deliver debris to the site) \u2014 deliberately distinct from curves.velocity_feasibility (can a device operate there). The same raw velocity is scored through both curves because they measure different things."
    },
    "velocity_feasibility": [
      {
        "v_lt": 0.05,
        "score": 0.3
      },
      {
        "v_lt": 0.3,
        "score": 0.7
      },
      {
        "v_le": 1.5,
        "score": 1.0
      },
      {
        "v_le": 2.5,
        "score": 0.5
      },
      {
        "else": 0.1
      }
    ],
    "channel_width_score": [
      {
        "w_lt": 0.5,
        "score": 0.0
      },
      {
        "w_lt": 2.0,
        "score": 0.5
      },
      {
        "w_le": 15.0,
        "score": 1.0
      },
      {
        "w_le": 30.0,
        "score": 0.5
      },
      {
        "w_le": 50.0,
        "score": 0.2
      },
      {
        "else": 0.0
      }
    ],
    "bank_slope_score": [
      {
        "slope_deg_lt": 15.0,
        "score": 1.0
      },
      {
        "slope_deg_lt": 30.0,
        "score": 0.5
      },
      {
        "slope_deg_lt": 45.0,
        "score": 0.2
      },
      {
        "else": 0.1
      }
    ]
  },
  "bank_slope_input": {
    "source": "NC OneMap / NC DPS DEM03 statewide lidar-derived elevation ImageServer",
    "source_url": "https://services.nconemap.gov/secure/rest/services/Elevation/DEM03/ImageServer",
    "source_resolution_ft": 3.125,
    "source_resolution_m": 0.9525,
    "source_crs_epsg": 6543,
    "profile_half_width_m": 25.0,
    "flow_direction_reach_m": 30.0,
    "center_search_m": 3.0,
    "rolling_run_m": 5.0,
    "bank_search_m": 20.0,
    "start_offset_m": 1.0,
    "side_aggregation": "mean of the steepest positive 5 m rise on each bank",
    "fallback": "Existing 10 m USGS 3DEP 3x3 DEM gradient when NC DEM03 samples are unavailable; non-NC regions retain this fallback.",
    "provenance_note": "USGS Seamless 1-m DEM coverage was verified incomplete in NC on 2026-07-12. DEM03 is the documented official-state-source fallback; it must not be labeled USGS 3DEP."
  },
  "width_order_fallback": {
    "formula": "min(40, 3.0 * order**1.1)"
  },
  "ej_index": {
    "source": "Census ACS (EJSCREEN demographic-index reconstruction)",
    "components": [
      "pct_low_income (C17002)",
      "pct_people_of_color (B03002)"
    ],
    "note": "EPA decommissioned EJSCREEN 2025-02-05"
  },
  "parameter_notes": {
    "_comment": "Status notes on parameters whose values are structurally constant or unpopulated in practice. The per-run varying/constant split is stamped into the output geojson's top-level 'provenance' block by scripts/score_candidates.py.",
    "bridge_proximity_bonus": "The flagship and region runners use FHWA/BTS National Bridge Inventory points with a 50 m proximity threshold. A confirmed complete empty inventory yields a real computed 0.0; a failed or truncated NBI query uses the documented 0.0 fallback, and the constant-column drop renormalizes its weight away.",
    "impervious_pct": "NLCD imperviousness is fetched as a whole-bbox raster mean, so it is identical for every candidate within a run by construction (fallback 35.0 when the fetch fails).",
    "runoff_coeff_C": "Derived from impervious_pct (C = 0.05 + 0.009*I), so it is constant whenever impervious_pct is.",
    "seasonal_cv": "Inverted in scoring: steadier flow scores higher.",
    "normalization": "Sub-scores MinMax-normalize each varying parameter within the candidate batch \u2014 including feasibility inputs that are already calibrated absolute [0,1] curve scores. Sub-scores are therefore batch-relative rankings, not absolute suitability values, and are not comparable across separately scored regions."
  },
  "proximity_curves": {
    "_comment": "Impact-side proximity curves made LIVE by the fix-pass-2 Phase 1 wiring (EPA SEMS, USGS PAD-US 4.1, NC DEQ SWAP). The curve shapes/constants are the ones shipped in core/*.py all along (science freeze) \u2014 this block documents them and check_model.py guards them functionally.",
    "superfund_score": {
      "formula": "sum over sites of 1 / (1 + (d_m / half_decay_m)^2)",
      "half_decay_m": 500.0,
      "source": "EPA DataMap SEMS (sems.envirofacts_site), non-archived georeferenced sites, state-filtered"
    },
    "cso_density": {
      "formula": "sum over sites of 1 / (1 + (d_m / half_decay_m)^2)",
      "half_decay_m": 500.0,
      "source": "EPA ECHO CSO inventory (national bulk), open CSO/TCS PF_LAT/PF_LON outfalls \u2014 same shared inverse-distance curve"
    },
    "litter_complaint_density": {
      "formula": "sum over complaints of 1 / (1 + (distance_to_catchment_m / half_decay_m)^2) / catchment_area_km2",
      "half_decay_m": 500.0,
      "sources": [
        "Charlotte ServiceRequests311: LITTER/DEBRIS IN STREET + DUMPING IN STREET/ROW",
        "Ask Raleigh Requests: REQUEST_TYPE=Litter",
        "Greensboro OpenData_CC_DS: 17-1 TW complaint-case archive joined to geocoded violations"
      ],
      "fallback": "0.0 where no public machine-readable litter/illegal-dumping feed exists or a configured feed is unavailable"
    },
    "protected_area_score": {
      "formula": "sum over intersecting areas of weight(designation) * 1/(1 + d_km/decay_km)",
      "buffer_km": 20.0,
      "decay_km": 5.0,
      "default_designation_weight": 0.2,
      "designation_weights": {
        "National Park": 1.0,
        "National Wildlife Refuge": 0.9,
        "Wilderness Area": 0.9,
        "State Park": 0.7,
        "State Wildlife": 0.6,
        "Local Park": 0.3
      },
      "source": "USGS PAD-US 4.1 state clip (local GDB preferred; official combined-inventory FeatureServer fallback), designation matched on d_Des_Tp/Des_Tp"
    },
    "water_intake_score": {
      "formula": "sum over intakes within max_dist_km of exp(-d_km / decay_km)",
      "max_dist_km": 50.0,
      "decay_km": 10.0,
      "source": "NC OneMap / NC DEQ SWAP public water supply sources, source_typ='Surface Water' (NC-only)"
    }
  },
  "flood_regressions": {
    "_comment": "USGS SIR 2014-5030 Table 7 10%-AEP (Q10) regional regression equations, applied only inside each region's calibration domain (regions.json flood_method). DA in mi2, IMP = % impervious, I24H50Y = NOAA Atlas 14 24-h/50-y depth (in). Blue Ridge (HR2) has NO urban equation in the report ('methods are not applicable to urban streams in the Blue Ridge region') and stays flood_method none.",
    "sir2014_hr1": {
      "small": "Q10 = 381*DA^0.7536 * 10^(0.0076*IMP)  (0.10 <= DA <= 3 mi2)",
      "large": "Q10 = 484*DA^0.5539 * 10^(0.0060*IMP)  (3 < DA <= 436 mi2)",
      "coeffs": {
        "small": [
          381.0,
          0.7536,
          0.0076
        ],
        "large": [
          484.0,
          0.5539,
          0.006
        ]
      }
    },
    "sir2014_hr4": {
      "equation": "Q10 = 51.8*DA^0.6004 * 10^(0.0101*IMP) * 10^(0.0666*I24H50Y)  (0.10 <= DA <= 53.5 mi2)",
      "coeffs": [
        51.8,
        0.6004,
        0.0101,
        0.0666
      ],
      "domain_mi2": [
        0.1,
        53.5
      ]
    }
  },
  "land_ownership": {
    "_comment": "Parcel owner-name -> land_ownership mapping (core/real_sources.py). Public 1.0, unknown 0.5; never 0.0 from ownership alone (0.0 would trip the hard gate). TOWN OF / VILLAGE OF are the fix-pass-2 statewide extension of the Durham-era hint list (same municipal-ownership construct).",
    "public_value": 1.0,
    "unknown_value": 0.5,
    "public_owner_hints": [
      "CITY OF",
      "COUNTY OF",
      "DURHAM CITY",
      "DURHAM COUNTY",
      "STATE OF",
      "NC DEPT",
      "NORTH CAROLINA",
      "UNITED STATES",
      "USA",
      "FEDERAL",
      "PARK",
      "RECREATION",
      "OPEN SPACE",
      "GREENWAY",
      "WATER",
      "SEWER",
      "UNIVERSITY",
      "SCHOOL",
      "BOARD OF EDUCATION",
      "HOUSING AUTHORITY",
      "TRANSIT",
      "DEPARTMENT OF",
      "US GOVERNMENT",
      "MUNICIPAL",
      "TOWN OF",
      "VILLAGE OF"
    ]
  }
}