waterledger-data 0.1.0__tar.gz

waterledger_data-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/

waterledger_data-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Northline Hydrology
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

waterledger_data-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.5
+Name: waterledger-data
+Version: 0.1.0
+Summary: Public U.S. water data for any place, fetched once and cached: Census places, EPA water systems and sewer plants, USGS watersheds, EPA ATTAINS, NOAA weather and design storms, EIA utilities
+Project-URL: Homepage, https://waterledger.org
+Project-URL: Source, https://github.com/northlinehydrology/waterledger
+Project-URL: Issues, https://github.com/northlinehydrology/waterledger/issues
+Author-email: Northline Hydrology <info@northlinehydrology.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pandas>=2.0
+Description-Content-Type: text/markdown
+
+# waterledger-data
+
+Public U.S. water data for any place, fetched once and cached, as used by [Water Ledger](https://waterledger.org):
+Census cities and townships, EPA water system service areas, USGS watersheds, EPA ATTAINS impaired waters, EPA ECHO and
+CWNS sewer plants, NOAA hourly weather and Atlas 14 design storms, and EIA electric utilities.
+
+Downloads are cached under `WATERLEDGER_CACHE` (default `~/.cache/waterledger`) or the `cache` path in a `waterledger.toml`.

waterledger_data-0.1.0/README.md

@@ -0,0 +1,7 @@
+# waterledger-data
+
+Public U.S. water data for any place, fetched once and cached, as used by [Water Ledger](https://waterledger.org):
+Census cities and townships, EPA water system service areas, USGS watersheds, EPA ATTAINS impaired waters, EPA ECHO and
+CWNS sewer plants, NOAA hourly weather and Atlas 14 design storms, and EIA electric utilities.
+
+Downloads are cached under `WATERLEDGER_CACHE` (default `~/.cache/waterledger`) or the `cache` path in a `waterledger.toml`.

waterledger_data-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "waterledger-data"
+version = "0.1.0"
+description = "Public U.S. water data for any place, fetched once and cached: Census places, EPA water systems and sewer plants, USGS watersheds, EPA ATTAINS, NOAA weather and design storms, EIA utilities"
+readme = "README.md"
+license = "BSD-3-Clause"
+authors = [{ name = "Northline Hydrology", email = "info@northlinehydrology.com" }]
+requires-python = ">=3.11"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Hydrology",
+]
+dependencies = ["numpy>=1.24", "pandas>=2.0", "matplotlib>=3.7", "openpyxl>=3.1"]
+
+[project.urls]
+Homepage = "https://waterledger.org"
+Source = "https://github.com/northlinehydrology/waterledger"
+Issues = "https://github.com/northlinehydrology/waterledger/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/waterledger_data"]

waterledger_data-0.1.0/src/waterledger_data/__init__.py

@@ -0,0 +1,19 @@
+"""Water Ledger data: public U.S. data for any place, fetched once and cached (see waterledger_data.config).
+
+    climate   hourly weather (ERA5 via Open-Meteo, NOAA ISD stations, NASA POWER) and NOAA Atlas 14 design storms
+    places    Census cities and townships, EPA water system service areas, USGS watersheds
+    waters    EPA ATTAINS impaired waters, ECHO and CWNS sewer plants, county rainfall, household wells
+    power     electric utility territories and EIA-861 loads
+
+Submodules load on first use, so `import waterledger_data` stays light.
+"""
+import importlib
+
+__version__ = "0.1.0"
+_SUB = ("climate", "config", "places", "power", "waters")
+
+
+def __getattr__(name):
+    if name in _SUB:
+        return importlib.import_module(f"waterledger_data.{name}")
+    raise AttributeError(name)

waterledger_data-0.1.0/src/waterledger_data/climate.py

@@ -0,0 +1,126 @@
+"""Public climate inputs for a site: hourly weather and NOAA Atlas 14 design-storm depths.
+
+Both are fetched once and cached under engine/data/raw/ (gitignored); rerunning reads the cache.
+"""
+import ast, json, os, re, urllib.request
+
+from waterledger_data.config import CACHE as RAW
+
+# Atlas 14 PFDS rows and columns, in the order the NOAA service returns them
+PF_DURATIONS = ["5-min", "10-min", "15-min", "30-min", "60-min", "2-hr", "3-hr", "6-hr", "12-hr", "24-hr",
+                "2-day", "3-day", "4-day", "7-day", "10-day", "20-day", "30-day", "45-day", "60-day"]
+PF_ARI = [1, 2, 5, 10, 25, 50, 100, 200, 500, 1000]
+
+
+def _fetch(url, path):
+    if not os.path.exists(path):
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with urllib.request.urlopen(url, timeout=300) as r, open(path, "wb") as f:
+            f.write(r.read())
+    return path
+
+
+def hourly_weather(lat, lon, start, end, name):
+    """Hourly 2 m air temperature (C) and relative humidity (%) from the Open-Meteo archive (ERA5 reanalysis).
+
+    Returns (times, temp_c, rh_pct) as lists. Reanalysis smooths local extremes slightly; a full engagement
+    cross-checks against NOAA ISD hourly observations at the nearest airport.
+    """
+    url = (f"https://archive-api.open-meteo.com/v1/archive?latitude={lat}&longitude={lon}&start_date={start}&end_date={end}"
+           "&hourly=temperature_2m,relative_humidity_2m&temperature_unit=celsius&timezone=America%2FDetroit")
+    with open(_fetch(url, os.path.join(RAW, f"openmeteo_{name}.json"))) as f:
+        h = json.load(f)["hourly"]
+    return h["time"], h["temperature_2m"], h["relative_humidity_2m"]
+
+
+POWER_HOURLY = "https://power.larc.nasa.gov/api/temporal/hourly/point"
+
+
+def power_hourly(lat, lon, name, first=2001, last=2024):
+    """Hourly 2 m air temperature (C) and relative humidity (%) from NASA POWER (MERRA-2 reanalysis, 0.5 x 0.625 degree), in local
+    standard time, for the states without a hand-built weather set. Free, with no daily quota, so every state can be covered;
+    fetched in 8-year pieces (the service's limit per request) and cached. Returns (times, temp_c, rh_pct) like hourly_weather."""
+    t, T, RH = [], [], []
+    for y0 in range(first, last + 1, 8):
+        y1 = min(y0 + 7, last)
+        url = (f"{POWER_HOURLY}?parameters=T2M,RH2M&community=RE&longitude={lon:.4f}&latitude={lat:.4f}"
+               f"&start={y0}0101&end={y1}1231&format=JSON&time-standard=LST")
+        with open(_fetch(url, os.path.join(RAW, "power_hourly", f"{name}_{y0}_{y1}.json"))) as f:
+            p = json.load(f)["properties"]["parameter"]
+        for k in p["T2M"]:
+            a, b = p["T2M"][k], p["RH2M"].get(k)
+            if a is None or b is None or a <= -900 or b <= -900:      # -999 marks missing source data
+                continue
+            t.append(f"{k[:4]}-{k[4:6]}-{k[6:8]}T{k[8:10]}:00")
+            T.append(a); RH.append(b)
+    return t, T, RH
+
+
+ISD_HISTORY = "https://www.ncei.noaa.gov/pub/data/noaa/isd-history.csv"
+ISD_LITE = "https://noaa-isd-pds.s3.amazonaws.com/isd-lite/data/{y}/{usaf}-{wban}-{y}.gz"
+
+
+def isd_stations(first=1995, last=2024):
+    """US weather stations in NOAA's Integrated Surface Database whose record spans first..last (mostly airports with a WBAN
+    number): [{id, name, state, lat, lon}]."""
+    import csv
+    path = _fetch(ISD_HISTORY, os.path.join(RAW, "isd", "isd-history.csv"))
+    out = []
+    for r in csv.DictReader(open(path)):
+        if r["CTRY"] != "US" or r["WBAN"] == "99999" or not r["LAT"] or not r["BEGIN"]:
+            continue
+        if r["BEGIN"] > f"{first}0101" or r["END"] < f"{last}1001":
+            continue
+        out.append({"id": f"{r['USAF']}-{r['WBAN']}", "name": r["STATION NAME"].title(), "state": r["STATE"],
+                    "lat": float(r["LAT"]), "lon": float(r["LON"])})
+    return out
+
+
+def isd_hourly(station, first=1995, last=2024, min_share=0.85):
+    """Hourly 2 m air temperature (C) and relative humidity (%) observed at an ISD station (ISD-Lite: hourly temperature and dew point),
+    in local standard time from the station's longitude, for the states without a hand-built weather set. Gaps up to 6 hours are
+    filled linearly and longer ones with the station's mean for that month and hour, so every day has 24 hours. Returns
+    (times, temp_c, rh_pct, share_observed), or None when fewer than `min_share` of hours were observed."""
+    import gzip
+    import numpy as np
+    import pandas as pd
+    usaf, wban = station["id"].split("-")
+    rows = []
+    for y in range(first, last + 1):
+        path = os.path.join(RAW, "isd", "lite", f"{station['id']}-{y}.gz")
+        try:
+            _fetch(ISD_LITE.format(y=y, usaf=usaf, wban=wban), path)
+        except Exception:
+            continue
+        with gzip.open(path, "rt") as f:
+            for ln in f:
+                p = ln.split()
+                t, d = int(p[4]), int(p[5])
+                if t != -9999 and d != -9999:
+                    rows.append((f"{p[0]}-{p[1]}-{p[2]} {p[3]}", t / 10, d / 10))
+    if not rows:
+        return None
+    df = pd.DataFrame(rows, columns=["t", "T", "Td"]).drop_duplicates("t")
+    df.index = pd.to_datetime(df.pop("t")) + pd.Timedelta(hours=round(station["lon"] / 15))     # UTC to local standard time
+    full = pd.date_range(f"{first}-01-01 00:00", f"{last}-12-31 23:00", freq="h")
+    df = df[~df.index.duplicated()].reindex(full)
+    share = float(df["T"].notna().mean())
+    if share < min_share:
+        return None
+    df = df.interpolate(limit=6, limit_area="inside")
+    clim = df.groupby([df.index.month, df.index.hour]).transform("mean")
+    df = df.fillna(clim)
+    a = lambda x: np.exp(17.625 * x / (243.04 + x))                       # Magnus form (Alduchov and Eskridge 1996)
+    rh = np.clip(100 * a(df["Td"].values) / a(df["T"].values), 1, 100)
+    return [i.strftime("%Y-%m-%dT%H:00") for i in df.index], df["T"].tolist(), rh.tolist(), share
+
+
+def atlas14_depths(lat, lon, name):
+    """NOAA Atlas 14 partial-duration precipitation depths (inches) as {duration: {ARI years: depth}}, plus metadata."""
+    url = (f"https://hdsc.nws.noaa.gov/cgi-bin/new/cgi_readH5.py?lat={lat:.4f}&lon={lon:.4f}"
+           "&type=pf&data=depth&units=english&series=pds")
+    with open(_fetch(url, os.path.join(RAW, f"noaa_pfds_{name}.txt"))) as f:
+        txt = f.read()
+    q = ast.literal_eval(re.search(r"quantiles = (\[.*?\]);", txt, re.S).group(1))
+    meta = dict(re.findall(r"^(volume|version|region) = '([^']*)';", txt, re.M))
+    return {d: {a: float(v) for a, v in zip(PF_ARI, row)} for d, row in zip(PF_DURATIONS, q)}, meta

waterledger_data-0.1.0/src/waterledger_data/config.py

@@ -0,0 +1,40 @@
+"""Where Water Ledger keeps its downloads and writes its site data, and other local paths.
+
+Resolved once, at import, from the first of:
+  1. environment variables: WATERLEDGER_CACHE, WATERLEDGER_SITE, and WATERLEDGER_<NAME> for any other setting;
+  2. a waterledger.toml in the working directory or a parent, whose [paths] table names them (relative to the file):
+         [paths]
+         cache = "data/raw"
+         site = "site"
+  3. defaults: ~/.cache/waterledger for downloads and ./site for the site.
+"""
+import os
+import tomllib
+
+
+def _find(start=None):
+    d = os.path.abspath(start or os.getcwd())
+    while True:
+        f = os.path.join(d, "waterledger.toml")
+        if os.path.exists(f):
+            return f
+        up = os.path.dirname(d)
+        if up == d:
+            return None
+        d = up
+
+
+CONFIG_FILE = _find()
+_paths = {}
+if CONFIG_FILE:
+    with open(CONFIG_FILE, "rb") as f:
+        _paths = {k: os.path.normpath(os.path.join(os.path.dirname(CONFIG_FILE), v)) for k, v in tomllib.load(f).get("paths", {}).items()}
+
+
+def setting(name, default=None):
+    """A path setting: WATERLEDGER_<NAME> in the environment, else waterledger.toml's [paths], else `default`."""
+    return os.environ.get("WATERLEDGER_" + name.upper()) or _paths.get(name) or default
+
+
+CACHE = setting("cache", os.path.join(os.path.expanduser("~"), ".cache", "waterledger"))
+SITE = setting("site", os.path.abspath("site"))

waterledger_data-0.1.0/src/waterledger_data/places.py

@@ -0,0 +1,237 @@
+"""Michigan municipalities and their public water context, cached under engine/data/raw/places/.
+
+Sources (all public):
+  Census TIGERweb   county subdivisions (every city and township) and counties
+  EPA               Community Water System Service Area Boundaries (reported or modeled), via ArcGIS REST
+  USGS              Watershed Boundary Dataset HUC12 and HUC8, via The National Map REST
+  NOAA              Atlas 14 precipitation frequency (24-hour depths), via the PFDS service
+"""
+import concurrent.futures as cf, json, os, time, urllib.parse, urllib.request
+
+import numpy as np
+
+from waterledger_data.config import CACHE
+from matplotlib.path import Path
+
+from waterledger_data.climate import atlas14_depths
+
+RAW = os.path.join(CACHE, "places")
+TIGER = "https://tigerweb.geo.census.gov/arcgis/rest/services/TIGERweb"
+EPA_SA = "https://services.arcgis.com/cJ9YHowT8TU7DUyn/arcgis/rest/services/Water_System_Boundaries/FeatureServer/0/query"
+WBD = "https://hydro.nationalmap.gov/arcgis/rest/services/wbd/MapServer"
+LSAD = {"25": "city", "44": "township", "49": "charter township"}
+
+
+def _get(url, params, retries=5, post=False):
+    data = urllib.parse.urlencode(params).encode() if post else None
+    q = url if post else url + "?" + urllib.parse.urlencode(params)
+    for i in range(retries):
+        try:
+            with urllib.request.urlopen(q, data=data, timeout=120) as r:
+                d = json.load(r)
+            if isinstance(d, dict) and "error" in d:
+                raise RuntimeError(str(d["error"])[:200])
+            return d
+        except Exception:
+            if i == retries - 1:
+                raise
+            time.sleep(3 * (i + 1))
+
+
+def _cached(name, fn):
+    path = os.path.join(RAW, name)
+    if os.path.exists(path):
+        with open(path) as f:
+            return json.load(f)
+    os.makedirs(RAW, exist_ok=True)
+    data = fn()
+    with open(path, "w") as f:
+        json.dump(data, f)
+    return data
+
+
+def counties():
+    def fetch():
+        d = _get(f"{TIGER}/State_County/MapServer/1/query", {"where": "STATE='26'", "outFields": "GEOID,NAME,BASENAME,COUNTY,INTPTLAT,INTPTLON",
+                                                            "returnGeometry": "true", "outSR": 4326, "maxAllowableOffset": 0.01, "geometryPrecision": 3, "f": "json"})
+        return [{"geoid": f["attributes"]["GEOID"], "name": f["attributes"]["BASENAME"], "lat": float(f["attributes"]["INTPTLAT"]),
+                 "lon": float(f["attributes"]["INTPTLON"]), "rings": f["geometry"]["rings"]} for f in d["features"]]
+    return _cached("counties.json", fetch)
+
+
+def municipalities():
+    def fetch():
+        d = _get(f"{TIGER}/Places_CouSub_ConCity_SubMCD/MapServer/1/query", {"where": "STATE='26'", "outFields": "GEOID,NAME,BASENAME,COUNTY,LSADC,INTPTLAT,INTPTLON,AREALAND",
+                                                                            "returnGeometry": "false", "resultRecordCount": 5000, "f": "json"})
+        out = []
+        for f in d["features"]:
+            a = f["attributes"]
+            if a["LSADC"] not in LSAD or not a["AREALAND"]:
+                continue
+            out.append({"geoid": a["GEOID"], "name": a["NAME"], "base": a["BASENAME"], "kind": LSAD[a["LSADC"]], "county_fips": "26" + a["COUNTY"],
+                        "lat": round(float(a["INTPTLAT"]), 4), "lon": round(float(a["INTPTLON"]), 4)})
+        return out
+    return _cached("municipalities.json", fetch)
+
+
+def boundaries(cnties):
+    """Generalized municipal boundary polygons (Census TIGERweb), fetched county by county."""
+    def fetch():
+        out = {}
+        for c in cnties:
+            d = _get(f"{TIGER}/Places_CouSub_ConCity_SubMCD/MapServer/1/query", {"where": f"STATE='26' AND COUNTY='{c['geoid'][2:]}'", "outFields": "GEOID",
+                                                                                "returnGeometry": "true", "outSR": 4326, "maxAllowableOffset": 0.002, "geometryPrecision": 4, "f": "json"})
+            for f in d["features"]:
+                out[f["attributes"]["GEOID"]] = f["geometry"]["rings"]
+        return out
+    return _cached("boundaries.json", fetch)
+
+
+def _poly(rings):
+    return json.dumps({"rings": rings, "spatialReference": {"wkid": 4326}})
+
+
+def _inside(x, y, rings):
+    c = False
+    for ring in rings:
+        n = len(ring)
+        for i in range(n):
+            x1, y1 = ring[i][0], ring[i][1]
+            x2, y2 = ring[(i + 1) % n][0], ring[(i + 1) % n][1]
+            if (y1 > y) != (y2 > y) and x < (x2 - x1) * (y - y1) / (y2 - y1) + x1:
+                c = not c
+    return c
+
+
+def _inside_many(pts, rings):
+    """Even-odd point-in-polygon for many points at once (holes and multipart rings handled by parity)."""
+    pts = np.asarray(pts, dtype=float)
+    hits = np.zeros(len(pts), dtype=int)
+    for ring in rings:
+        if len(ring) >= 3:
+            hits += Path(np.asarray(ring, dtype=float)[:, :2]).contains_points(pts)
+    return hits % 2 == 1
+
+
+def _samples(rings, n=24):
+    xs = [p[0] for r in rings for p in r]
+    ys = [p[1] for r in rings for p in r]
+    x0, x1, y0, y1 = min(xs), max(xs), min(ys), max(ys)
+    pts = [(x0 + (i + 0.5) * (x1 - x0) / n, y0 + (j + 0.5) * (y1 - y0) / n) for i in range(n) for j in range(n)]
+    return [p for p, ok in zip(pts, _inside_many(pts, rings)) if ok]
+
+
+def _overlaps(url, rings, fields, extra_where=None):
+    params = {"geometry": _poly(rings), "geometryType": "esriGeometryPolygon", "inSR": 4326, "spatialRel": "esriSpatialRelIntersects",
+              "outFields": fields, "returnGeometry": "true", "outSR": 4326, "maxAllowableOffset": 0.002, "geometryPrecision": 4, "f": "json"}
+    if extra_where:
+        params["where"] = extra_where
+    d = _get(url, params, post=True)
+    pts = _samples(rings)
+    out = []
+    for f in d.get("features", []):
+        g = (f.get("geometry") or {}).get("rings")
+        if not g or not pts:
+            continue
+        share = _inside_many(pts, g).mean()
+        if share >= 0.05:
+            out.append((float(share), f["attributes"]))
+    out.sort(key=lambda t: -t[0])
+    return out
+
+
+def _water_systems(rings):
+    """Community water systems serving the municipality, with the share of its area each service area covers (EPA; reported or modeled boundaries)."""
+    rows = _overlaps(EPA_SA, rings, "PWSID,PWS_Name,Population_Served_Count,Service_Connections_Count,Data_Provider_Type", "PWSID LIKE 'MI%'")
+    return [{"pwsid": a["PWSID"], "name": a["PWS_Name"], "pop": a.get("Population_Served_Count"), "connections": a.get("Service_Connections_Count"),
+             "boundary": a.get("Data_Provider_Type"), "share": round(sh, 2)} for sh, a in rows[:4]]
+
+
+MI_ENVELOPE = "-90.5,41.6,-82.1,48.4"
+
+
+def _layer_polys(layer, fields, name, page=500):
+    """Every WBD polygon in a layer that intersects Michigan, generalized, fetched in pages and cached."""
+    def fetch():
+        out, off = [], 0
+        while True:
+            d = _get(f"{WBD}/{layer}/query", {"where": "1=1", "geometry": MI_ENVELOPE, "geometryType": "esriGeometryEnvelope", "inSR": 4326,
+                                             "spatialRel": "esriSpatialRelIntersects", "outFields": fields, "returnGeometry": "true", "outSR": 4326,
+                                             "maxAllowableOffset": 0.002, "geometryPrecision": 4, "orderByFields": "OBJECTID",
+                                             "resultOffset": off, "resultRecordCount": page, "f": "json"}, post=True)
+            feats = d.get("features", [])
+            for f in feats:
+                if (f.get("geometry") or {}).get("rings"):
+                    out.append({**f["attributes"], "rings": f["geometry"]["rings"]})
+            print(name, len(out))
+            if len(feats) < page:
+                return out
+            off += page
+    polys = _cached(name, fetch)
+    for q in polys:
+        xs = [pt[0] for r in q["rings"] for pt in r]
+        ys = [pt[1] for r in q["rings"] for pt in r]
+        q["bbox"] = (min(xs), min(ys), max(xs), max(ys))
+    return polys
+
+
+def _local_shares(rings, polys, pts=None):
+    """Share of a municipality's sampled points inside each polygon (bounding boxes first), shares under 5% dropped."""
+    pts = pts if pts is not None else _samples(rings)
+    if not pts:
+        return []
+    x0, y0 = min(p[0] for p in pts), min(p[1] for p in pts)
+    x1, y1 = max(p[0] for p in pts), max(p[1] for p in pts)
+    out = []
+    for q in polys:
+        b = q["bbox"]
+        if b[0] > x1 or b[2] < x0 or b[1] > y1 or b[3] < y0:
+            continue
+        share = _inside_many(pts, q["rings"]).mean()
+        if share >= 0.05:
+            out.append((float(share), q))
+    out.sort(key=lambda t: -t[0])
+    return out
+
+
+def _watersheds(rings, lat, lon, h12, h8):
+    """HUC12 subwatersheds covering the municipality with their shares, and the HUC8 at its internal point (USGS WBD)."""
+    rows = _local_shares(rings, h12)
+    at = [q for q in h8 if q["bbox"][0] <= lon <= q["bbox"][2] and q["bbox"][1] <= lat <= q["bbox"][3] and _inside(lon, lat, q["rings"])]
+    return {"huc12": [{"code": q["huc12"], "name": q["name"], "share": round(sh, 2)} for sh, q in rows[:5]],
+            "huc8": {"code": at[0]["huc8"], "name": at[0]["name"]} if at else None}
+
+
+def enrich(munis, bounds, workers=8):
+    """Water systems (EPA query per place) and watersheds (local overlap with bulk USGS polygons) for each municipality. Cached per GEOID; safe to re-run."""
+    path = os.path.join(RAW, "enrich.json")
+    cache = json.load(open(path)) if os.path.exists(path) else {}
+    cache = {k: v for k, v in cache.items() if "error" not in v}
+    todo = [m for m in munis if m["geoid"] not in cache and m["geoid"] in bounds]
+    h12 = _layer_polys(6, "huc12,name", "wbd_huc12_mi.json")
+    h8 = _layer_polys(4, "huc8,name", "wbd_huc8_mi.json")
+
+    def one(m):
+        try:
+            rings = bounds[m["geoid"]]
+            return m["geoid"], {"water": _water_systems(rings), "watershed": _watersheds(rings, m["lat"], m["lon"], h12, h8)}
+        except Exception as e:
+            return m["geoid"], {"error": str(e)[:200]}
+
+    with cf.ThreadPoolExecutor(workers) as ex:
+        for i, (gid, res) in enumerate(ex.map(one, todo), 1):
+            cache[gid] = res
+            if i % 100 == 0:
+                json.dump(cache, open(path, "w"))
+                print("enriched", i, "of", len(todo))
+    json.dump(cache, open(path, "w"))
+    return cache
+
+
+def county_design_storms(cnties):
+    """NOAA Atlas 14 24-hour depths (2-, 10-, 100-year) at each county's internal point."""
+    out = {}
+    for c in cnties:
+        pf, meta = atlas14_depths(c["lat"], c["lon"], f"county_{c['geoid']}")
+        out[c["geoid"]] = {k: pf["24-hr"][k] for k in (2, 10, 100)}
+    return out

waterledger_data-0.1.0/src/waterledger_data/power.py

@@ -0,0 +1,133 @@
+"""Michigan electric utilities: who serves each place and how big each utility's load is, cached under engine/data/raw/power/.
+
+Sources (all public):
+  MPSC     Electric Utility Service Areas (Michigan Public Service Commission GIS hub): the territory of every investor-owned,
+           cooperative and municipal utility in Michigan, via ArcGIS REST
+  EIA-861  Annual Electric Power Industry Report: each utility's Michigan retail sales and customers (bundled plus
+           delivery-only; short-form filers included) and summer and winter peak demand (Operational Data)
+
+A place's utilities are the MPSC territories covering its sampled area, with the share each covers. The utility's size is
+its own customers' load, not where its power is generated: Michigan's utilities buy and sell through the MISO market.
+"""
+import glob, io, json, os, urllib.request, zipfile
+
+from waterledger_data import places as pl
+from waterledger_data.config import CACHE
+
+RAW = os.path.join(CACHE, "power")
+MPSC = "https://services3.arcgis.com/943LBv9FP414WfDO/arcgis/rest/services/ELECTRIC_UTILITY_SERVICE_AREA_MI_WFL1/FeatureServer/16/query"
+EIA861 = "https://www.eia.gov/electricity/data/eia861/zip/f861{year}.zip"
+
+# MPSC territory name -> EIA utility number (checked by hand against names and customer counts, Oct 2026)
+EIA_ID = {
+    "DTE Electric Company": 5109, "Consumers Energy Company": 4254, "Indiana Michigan Power Company": 9324, "Upper Peninsula Power Company": 19578,
+    "Upper Michigan Energy Resources Corporation": 60631, "Alpena Power Company": 392, "Northern States Power Company - Wisconsin": 13780,
+    "Great Lakes Energy Cooperative": 38084, "Cloverland Electric Cooperative": 3828, "Cherryland Electric Cooperative": 3436,
+    "Midwest Energy Cooperative": 12377, "Presque Isle Electric & Gas Cooperative": 15340, "Homeworks Tri-County Electric Cooperative": 19396,
+    "Thumb Electric Cooperative": 18895, "Alger Delta Cooperative Electric Association": 305, "Ontonagon County Rural Electrification Association": 14156,
+    "Bayfield Electric Cooperative": 1367, "Lansing Board of Water & Light": 10704, "Holland Board of Public Works": 8723,
+    "Bay City Electric Light & Power": 1366, "Marquette Board of Light and Power": 11701, "Grand Haven Board of Light & Power": 7483,
+    "Traverse City Light & Power": 19125, "Wyandotte Municipal Services": 21048, "City of South Haven": 17562, "City of Niles": 13604,
+    "Coldwater Board of Public Utilities": 3915, "City of Escanaba": 24558, "City of Sturgis": 18252, "Zeeland Board of Public Works": 21158,
+    "Hillsdale Board of Public Utilities": 8631, "City of Petoskey": 14867, "City of Marshall": 11713, "City of Charlevoix": 3384,
+    "City of Harbor Springs": 8083, "City of Chelsea": 3415, "City of Eaton Rapids": 5630, "Lowell Light & Power": 11268, "City of Dowagiac": 5343,
+    "City of Gladstone": 7265, "City of Portland": 15246, "City of Negaunee": 13352, "City of Norway": 13826, "City of St Louis": 17886,
+    "Village of Paw Paw": 14581, "City of Crystal Falls": 4604, "Village of Union City": 19432, "Village of Clinton": 3813,
+    "Village of Newberry": 13525, "City of Hart": 8205, "Sebewaing Light & Water": 16873, "City of Croswell": 4562, "Village of L'Anse": 10508,
+    "City of Wakefield": 19975, "Village of Baraga": 1196, "City of Stephenson": 18074, "Village of Daggett": 4792,
+}
+
+
+def _cached(name, fn):
+    path = os.path.join(RAW, name)
+    if not os.path.exists(path):
+        os.makedirs(RAW, exist_ok=True)
+        json.dump(fn(), open(path, "w"))
+    return json.load(open(path))
+
+
+def territories():
+    """MPSC service territories with generalized polygons."""
+    def fetch():
+        out, off = [], 0
+        while True:
+            d = pl._get(MPSC, {"where": "1=1", "outFields": "Name,Type,Customers,Counties_1", "returnGeometry": "true", "outSR": 4326,
+                               "maxAllowableOffset": 0.002, "geometryPrecision": 4, "resultOffset": off, "resultRecordCount": 100, "f": "json"})
+            for f in d.get("features", []):
+                a = f["attributes"]
+                out.append({"name": a["Name"].strip(), "type": a["Type"], "customers": a["Customers"], "counties": a["Counties_1"],
+                            "rings": (f.get("geometry") or {}).get("rings") or []})
+            if len(d.get("features", [])) < 100:
+                return out
+            off += 100
+    polys = _cached("mpsc_service_areas.json", fetch)
+    for q in polys:
+        xs = [p[0] for r in q["rings"] for p in r] or [0]
+        ys = [p[1] for r in q["rings"] for p in r] or [0]
+        q["bbox"] = (min(xs), min(ys), max(xs), max(ys))
+    return polys
+
+
+def eia_year():
+    """The newest EIA-861 year on disk."""
+    have = sorted(glob.glob(os.path.join(RAW, "eia861_[0-9][0-9][0-9][0-9]")))
+    if not have:
+        raise FileNotFoundError("No EIA-861 data in " + RAW + "; run `python -m engine.update --only eia861`")
+    return int(have[-1][-4:])
+
+
+def fetch_eia861(year):
+    """Download and unpack one year of EIA-861 (about 5 MB). EIA posts a year's final data the following fall."""
+    with urllib.request.urlopen(EIA861.format(year=year), timeout=300) as r:
+        z = zipfile.ZipFile(io.BytesIO(r.read()))
+    d = os.path.join(RAW, f"eia861_{year}")
+    os.makedirs(d, exist_ok=True)
+    for n in z.namelist():
+        if n.startswith(("Sales_Ult_Cust_", "Short_Form_", "Operational_Data_")):
+            open(os.path.join(d, os.path.basename(n)), "wb").write(z.read(n))
+    return d
+
+
+def utility_loads(year=None):
+    """{EIA id: {"mwh", "customers", "summer_mw", "winter_mw"}} for Michigan. Sales are bundled plus delivery-only customers (everyone on
+    the utility's wires); short-form filers report sales only. Peaks are Michigan-reported only (a multistate utility's Michigan peak is absent)."""
+    import pandas as pd
+    year = year or eia_year()
+    d = os.path.join(RAW, f"eia861_{year}")
+    s = pd.read_excel(os.path.join(d, f"Sales_Ult_Cust_{year}.xlsx"), header=None, skiprows=3).iloc[:, [1, 3, 6, -2, -1]]
+    s.columns = ["id", "part", "state", "mwh", "cust"]
+    num = lambda col: pd.to_numeric(col, errors="coerce")      # EIA marks withheld or missing values with '.' or '..'
+    s["mwh"], s["cust"] = num(s.mwh), num(s.cust)
+    s = s[(s.state == "MI") & s.part.isin(["A", "C"])].groupby("id")[["mwh", "cust"]].sum()
+    f = pd.read_excel(os.path.join(d, f"Short_Form_{year}.xlsx"))
+    f = f[f["State"] == "MI"].set_index("Utility Number")[["Total Sales (MWh)", "Total Customers"]]
+    f.columns = ["mwh", "cust"]
+    f["mwh"], f["cust"] = num(f.mwh), num(f.cust)
+    o = pd.read_excel(os.path.join(d, f"Operational_Data_{year}.xlsx"), header=None, skiprows=3).iloc[:, [1, 3, 6, 7]]
+    o.columns = ["id", "state", "summer", "winter"]
+    o["summer"], o["winter"] = num(o.summer), num(o.winter)
+    o = o[o.state == "MI"].set_index("id")
+    val = lambda v: float(v) if v == v and v is not None else None
+    out = {}
+    for uid, r in pd.concat([s, f]).iterrows():
+        if r.mwh != r.mwh:
+            continue
+        pk = o.loc[uid] if uid in o.index else None
+        out[int(uid)] = {"mwh": float(r.mwh), "customers": int(r.cust) if r.cust == r.cust else None,
+                         "summer_mw": val(pk.summer) if pk is not None else None, "winter_mw": val(pk.winter) if pk is not None else None}
+    return out
+
+
+def michigan_retail_mwh(year=None):
+    """All retail electricity sold in Michigan in a year: bundled sales plus energy-only (retail choice) sales, MWh."""
+    import pandas as pd
+    year = year or eia_year()
+    s = pd.read_excel(os.path.join(RAW, f"eia861_{year}", f"Sales_Ult_Cust_{year}.xlsx"), header=None, skiprows=3).iloc[:, [3, 6, -2]]
+    s.columns = ["part", "state", "mwh"]
+    s["mwh"] = pd.to_numeric(s.mwh, errors="coerce")
+    return float(s[(s.state == "MI") & s.part.isin(["A", "B"])].mwh.sum())
+
+
+def place_utilities(rings, polys):
+    """Utilities whose MPSC territory covers the place, with the share of its sampled area each covers (5% or more)."""
+    return [(round(sh, 2), q["name"]) for sh, q in pl._local_shares(rings, [q for q in polys if q["rings"]])]

waterledger_data-0.1.0/src/waterledger_data/waters.py

@@ -0,0 +1,353 @@
+"""Michigan receiving waters and sewer plants, cached under engine/data/raw/waters/.
+
+Sources (all public):
+  EPA ATTAINS        2026 Integrated Report assessment units and parameters for Michigan (EGLE's 303(d)/305(b) listings),
+                     via the ATTAINS_Assessment map service (no key needed)
+  USGS WBD           HUC12 downstream links (tohuc), via The National Map REST
+  NOAA NCEI          county annual precipitation, 1991-2020 mean (Climate at a Glance, nClimGrid)
+  EPA ECHO           Michigan sewer plants (POTWs): location, receiving water, combined sewer flag, last year's average flow
+"""
+import collections, functools, glob, json, os, re, urllib.parse, urllib.request
+
+from waterledger_data.config import CACHE
+
+RAW = os.path.join(CACHE, "waters")
+ATTAINS = "https://gispub.epa.gov/arcgis/rest/services/OW/ATTAINS_Assessment/MapServer"
+WBD6 = "https://hydro.nationalmap.gov/arcgis/rest/services/wbd/MapServer/6/query"
+ECHO = "https://echodata.epa.gov/echo/cwa_rest_services"
+
+# ATTAINS parameter groups -> plain groups. Runoff and wastewater can add to the first set; the "fish" group is legacy
+# contamination (mercury, PCBs, PFAS in fish tissue) that a new campus would not change much.
+GROUPS = {
+    "SEDIMENT": "sed", "TURBIDITY": "sed",
+    "CAUSE UNKNOWN - IMPAIRED BIOTA": "bio", "CAUSE UNKNOWN": "bio",
+    "NUTRIENTS": "nut", "ALGAL GROWTH": "nut", "NOXIOUS AQUATIC PLANTS": "nut",
+    "ORGANIC ENRICHMENT/OXYGEN DEPLETION": "do",
+    "PATHOGENS": "ecoli",
+    "TEMPERATURE": "temp",
+    "SALINITY/TOTAL DISSOLVED SOLIDS/CHLORIDES/SULFATES": "salt",
+    "HYDROLOGIC ALTERATION": "flow", "HABITAT ALTERATIONS": "flow",
+    "OIL AND GREASE": "oil",
+    "METALS (OTHER THAN MERCURY)": "metal", "PH/ACIDITY/CAUSTIC CONDITIONS": "metal",
+    "MERCURY": "fish", "POLYCHLORINATED BIPHENYLS (PCBS)": "fish", "PER- AND POLYFLUOROALKYL SUBSTANCES (PFAS)": "fish",
+    "DIOXINS": "fish", "PESTICIDES": "fish", "TOXIC ORGANICS": "fish", "TOTAL TOXICS": "fish",
+}
+LABELS = {
+    "sed": "Sediment", "bio": "Fish and stream insects in poor shape", "nut": "Phosphorus and algae", "do": "Low oxygen",
+    "ecoli": "Bacteria (E. coli)", "temp": "Water too warm", "salt": "Salt (chloride)", "flow": "Flow and habitat changes",
+    "oil": "Oil and grease", "metal": "Metals", "fish": "Chemicals in fish (mercury, PCBs, PFAS)",
+}
+ORDER = ["sed", "nut", "temp", "salt", "do", "bio", "flow", "ecoli", "oil", "metal", "fish"]
+
+
+def _get(url, params, timeout=180):
+    with urllib.request.urlopen(url + "?" + urllib.parse.urlencode(params), timeout=timeout) as r:
+        return json.load(r)
+
+
+def _paged(url, where, fields="*", page=2000):
+    rows, off = [], 0
+    while True:
+        d = _get(url, {"where": where, "outFields": fields, "returnGeometry": "false", "resultOffset": off,
+                       "resultRecordCount": page, "orderByFields": "OBJECTID" if "ATTAINS" in url else "huc12", "f": "json"})
+        rows += [f["attributes"] for f in d.get("features", [])]
+        if len(d.get("features", [])) < page:
+            return rows
+        off += page
+
+
+def _cached(name, fn):
+    path = os.path.join(RAW, name)
+    if not os.path.exists(path):
+        os.makedirs(RAW, exist_ok=True)
+        json.dump(fn(), open(path, "w"))
+    return json.load(open(path))
+
+
+def attains():
+    """Michigan assessment units (names, categories) and their parameters, 2026 cycle."""
+    aus = {}
+    for p in sorted(glob.glob(os.path.join(RAW, "attains_[012]_*.json"))):
+        for f in json.load(open(p))["features"]:
+            a = f["attributes"]
+            aus[a["assessmentunitidentifier"]] = {"name": a["assessmentunitname"], "cat": a["ircategory"], "cycle": a["reportingcycle"]}
+    if not aus:
+        for layer in (0, 1, 2):
+            for a in _paged(f"{ATTAINS}/{layer}/query", "state='MI'", "assessmentunitidentifier,assessmentunitname,ircategory,reportingcycle"):
+                aus[a["assessmentunitidentifier"]] = {"name": a["assessmentunitname"], "cat": a["ircategory"], "cycle": a["reportingcycle"]}
+    params = _cached("attains_table8_mi.json", lambda: _paged(f"{ATTAINS}/8/query", "organizationid='21MICH'"))
+    return aus, params
+
+
+@functools.lru_cache(None)
+def huc12_links():
+    return {r["huc12"]: r for r in _cached("wbd_huc12_tohuc_mi.json", lambda: _paged(WBD6, "states LIKE '%MI%'", "huc12,name,tohuc,hutype", 1000))}
+
+
+@functools.lru_cache(None)
+def county_precip():
+    def fetch():
+        out = {}
+        for i in range(1, 166, 2):
+            d = _get(f"https://www.ncei.noaa.gov/access/monitoring/climate-at-a-glance/county/time-series/MI-{i:03d}/pcp/12/12/1991-2020/data.json", {})
+            v = [x["value"] for x in d["data"].values()]
+            out[f"26{i:03d}"] = {"name": d["description"]["title"].split(",")[0], "annual_in": round(sum(v) / len(v), 2), "n": len(v)}
+        return {"source": "NOAA NCEI Climate at a Glance, county time series (nClimGrid), January-December precipitation, mean 1991-2020", "counties": out}
+    return {k: v["annual_in"] for k, v in _cached("noaa_county_precip_1991_2020.json", fetch)["counties"].items()}
+
+
+@functools.lru_cache(None)
+def by_huc12():
+    """Impairments of the waters in each HUC12 (assessment units whose ID carries that HUC12), with whether a TMDL covers each,
+    plus the downstream HUC12 so the client can follow the water. Returns {huc12: {"n": name, "t": tohuc, "i": [[group, tmdl, waters]]}}."""
+    aus, params = attains()
+    links = huc12_links()
+    found = collections.defaultdict(lambda: collections.defaultdict(lambda: {"tmdl": 0, "w": set()}))
+    recoded = recode_aus()
+    for r in params:
+        if r["parameterstatus"] not in ("Cause", "Observed effect"):
+            continue
+        g = GROUPS.get(r["parametergroupname"])
+        m = re.match(r"MI(\d{12})", r["assessmentunitidentifier"] or "")
+        if not g or not m:
+            continue
+        e = found[recoded.get(r["assessmentunitidentifier"], m.group(1))][g]
+        e["tmdl"] |= int(r["parametercategorycode"] == "4A")
+        name = aus.get(r["assessmentunitidentifier"], {}).get("name") or ""
+        if name and " in HUC " not in name:   # named lakes and rivers; generic "Rivers/Streams in HUC ..." units go unnamed
+            e["w"].add(name.title() if name.isupper() else name)
+    assessed = {recoded.get(a, re.match(r"MI(\d{12})", a).group(1)) for a, v in aus.items()
+                if re.match(r"MI(\d{12})", a) and not a.endswith(("-NA", "-NAL"))}
+    out = {}
+    for h, L in links.items():
+        rec = {"n": L["name"], "t": L["tohuc"] if L["tohuc"] in links else None, "a": int(h in assessed)}
+        if h in found:
+            rec["i"] = [[g, found[h][g]["tmdl"], sorted(found[h][g]["w"])[:3]] for g in ORDER if g in found[h]]
+        out[h] = rec
+    return out
+
+
+ECHO_COLS = "1,2,4,13,15,26,27,28,29,30,31,53,56,62,150,158,159,161,168,172,173,175,176,178,179"
+
+
+@functools.lru_cache(None)
+def potws():
+    """Michigan wastewater plants from EPA's Clean Watersheds Needs Survey 2022 (design flow, location; includes lagoons and plants that
+    discharge to groundwater under state permits), with last year's average reported flow, receiving water and combined-sewer status
+    from EPA ECHO where an NPDES permit matches. ECHO flows that don't fit the plant's design flow are dropped (unit errors are common)."""
+    import csv
+
+    def fetch():
+        q = _get(f"{ECHO}.get_facilities", {"output": "JSON", "p_st": "MI", "p_pcomp": "POT", "responseset": 1000})["Results"]["QueryID"]
+        return _get(f"{ECHO}.get_qid", {"output": "JSON", "qid": q, "pageno": 1, "responseset": 1000, "qcolumns": ECHO_COLS})["Results"]["Facilities"]
+    rows = _cached("echo_potw_mi.json", lambda: {"Results": {"Facilities": fetch()}})
+    rows = rows["Results"]["Facilities"] if isinstance(rows, dict) else rows
+    echo = {r["SourceID"]: r for r in rows if r["CWPPermitStatusDesc"] not in ("Terminated", "Expired")}
+    cwns_design_flows()   # downloads the CWNS tables if needed
+    for f in ("FACILITIES", "PHYSICAL_LOCATION"):
+        path = os.path.join(RAW, f"cwns2022_{f}.csv")
+        if not os.path.exists(path):
+            urllib.request.urlretrieve(f"{CWNS}/{f}.csv", path)
+    rd = lambda f: csv.DictReader(open(os.path.join(RAW, f"cwns2022_{f}.csv")))
+    fac = {r["CWNS_ID"]: r for r in rd("FACILITIES") if r["STATE_CODE"] == "MI" and r["INFRASTRUCTURE_TYPE"] == "Wastewater"}
+    flow = {r["CWNS_ID"]: float(r["CURRENT_DESIGN_FLOW"]) for r in rd("FLOW") if r["STATE_CODE"] == "MI" and r["FLOW_TYPE"] == "Total Flow" and r["CURRENT_DESIGN_FLOW"]}
+    loc = {r["CWNS_ID"]: r for r in rd("PHYSICAL_LOCATION") if r["STATE_CODE"] == "MI" and r["LATITUDE"]}
+    permits = collections.defaultdict(list)
+    for r in rd("FACILITY_PERMIT"):
+        if r["STATE_CODE"] == "MI":
+            permits[r["CWNS_ID"]].append(r["PERMIT_NUMBER"])
+    out = []
+    for cid, fr in fac.items():
+        if cid not in flow or cid not in loc:
+            continue
+        e = next((echo[pm] for pm in permits[cid] if pm in echo), None)
+        design = flow[cid]
+        f_echo = float(e["PastCalYrAverageFlow"]) if e and e["PastCalYrAverageFlow"] else None
+        if f_echo and not 0.1 <= f_echo / design <= 1.3:
+            f_echo = None
+        name = fr["FACILITY_NAME"].upper()
+        out.append({"id": (e or {}).get("SourceID") or (permits[cid] or [cid])[0], "name": name, "city": loc[cid]["CITY"],
+                    "lat": float(loc[cid]["LATITUDE"]), "lon": float(loc[cid]["LONGITUDE"]),
+                    "major": bool(e and e["CWPMajorMinorStatusFlag"] == "M"), "cso": bool(e and e["CWPCsoFlag"] == "Y"), "flow_mgd": f_echo, "design_mgd": design,
+                    "receiving": (e or {}).get("CWPStateWaterBodyName"), "huc12": (e or {}).get("RadWBDHuc12"),
+                    "lagoon": bool(re.search(r"LAGOON|WWSL|STABILIZATION", name))})
+    return out
+
+
+TROUT = "https://services3.arcgis.com/Jdnp1TjADvSDxMAX/ArcGIS/rest/services/DNRFisheriesTroutRegsOPENDATA/FeatureServer/0/query"
+
+
+@functools.lru_cache(None)
+def trout_by_huc12():
+    """Designated trout streams (coldwater under R 323.1100(7)) per HUC12: number of designated segments whose midpoint falls inside
+    the HUC12 and a few stream names. Michigan DNR's layer; it lists only streams classified by type, so it can miss some designated waters."""
+    from waterledger_data import places as pl
+
+    def fetch():
+        out, off = [], 0
+        while True:
+            d = _get(TROUT, {"where": "Designated=1 AND isActive=1", "outFields": "DNRName,StreamType", "outSR": 4326, "geometryPrecision": 4,
+                             "maxAllowableOffset": 0.002, "resultOffset": off, "resultRecordCount": 2000, "orderByFields": "OBJECTID", "f": "json"}, 300)
+            for f in d["features"]:
+                pts = [p for path in (f.get("geometry") or {}).get("paths", []) for p in path]
+                if pts:
+                    out.append({"name": f["attributes"]["DNRName"], "type": f["attributes"]["StreamType"], "mid": pts[len(pts) // 2], "len": len(pts)})
+            if len(d["features"]) < 2000:
+                return {"source": "Michigan DNR, Trout and Salmon Regulations Stream Main, Designated=1 and isActive=1; segment midpoints", "segments": out}
+            off += 2000
+    segs = _cached("mdnr_trout_streams_mid.json", fetch)["segments"]
+    polys = pl._layer_polys(6, "huc12,name", "wbd_huc12_mi.json")
+    out = {}
+    for s in segs:
+        x, y = s["mid"]
+        for q in polys:
+            b = q["bbox"]
+            if b[0] <= x <= b[2] and b[1] <= y <= b[3] and pl._inside(x, y, q["rings"]):
+                e = out.setdefault(q["huc12"], {"n": 0, "names": set()})
+                e["n"] += 1
+                if s["name"]:
+                    e["names"].add(s["name"])
+                break
+    return {h: {"n": e["n"], "names": sorted(e["names"])[:3]} for h, e in out.items()}
+
+
+CWNS = "https://www.hydroshare.org/resource/3dab07fd628a4af2ba812f038b1af89f/data/contents/2022"
+
+
+@functools.lru_cache(None)
+def cwns_design_flows():
+    """Current design flow (MGD) of Michigan wastewater plants by NPDES permit, EPA Clean Watersheds Needs Survey 2022
+    (HydroShare mirror, Hodson et al. 2026). CWNS has no actual flows."""
+    import csv
+    for f in ("FLOW", "FACILITY_PERMIT"):
+        path = os.path.join(RAW, f"cwns2022_{f}.csv")
+        if not os.path.exists(path):
+            urllib.request.urlretrieve(f"{CWNS}/{f}.csv", path)
+    total = {}
+    for r in csv.DictReader(open(os.path.join(RAW, "cwns2022_FLOW.csv"))):
+        if r["STATE_CODE"] == "MI" and r["FLOW_TYPE"] == "Total Flow" and r["CURRENT_DESIGN_FLOW"]:
+            total[r["CWNS_ID"]] = float(r["CURRENT_DESIGN_FLOW"])
+    out = {}
+    for r in csv.DictReader(open(os.path.join(RAW, "cwns2022_FACILITY_PERMIT.csv"))):
+        if r["STATE_CODE"] == "MI" and r["CWNS_ID"] in total and r["PERMIT_NUMBER"]:
+            out[r["PERMIT_NUMBER"]] = total[r["CWNS_ID"]]
+    return out
+
+
+def plant_name(n):
+    """'YCUA REGIONAL WWTP' -> 'YCUA Regional WWTP' (as on Water Ledger)."""
+    up = {"WWTP", "WRRF", "WWTF", "WTF", "WWSL", "STP", "RTB", "RTF", "CSO", "GLWA", "YCUA", "SCI"}
+    word = lambda w: w if w in up else ("County" if w == "CO" else w.capitalize())
+    return re.sub(r"[A-Za-z]+", lambda m: word(m.group(0).upper()), str(n).lower())
+
+
+def locate(lat, lon):
+    """HUC12 and county containing a point (USGS WBD, Census TIGERweb)."""
+    from waterledger_data import places as pl
+    h = next((q for q in pl._layer_polys(6, "huc12,name", "wbd_huc12_mi.json")
+              if q["bbox"][0] <= lon <= q["bbox"][2] and q["bbox"][1] <= lat <= q["bbox"][3] and pl._inside(lon, lat, q["rings"])), None)
+    c = next((c for c in pl.counties() if pl._inside(lon, lat, c["rings"])), None)
+    return {"huc12": h["huc12"] if h else None, "huc12_name": h["name"] if h else None,
+            "county_fips": c["geoid"] if c else None, "county": c["name"] if c else None}
+
+
+def downstream(huc12, hops=25):
+    """The HUC12s the water passes through, starting with the site's own: [{code, name, listings, trout}]."""
+    H, T = by_huc12(), trout_by_huc12()
+    out, h = [], huc12
+    while h and h in H and len(out) < hops:
+        out.append({"code": h, "name": H[h]["n"], "listings": H[h].get("i", []), "trout": T.get(h), "assessed": bool(H[h].get("a"))})
+        h = H[h]["t"]
+    return out
+
+
+def huc_name(n, cap=False):
+    """In a sentence, 'Headwaters Little Rabbit River' -> 'the headwaters of the Little Rabbit River' (same rule as wq.js hucName)."""
+    m = re.match(r"^Headwaters (.+)$", n or "")
+    s = (f"the headwaters of {'the ' if re.search(r'River$', m.group(1)) else ''}{m.group(1)}" if m
+         else f"the {n}" if n and re.search(r"River$", n) and "-" not in n else (n or ""))
+    return s[:1].upper() + s[1:] if cap else s
+
+
+def place_stem(name):
+    """'Gaines Charter Township' / 'Gaylord city' -> 'gaines' / 'gaylord', to match a plant's city."""
+    return re.sub(r"\s+(charter township|township|city)$", "", str(name).strip(), flags=re.I).lower()
+
+
+def nearest_plants(lat, lon, k=3, km=40, stem=None):
+    """Sewer plants for a place, as on Water Ledger: a plant in the place's own city or township first (any size), then the nearest
+    plants of 0.5 MGD design or more within km."""
+    import math
+    rows = []
+    for p in potws():
+        d = 6371 * math.acos(min(1, math.sin(math.radians(lat)) * math.sin(math.radians(p["lat"])) +
+                                 math.cos(math.radians(lat)) * math.cos(math.radians(p["lat"])) * math.cos(math.radians(p["lon"] - lon))))
+        own = bool(stem) and p["city"].lower() == stem
+        if (own and d <= km) or (d <= km and p["design_mgd"] >= 0.5):
+            rows.append({**p, "km": round(d, 1), "own": own})
+    return sorted(rows, key=lambda r: (not r["own"], r["km"]))[:k]
+
+
+@functools.lru_cache(None)
+def recode_aus():
+    """USGS recoded some Michigan HUC12s after EGLE assigned assessment-unit IDs (e.g. the Huron River moved from 0409 to 0410).
+    For units whose ID carries a code no longer in WBD, find the current HUC12 from the unit's own geometry (a middle vertex).
+    Returns {assessment unit ID: current HUC12}."""
+    def fetch():
+        links = huc12_links()
+        aus, _ = attains()
+        stale = sorted(a for a in aus if re.match(r"MI(\d{12})", a) and re.match(r"MI(\d{12})", a).group(1) not in links)
+        pts = {}
+        for layer in (0, 1, 2):
+            for i in range(0, len(stale), 100):
+                ids = ",".join(f"'{a}'" for a in stale[i:i + 100])
+                d = _get(f"{ATTAINS}/{layer}/query", {"where": f"assessmentunitidentifier IN ({ids})", "outFields": "assessmentunitidentifier",
+                                                      "returnGeometry": "true", "outSR": 4326, "maxAllowableOffset": 0.002, "geometryPrecision": 4, "f": "json"})
+                for f in d.get("features", []):
+                    g = f.get("geometry") or {}
+                    v = ([p for path in g.get("paths", []) for p in path] or [p for ring in g.get("rings", []) for p in ring]
+                         or ([[g["x"], g["y"]]] if "x" in g else []))
+                    if v:
+                        if g.get("rings"):
+                            v = [[sum(p[0] for p in v) / len(v), sum(p[1] for p in v) / len(v)]]
+                        pts[f["attributes"]["assessmentunitidentifier"]] = v[len(v) // 2]
+        return pts
+    pts = _cached("attains_stale_au_points.json", fetch)
+    from waterledger_data import places as pl
+    polys = pl._layer_polys(6, "huc12,name", "wbd_huc12_mi.json")
+    out = {}
+    for au, (x, y) in pts.items():
+        for q in polys:
+            b = q["bbox"]
+            if b[0] <= x <= b[2] and b[1] <= y <= b[3] and pl._inside(x, y, q["rings"]):
+                out[au] = q["huc12"]
+                break
+    return out
+
+
+WELLOGIC = "https://gisagoegle.state.mi.us/arcgis/rest/services/EGLE/DwOpenData/MapServer/3/query"
+
+
+@functools.lru_cache(None)
+def household_wells():
+    """Household wells logged in EGLE's Wellogic by county and township: how many draw from glacial deposits (drift) vs bedrock,
+    their average depth and static water level (ft). Returns {(county, township): {"drift": {...}, "rock": {...}}}."""
+    from waterledger_data import places as pl
+
+    def fetch():
+        out = []
+        for c in sorted({c["name"] for c in pl.counties()}):
+            stats = [{"statisticType": "count", "onStatisticField": "OBJECTID", "outStatisticFieldName": "n"},
+                     {"statisticType": "avg", "onStatisticField": "WELL_DEPTH", "outStatisticFieldName": "depth"},
+                     {"statisticType": "avg", "onStatisticField": "SWL", "outStatisticFieldName": "swl"}]
+            d = _get(WELLOGIC, {"where": f"COUNTY='{c}' AND WELL_TYPE='HOSHLD' AND AQ_TYPE IS NOT NULL", "outStatistics": json.dumps(stats),
+                                "groupByFieldsForStatistics": "TOWNSHIP,AQ_TYPE", "f": "json"}, 300)
+            out += [{"county": c, **f["attributes"]} for f in d.get("features", [])]
+        return out
+    out = {}
+    for r in _cached("wellogic_household_by_township.json", fetch):
+        if not r["TOWNSHIP"]:
+            continue
+        e = out.setdefault((r["county"], r["TOWNSHIP"].strip().lower()), {})
+        e[r["AQ_TYPE"].lower()] = {"n": r["n"], "depth": round(r["depth"] or 0), "swl": round(r["swl"]) if r["swl"] else None}
+    return out