rsplot 0.1.0__py3-none-any.whl

rsplot/results.py

@@ -0,0 +1,553 @@
+"""Structured result builder and emitter for agent-friendly output.
+
+Every CLI command writes a sidecar JSON file next to the output image
+({output}.json). The calling agent reads this file directly instead of
+parsing stdout.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    import geopandas as gpd
+
+    from rsplot.fnr import FnrResult
+    from rsplot.geo.boundaries import RegionInfo
+    from rsplot.readers import ProductInfo
+    from rsplot.readers.guokong import StationData
+
+
+# ---------------------------------------------------------------------------
+# Generic helpers
+# ---------------------------------------------------------------------------
+def _round(x: float, n: int = 2) -> float:
+    """Round, keeping NaN as None for JSON."""
+    if not np.isfinite(x):
+        return None  # type: ignore[return-value]
+    return round(float(x), n)
+
+
+def _basic_stats(values: np.ndarray, n: int = 2) -> dict[str, float]:
+    """min/max/mean/median + p10/p25/p75/p90 over finite values."""
+    finite = values[np.isfinite(values)]
+    if len(finite) == 0:
+        return {}
+    return {
+        "n": int(len(finite)),
+        "min": _round(np.min(finite), n),
+        "max": _round(np.max(finite), n),
+        "mean": _round(np.mean(finite), n),
+        "median": _round(np.median(finite), n),
+        "p10": _round(np.percentile(finite, 10), n),
+        "p25": _round(np.percentile(finite, 25), n),
+        "p75": _round(np.percentile(finite, 75), n),
+        "p90": _round(np.percentile(finite, 90), n),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Raster
+# ---------------------------------------------------------------------------
+def _grid_per_city_stats(
+    LON: np.ndarray,
+    LAT: np.ndarray,
+    grid: np.ndarray,
+    cities_gdf: gpd.GeoDataFrame,
+) -> list[dict[str, Any]]:
+    """Per-city aggregation on a gridded raster."""
+    from shapely.vectorized import contains
+
+    rows: list[dict[str, Any]] = []
+    for _, row in cities_gdf.iterrows():
+        mask = contains(row.geometry, LON, LAT)
+        sub = grid[mask]
+        finite = sub[np.isfinite(sub)]
+        if len(finite) == 0:
+            continue
+        rows.append(
+            {
+                "name": row["name"],
+                "n_pixels": int(len(finite)),
+                "mean": _round(np.mean(finite)),
+                "max": _round(np.max(finite)),
+                "min": _round(np.min(finite)),
+            }
+        )
+    rows.sort(key=lambda r: (r["mean"] is None, -(r["mean"] or 0)))
+    return rows
+
+
+def _top_hotspots(
+    LON: np.ndarray,
+    LAT: np.ndarray,
+    grid: np.ndarray,
+    cities_gdf: gpd.GeoDataFrame | None,
+    n: int = 5,
+) -> list[dict[str, Any]]:
+    """Top-N highest finite pixels, each tagged with its containing city."""
+    from shapely.geometry import Point
+
+    flat = grid.ravel()
+    lon_flat = LON.ravel()
+    lat_flat = LAT.ravel()
+    order = np.argsort(flat)[::-1]
+
+    hotspots: list[dict[str, Any]] = []
+    for i in order:
+        v = flat[i]
+        if not np.isfinite(v):
+            continue
+        lon, lat = float(lon_flat[i]), float(lat_flat[i])
+        nearest_city = None
+        if cities_gdf is not None and len(cities_gdf) > 0:
+            pt = Point(lon, lat)
+            hit = cities_gdf[cities_gdf.geometry.contains(pt)]
+            if len(hit) > 0:
+                nearest_city = hit.iloc[0]["name"]
+            else:
+                dists = cities_gdf.geometry.distance(pt)
+                nearest_city = cities_gdf.iloc[int(dists.argmin())]["name"]
+        hotspots.append(
+            {
+                "lon": round(lon, 3),
+                "lat": round(lat, 3),
+                "value": _round(v),
+                "city": nearest_city,
+            }
+        )
+        if len(hotspots) >= n:
+            break
+    return hotspots
+
+
+def build_raster_result(
+    *,
+    region: RegionInfo,
+    product: str,
+    date: str,
+    prod_info: ProductInfo,
+    LON: np.ndarray,
+    LAT: np.ndarray,
+    grid: np.ndarray,
+    swath_meta: dict[str, Any],
+    vmin: float,
+    vmax: float,
+    output: str,
+    window: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build the JSON sidecar payload for a raster run.
+
+    ``window`` is None for single-day runs and a dict (start/end/
+    n_days_requested/n_days_found/n_min/dates_failed/coverage_days) for
+    window-mean runs.
+    """
+    finite = grid[np.isfinite(grid)]
+    total = grid.size
+    coverage_pct = round(100 * len(finite) / total, 1) if total else 0.0
+
+    result: dict[str, Any] = {
+        "command": "raster",
+        "image": output,
+        "region": {
+            "name": region.name,
+            "level": region.level,
+            "extent": [round(x, 3) for x in region.extent],
+        },
+        "product": product,
+        "date": date,
+        "unit": prod_info.colorbar_label,
+        "vrange": {"vmin": _round(vmin), "vmax": _round(vmax)},
+        "swath": swath_meta,
+        "stats": {
+            "grid_shape": list(grid.shape),
+            "coverage_pct": coverage_pct,
+            **_basic_stats(grid),
+        },
+    }
+    if window is not None:
+        result["window"] = window
+
+    sub_gdf = region.sub_boundary_gdf
+    if sub_gdf is not None and len(sub_gdf) > 0:
+        result["spatial_summary"] = _grid_per_city_stats(LON, LAT, grid, sub_gdf)
+        result["hotspots"] = _top_hotspots(LON, LAT, grid, sub_gdf, n=5)
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Station
+# ---------------------------------------------------------------------------
+def _attribute_stations_to_cities(
+    lon: np.ndarray, lat: np.ndarray, cities_gdf: gpd.GeoDataFrame
+) -> np.ndarray:
+    """Return city name for each (lon, lat); empty string if none contain it."""
+    from shapely.geometry import Point
+
+    sindex = cities_gdf.sindex
+    out = np.empty(len(lon), dtype=object)
+    for i, (x, y) in enumerate(zip(lon, lat)):
+        if not (np.isfinite(x) and np.isfinite(y)):
+            out[i] = ""
+            continue
+        pt = Point(float(x), float(y))
+        city = ""
+        for idx in sindex.intersection((x, y, x, y)):
+            if cities_gdf.iloc[idx].geometry.contains(pt):
+                city = cities_gdf.iloc[idx]["name"]
+                break
+        out[i] = city
+    return out
+
+
+def _aqi_distribution(vals: np.ndarray) -> dict[str, int]:
+    bounds = [0, 50, 100, 150, 200, 300, 500]
+    labels = ["优", "良", "轻度", "中度", "重度", "严重"]
+    dist: dict[str, int] = {}
+    for i, label in enumerate(labels):
+        lo, hi = bounds[i], bounds[i + 1]
+        if i == 0:
+            m = (vals >= lo) & (vals <= hi)
+        else:
+            m = (vals > lo) & (vals <= hi)
+        dist[label] = int(m.sum())
+    dist["爆表"] = int((vals > 500).sum())
+    return dist
+
+
+def build_station_result(
+    *,
+    region: RegionInfo,
+    data: StationData,
+    datetime_str: str,
+    threshold: float | None,
+    unit: str,
+    cities_gdf: gpd.GeoDataFrame | None,
+    output: str,
+) -> dict[str, Any]:
+    valid = np.isfinite(data.values)
+    vals = data.values[valid]
+    lons = data.lon[valid]
+    lats = data.lat[valid]
+    ids = np.asarray(data.id)[valid]
+
+    result: dict[str, Any] = {
+        "command": "station",
+        "image": output,
+        "region": {
+            "name": region.name,
+            "level": region.level,
+            "extent": [round(x, 3) for x in region.extent],
+        },
+        "datetime": datetime_str,
+        "variable": data.var_name,
+        "unit": unit or None,
+        "threshold": threshold,
+        "n_stations": int(data.n_stations),
+        "n_valid": int(data.n_valid),
+        "stats": _basic_stats(vals),
+    }
+
+    station_cities = None
+    if cities_gdf is not None and len(cities_gdf) > 0 and len(vals) > 0:
+        station_cities = _attribute_stations_to_cities(lons, lats, cities_gdf)
+
+    # Exceedance summary
+    if threshold is not None and len(vals) > 0:
+        exceed_mask = vals > threshold
+        n_exceed = int(exceed_mask.sum())
+        top_idx = np.argsort(vals)[::-1]
+        top_stations: list[dict[str, Any]] = []
+        for i in top_idx:
+            if vals[i] <= threshold:
+                break
+            entry: dict[str, Any] = {
+                "id": str(ids[i]),
+                "value": _round(vals[i]),
+                "lon": round(float(lons[i]), 3),
+                "lat": round(float(lats[i]), 3),
+            }
+            if station_cities is not None:
+                entry["city"] = station_cities[i] or None
+            top_stations.append(entry)
+            if len(top_stations) >= 10:
+                break
+        result["exceedance"] = {
+            "count": n_exceed,
+            "rate_pct": round(100 * n_exceed / len(vals), 1),
+            "top_stations": top_stations,
+        }
+
+    # AQI discrete distribution
+    if data.var_name == "AQI" and len(vals) > 0:
+        result["aqi_distribution"] = _aqi_distribution(vals)
+
+    # Per-city ranking
+    if station_cities is not None and len(vals) > 0:
+        acc: dict[str, dict[str, Any]] = {}
+        for i in range(len(vals)):
+            c = station_cities[i]
+            if not c:
+                continue
+            s = acc.setdefault(c, {"values": [], "n_exceed": 0})
+            s["values"].append(float(vals[i]))
+            if threshold is not None and vals[i] > threshold:
+                s["n_exceed"] += 1
+        ranking = []
+        for city, s in acc.items():
+            arr = np.asarray(s["values"])
+            ranking.append(
+                {
+                    "city": city,
+                    "n_valid": len(arr),
+                    "mean": _round(np.mean(arr)),
+                    "max": _round(np.max(arr)),
+                    "n_exceed": s["n_exceed"],
+                }
+            )
+        ranking.sort(key=lambda r: (r["mean"] is None, -(r["mean"] or 0)))
+        result["city_ranking"] = ranking
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Overlay (raster + station combined)
+# ---------------------------------------------------------------------------
+def build_overlay_result(
+    *,
+    region: RegionInfo,
+    product: str,
+    date: str,
+    prod_info: ProductInfo,
+    LON: np.ndarray,
+    LAT: np.ndarray,
+    grid: np.ndarray,
+    swath_meta: dict[str, Any],
+    raster_vmin: float,
+    raster_vmax: float,
+    data: StationData,
+    datetime_str: str,
+    threshold: float | None,
+    unit: str,
+    cities_gdf: gpd.GeoDataFrame | None,
+    output: str,
+) -> dict[str, Any]:
+    """Combine raster + station results into a single JSON payload.
+
+    Nested under `raster` and `station` keys so agents can inspect either
+    layer independently. A shared `region`, `image`, and `datetime` sit
+    at the top level.
+    """
+    raster_block = build_raster_result(
+        region=region,
+        product=product,
+        date=date,
+        prod_info=prod_info,
+        LON=LON,
+        LAT=LAT,
+        grid=grid,
+        swath_meta=swath_meta,
+        vmin=raster_vmin,
+        vmax=raster_vmax,
+        output=output,
+    )
+    station_block = build_station_result(
+        region=region,
+        data=data,
+        datetime_str=datetime_str,
+        threshold=threshold,
+        unit=unit,
+        cities_gdf=cities_gdf,
+        output=output,
+    )
+
+    # Shared fields are promoted to the top level; strip them from the
+    # per-layer blocks so the structure stays flat and non-redundant.
+    shared_keys = ("command", "image", "region")
+    for key in shared_keys:
+        raster_block.pop(key, None)
+        station_block.pop(key, None)
+
+    return {
+        "command": "overlay",
+        "image": output,
+        "region": {
+            "name": region.name,
+            "level": region.level,
+            "extent": [round(x, 3) for x in region.extent],
+        },
+        "datetime": datetime_str,
+        "date": date,
+        "raster": raster_block,
+        "station": station_block,
+    }
+
+
+# ---------------------------------------------------------------------------
+# FNR (HCHO/NO2 regime)
+# ---------------------------------------------------------------------------
+def _fnr_per_city_stats(
+    LON: np.ndarray,
+    LAT: np.ndarray,
+    fnr: np.ndarray,
+    cities_gdf: gpd.GeoDataFrame,
+) -> list[dict[str, Any]]:
+    """Per-city mean FNR and dominant regime."""
+    from shapely.vectorized import contains
+
+    from rsplot.fnr import FNR_NOX_LIMIT, FNR_VOC_LIMIT
+
+    rows: list[dict[str, Any]] = []
+    for _, row in cities_gdf.iterrows():
+        mask = contains(row.geometry, LON, LAT)
+        sub = fnr[mask]
+        finite = sub[np.isfinite(sub)]
+        if len(finite) == 0:
+            continue
+        mean_fnr = float(np.mean(finite))
+        if mean_fnr < FNR_VOC_LIMIT:
+            regime = "voc_limited"
+        elif mean_fnr <= FNR_NOX_LIMIT:
+            regime = "transition"
+        else:
+            regime = "nox_limited"
+        rows.append(
+            {
+                "name": row["name"],
+                "n_pixels": int(len(finite)),
+                "mean_fnr": _round(mean_fnr),
+                "median_fnr": _round(np.median(finite)),
+                "regime": regime,
+                "voc_limited_pct": round(
+                    100 * float((finite < FNR_VOC_LIMIT).mean()), 1
+                ),
+                "nox_limited_pct": round(
+                    100 * float((finite > FNR_NOX_LIMIT).mean()), 1
+                ),
+            }
+        )
+    rows.sort(key=lambda r: (r["mean_fnr"] is None, r["mean_fnr"] or 1e9))
+    return rows
+
+
+def build_fnr_result(
+    *,
+    region: RegionInfo,
+    fnr_out: FnrResult,
+    res: float,
+    output: str,
+) -> dict[str, Any]:
+    """Build the JSON sidecar for an FNR run."""
+    from rsplot.fnr import (
+        FNR_DISPLAY_MAX,
+        FNR_NOX_LIMIT,
+        FNR_VOC_LIMIT,
+        regime_percentages,
+    )
+
+    fnr = fnr_out.fnr
+    finite = fnr[np.isfinite(fnr)]
+
+    # Per-pixel coverage histogram: how many of the requested days had
+    # both NO2 and HCHO valid?
+    from shapely.vectorized import contains
+
+    region_mask = contains(region.geometry, fnr_out.LON, fnr_out.LAT)
+    total_region_pixels = int(region_mask.sum())
+    n_valid_fnr = int(np.isfinite(fnr).sum())
+    coverage_pct = (
+        round(100 * n_valid_fnr / total_region_pixels, 3)
+        if total_region_pixels
+        else 0.0
+    )
+    both_valid_days = np.minimum(fnr_out.n_valid_hcho, fnr_out.n_valid_no2)
+    covered = both_valid_days[(both_valid_days > 0) & region_mask]
+    coverage_days = {
+        "min": int(covered.min()) if len(covered) else 0,
+        "max": int(covered.max()) if len(covered) else 0,
+        "mean": round(float(covered.mean()), 1) if len(covered) else 0.0,
+    }
+    diagnostic_masks = {
+        name: mask & region_mask
+        for name, mask in fnr_out.diagnostic_masks.items()
+    }
+    mask_diagnostics = {
+        "total_region_pixels": total_region_pixels,
+        "coverage_ge_n_min_pixels": int(
+            diagnostic_masks["coverage_ok"].sum()
+        ),
+        "no2_ge_threshold_pixels": int(diagnostic_masks["no2_ok"].sum()),
+        "hcho_nonnegative_pixels": int(diagnostic_masks["hcho_ok"].sum()),
+        "final_valid_pixels": n_valid_fnr,
+    }
+
+    result: dict[str, Any] = {
+        "command": "fnr",
+        "image": output,
+        "region": {
+            "name": region.name,
+            "level": region.level,
+            "extent": [round(x, 3) for x in region.extent],
+        },
+        "window": {
+            "start": fnr_out.dates_requested[0],
+            "end": fnr_out.dates_requested[-1],
+            "n_days_requested": len(fnr_out.dates_requested),
+            "n_days_found_no2": len(fnr_out.dates_found_no2),
+            "n_days_found_hcho": len(fnr_out.dates_found_hcho),
+            "dates_failed_no2": fnr_out.dates_failed_no2,
+            "dates_failed_hcho": fnr_out.dates_failed_hcho,
+        },
+        "params": {
+            "n_min": fnr_out.n_min,
+            "no2_min_column": fnr_out.no2_min_column,
+            "voc_threshold": FNR_VOC_LIMIT,
+            "nox_threshold": FNR_NOX_LIMIT,
+            "display_max": FNR_DISPLAY_MAX,
+            "resolution_deg": res,
+        },
+        "stats": {
+            "grid_shape": list(fnr.shape),
+            "coverage_pct": coverage_pct,
+            "valid_pixels": n_valid_fnr,
+            "total_region_pixels": total_region_pixels,
+            "coverage_days": coverage_days,
+            "mask_diagnostics": mask_diagnostics,
+            **_basic_stats(fnr),
+        },
+        "regime_pct": regime_percentages(fnr),
+        "mean_fields": {
+            "hcho_mean_raw_stats": _basic_stats(fnr_out.hcho_mean),
+            "no2_mean_raw_stats": _basic_stats(fnr_out.no2_mean),
+            "hcho_mean_filled_stats": _basic_stats(fnr_out.hcho_mean_filled),
+            "no2_mean_filled_stats": _basic_stats(fnr_out.no2_mean_filled),
+        },
+    }
+
+    sub_gdf = region.sub_boundary_gdf
+    if sub_gdf is not None and len(sub_gdf) > 0:
+        result["city_ranking"] = _fnr_per_city_stats(
+            fnr_out.LON, fnr_out.LAT, fnr, sub_gdf
+        )
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Emission
+# ---------------------------------------------------------------------------
+def emit_result(result: dict[str, Any], image_path: str) -> str:
+    """Write {image}.json sidecar. Return sidecar path."""
+    sidecar = str(Path(image_path).with_suffix(".json"))
+    result["sidecar"] = sidecar
+
+    with open(sidecar, "w", encoding="utf-8") as f:
+        json.dump(result, f, ensure_ascii=False, indent=2)
+
+    return sidecar

rsplot/tiles/__init__.py

@@ -0,0 +1 @@
+"""Basemap tile providers."""

rsplot/tiles/tianditu.py

@@ -0,0 +1,32 @@
+"""TianDiTu (天地图) tile provider for cartopy.
+
+Supports satellite imagery (img), vector (vec), and terrain (ter) layers.
+Requires an API key from https://www.tianditu.gov.cn.
+"""
+
+from __future__ import annotations
+
+import cartopy.io.img_tiles as cimgt
+
+
+class TianDiTuTiles(cimgt.GoogleTiles):
+    """天地图卫星影像瓦片（球面墨卡托投影）。
+
+    Parameters
+    ----------
+    tk : TianDiTu API key.
+    layer : "img" (satellite), "vec" (vector), "ter" (terrain).
+    """
+
+    def __init__(self, tk: str, layer: str = "img"):
+        self.tk = tk
+        self.layer = layer
+        super().__init__()
+
+    def _image_url(self, tile):
+        x, y, z = tile
+        server = (x + y) % 8
+        return (
+            f"http://t{server}.tianditu.gov.cn/DataServer"
+            f"?T={self.layer}_w&x={x}&y={y}&l={z}&tk={self.tk}"
+        )