rsplot 0.1.0__py3-none-any.whl

rsplot/config.py

@@ -0,0 +1,290 @@
+"""Configuration management for rsplot.
+
+# TODO: Loads defaults from ~/.config/rsplot/config.toml if present,
+CLI arguments override everything.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+# ---------------------------------------------------------------------------
+# Default paths
+# ---------------------------------------------------------------------------
+DEFAULT_DATA_DIRS: dict[str, str] = {
+    "no2": "/satellite/exports2/yaoyhu/NO2",
+    "o3": "/satellite/exports2/yaoyhu/O3",
+    "hcho": "/satellite/exports2/yaoyhu/HCHO",
+    "guokong": "/home/zzgsg/data/guokong_combine",
+}
+DEFAULT_GEOJSON_DIR = "/satellite/d4/yaoyhu/tiandi"
+DEFAULT_FONT_DIR = "/satellite/d4/yaoyhu/fonts"
+DEFAULT_TIANDITU_KEY = None
+
+
+CONFIG_PATH = Path.home() / ".config" / "rsplot" / "config.toml"
+
+
+# ---------------------------------------------------------------------------
+# Per-level default parameters
+# ---------------------------------------------------------------------------
+@dataclass
+class LevelParams:
+    """Plotting parameters derived from administrative level."""
+
+    res: float
+    basemap: bool
+    smooth_sigma: float | None
+    grid_step: float
+    pad: float
+    boundary_linewidth: float
+    label_fontsize: float
+    zoom: int  # TianDiTu tile zoom level
+
+
+LEVEL_DEFAULTS: dict[str, LevelParams] = {
+    "country": LevelParams(
+        res=0.1,
+        basemap=False,
+        smooth_sigma=None,
+        grid_step=5.0,
+        pad=0.5,
+        boundary_linewidth=0.5,
+        label_fontsize=6,
+        zoom=5,
+    ),
+    "key_region": LevelParams(
+        res=0.05,
+        basemap=False,
+        smooth_sigma=None,
+        grid_step=2.0,
+        pad=0.2,
+        boundary_linewidth=1.0,
+        label_fontsize=7,
+        zoom=7,
+    ),
+    "province": LevelParams(
+        res=0.05,
+        basemap=False,
+        smooth_sigma=None,
+        grid_step=1.0,
+        pad=0.15,
+        boundary_linewidth=0.8,
+        label_fontsize=7,
+        zoom=8,
+    ),
+    "city": LevelParams(
+        res=0.03,
+        basemap=True,
+        smooth_sigma=1.5,
+        grid_step=0.5,
+        pad=0.15,
+        boundary_linewidth=1.5,
+        label_fontsize=8,
+        zoom=10,
+    ),
+    "county": LevelParams(
+        res=0.01,
+        basemap=True,
+        smooth_sigma=1.5,
+        grid_step=0.2,
+        pad=0.05,
+        boundary_linewidth=1.5,
+        label_fontsize=9,
+        zoom=12,
+    ),
+}
+
+# ---------------------------------------------------------------------------
+# Preset key regions (province name lists)
+# ---------------------------------------------------------------------------
+DEFAULT_KEY_REGIONS: dict[str, list[str]] = {
+    "YRD": ["上海市", "江苏省", "浙江省", "安徽省"],
+    "长三角": ["上海市", "江苏省", "浙江省", "安徽省"],
+    "BTH": ["北京市", "天津市", "河北省"],
+    "京津冀": ["北京市", "天津市", "河北省"],
+    "PRD": [
+        "广州市",
+        "深圳市",
+        "珠海市",
+        "东莞市",
+        "中山市",
+        "江门市",
+        "惠州市",
+        "肇庆市",
+        "佛山市",
+    ],
+    "珠三角": [
+        "广州市",
+        "深圳市",
+        "珠海市",
+        "东莞市",
+        "中山市",
+        "江门市",
+        "惠州市",
+        "肇庆市",
+        "佛山市",
+    ],
+    "SCB": ["四川省", "重庆市"],
+    "成渝": ["四川省", "重庆市"],
+}
+
+
+# ---------------------------------------------------------------------------
+# Global app config
+# ---------------------------------------------------------------------------
+@dataclass
+class AppConfig:
+    """Merged configuration (file defaults + CLI overrides)."""
+
+    # paths (per-product data directories)
+    data_dirs: dict[str, str] = field(
+        default_factory=lambda: dict(DEFAULT_DATA_DIRS)
+    )
+    geojson_dir: str = DEFAULT_GEOJSON_DIR
+    font_dir: str = DEFAULT_FONT_DIR
+    tianditu_key: str | None = DEFAULT_TIANDITU_KEY
+
+    # plotting defaults
+    dpi: int = 300
+    qa_threshold: float = 0.5
+
+    # key regions
+    key_regions: dict[str, list[str]] = field(
+        default_factory=lambda: dict(DEFAULT_KEY_REGIONS)
+    )
+
+    @classmethod
+    def load(cls) -> AppConfig:
+        """Load config from TOML file, falling back to defaults."""
+        cfg = cls()
+        if CONFIG_PATH.exists():
+            with open(CONFIG_PATH, "rb") as f:
+                data = tomllib.load(f)
+            cfg._apply_toml(data)
+        # Environment variable overrides (per-product: RSPLOT_DATA_DIR_NO2, etc.)
+        for product in list(cfg.data_dirs):
+            env_key = f"RSPLOT_DATA_DIR_{product.upper()}"
+            if v := os.environ.get(env_key):
+                cfg.data_dirs[product] = v
+        if v := os.environ.get("RSPLOT_GEOJSON_DIR"):
+            cfg.geojson_dir = v
+        if v := os.environ.get("TIANDITU_API_KEY"):
+            cfg.tianditu_key = v
+        return cfg
+
+    def get_data_dir(self, product: str) -> str:
+        """Return data directory for a product, or raise if not configured."""
+        key = product.lower()
+        if key in self.data_dirs:
+            return self.data_dirs[key]
+        available = ", ".join(self.data_dirs)
+        raise ValueError(
+            f"No data directory configured for product '{product}'. "
+            f"Available: {available}"
+        )
+
+    def _apply_toml(self, data: dict[str, Any]) -> None:
+        paths = data.get("paths", {})
+        data_dirs = paths.get("data_dirs", {})
+        for product, dir_path in data_dirs.items():
+            self.data_dirs[product.lower()] = dir_path
+        if v := paths.get("geojson_dir"):
+            self.geojson_dir = v
+        if v := paths.get("font_dir"):
+            self.font_dir = v
+
+        td = data.get("tianditu", {})
+        if v := td.get("api_key"):
+            self.tianditu_key = v
+
+        defaults = data.get("defaults", {})
+        if v := defaults.get("dpi"):
+            self.dpi = int(v)
+        if v := defaults.get("qa_threshold"):
+            self.qa_threshold = float(v)
+
+        kr = data.get("key_regions", {})
+        for name, provinces in kr.items():
+            self.key_regions[name] = provinces
+
+
+# ---------------------------------------------------------------------------
+# GB 3095-2026 Air Quality Limits (transitional phase, grade II)
+# ---------------------------------------------------------------------------
+AQ_LIMITS_2026: dict[str, dict[str, float]] = {
+    "SO2": {"annual": 60, "daily": 150, "hourly": 500},
+    "NO2": {"annual": 40, "daily": 80, "hourly": 200},
+    "CO": {"daily": 4, "hourly": 10},
+    "O3": {"8h": 160, "hourly": 200},
+    "PM10": {"annual": 60, "daily": 120},
+    "PM2_5": {"annual": 30, "daily": 60},
+    "TSP": {"annual": 200, "daily": 300},
+    "NOx": {"annual": 40, "daily": 70, "hourly": 250},
+    "Pb": {"annual": 0.5, "seasonal": 1.0},
+    "BaP": {"annual": 0.001, "daily": 0.0025},
+}
+
+# ---------------------------------------------------------------------------
+# AQI Classification (official standard)
+# ---------------------------------------------------------------------------
+AQI_COLORS: list[tuple[int, str]] = [
+    # (upper bound, hex color)
+    (50, "#00e400"),   # 优 / green
+    (100, "#ffff00"),  # 良 / yellow
+    (150, "#ff7e00"),  # 轻度污染 / orange
+    (200, "#ff0000"),  # 中度污染 / red
+    (300, "#99004c"),  # 重度污染 / purple
+    (500, "#7e0023"),  # 严重污染 / maroon
+]
+
+AQI_EXCEEDANCE_THRESHOLD = 100  # AQI > 100 considered exceeding
+
+# ---------------------------------------------------------------------------
+# Station variable metadata: nc_name -> (unit, limit_key, limit_time)
+# limit_key maps into AQ_LIMITS_2026; limit_time selects which sub-key.
+# None means no standard exceedance check for this variable.
+# ---------------------------------------------------------------------------
+STATION_VAR_META: dict[str, tuple[str, str | None, str | None]] = {
+    "AQI": ("", None, None),
+    "PM2.5": ("ug/m3", None, None),
+    "PM2.5_24h": ("ug/m3", "PM2_5", "daily"),
+    "PM10": ("ug/m3", None, None),
+    "PM10_24h": ("ug/m3", "PM10", "daily"),
+    "SO2": ("ug/m3", "SO2", "hourly"),
+    "SO2_24h": ("ug/m3", "SO2", "daily"),
+    "NO2": ("ug/m3", "NO2", "hourly"),
+    "NO2_24h": ("ug/m3", "NO2", "daily"),
+    "O3": ("ug/m3", "O3", "hourly"),
+    "O3_24h": ("ug/m3", "O3", "hourly"),
+    "O3_8h": ("ug/m3", "O3", "8h"),
+    "O3_8h_24h": ("ug/m3", "O3", "8h"),
+    "CO": ("mg/m3", "CO", "hourly"),
+    "CO_24h": ("mg/m3", "CO", "daily"),
+}
+
+
+def get_exceedance_threshold(var_name: str) -> float | None:
+    """Return the exceedance threshold for a station variable, or None."""
+    if var_name == "AQI":
+        return AQI_EXCEEDANCE_THRESHOLD
+    meta = STATION_VAR_META.get(var_name)
+    if meta is None:
+        return None
+    _, limit_key, limit_time = meta
+    if limit_key is None or limit_time is None:
+        return None
+    limits = AQ_LIMITS_2026.get(limit_key)
+    if limits is None:
+        return None
+    return limits.get(limit_time)

rsplot/fnr.py

@@ -0,0 +1,384 @@
+"""FNR (Formaldehyde-to-NO2 Ratio) computation with temporal averaging.
+
+TROPOMI daily HCHO coverage is typically 30-50% over China (HCHO has
+lower SNR and stricter cloud filters than NO2), so per-day FNR maps are
+too fragmented to diagnose NOx/VOC-limited regimes reliably. The
+standard fix in the literature (Duncan 2010, Jin & Holloway 2015,
+Souri 2020 et al.) is:
+
+    1. Average HCHO and NO2 columns *separately* over an N-day window
+       (typically 7 or 30 days).
+    2. Divide the averaged fields pixel-wise.
+    3. Mask pixels with too few valid days, and pixels where the mean
+       NO2 column is too low for the FNR interpretation to hold.
+
+Regime classification (Duncan 2010):
+
+    FNR < 1.0   →  VOC-limited   (reducing VOC more effective)
+    1.0 ≤ FNR ≤ 2.0  →  Transition
+    FNR > 2.0   →  NOx-limited   (reducing NOx more effective)
+
+Both HCHO and NO2 readers return columns in 10^15 molec/cm², so FNR is
+dimensionless and directly comparable with the literature.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING
+
+import numpy as np
+from rich.console import Console
+from rich.progress import track
+
+from rsplot.geo.gridding import (
+    fill_nan_gaps,
+    grid_data,
+    mask_to_region,
+    smooth_grid,
+)
+from rsplot.readers import get_product_info
+
+if TYPE_CHECKING:
+    from rsplot.geo.boundaries import RegionInfo
+
+
+# ---------------------------------------------------------------------------
+# Regime thresholds (Duncan et al. 2010, widely reused in the literature)
+# ---------------------------------------------------------------------------
+FNR_VOC_LIMIT = 1.0
+FNR_NOX_LIMIT = 2.0
+
+# Minimum mean NO2 (10^15 molec/cm²) below which FNR is not meaningful.
+# Duncan used 1.5, but over China most non-urban pixels sit below that;
+# keep 0.5 as a softer default and flag in the JSON sidecar.
+NO2_MIN_COLUMN = 0.5
+
+# Display clamp for the FNR colorbar — beyond this the regime classification
+# has already saturated.
+FNR_DISPLAY_MAX = 6.0
+
+
+# ---------------------------------------------------------------------------
+# Date window parsing
+# ---------------------------------------------------------------------------
+def _parse_yyyymmdd(value: str, label: str = "日期") -> datetime:
+    """Parse a YYYYMMDD string and report invalid calendar dates clearly."""
+    try:
+        return datetime.strptime(value, "%Y%m%d")
+    except ValueError as e:
+        raise ValueError(
+            f"{label}无效: '{value}'，请检查年月日是否真实存在 "
+            f"(原始错误: {e})"
+        ) from e
+
+
+def parse_date_window(arg: str, default_days: int) -> list[str]:
+    """Parse a ``YYYYMMDD`` or ``YYYYMMDD-YYYYMMDD`` argument into a date list.
+
+    - Single date → window is the ``default_days``-day period ending on
+      that date (inclusive).
+    - ``START-END`` → inclusive range; ``START`` and ``END`` can be equal.
+
+    Returns YYYYMMDD strings in ascending order.
+    """
+    if "-" in arg:
+        parts = arg.split("-")
+        if len(parts) != 2 or any(len(p) != 8 or not p.isdigit() for p in parts):
+            raise ValueError(
+                f"日期范围格式错误: '{arg}'，应为 YYYYMMDD-YYYYMMDD"
+            )
+        start = _parse_yyyymmdd(parts[0], "开始日期")
+        end = _parse_yyyymmdd(parts[1], "结束日期")
+        if end < start:
+            raise ValueError(f"日期范围起止颠倒: {arg}")
+    else:
+        if len(arg) != 8 or not arg.isdigit():
+            raise ValueError(
+                f"日期格式错误: '{arg}'，应为 YYYYMMDD 或 YYYYMMDD-YYYYMMDD"
+            )
+        end = _parse_yyyymmdd(arg)
+        start = end - timedelta(days=default_days - 1)
+
+    out = []
+    cur = start
+    while cur <= end:
+        out.append(cur.strftime("%Y%m%d"))
+        cur += timedelta(days=1)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Window-mean helper (used by both `rsplot fnr` and `rsplot raster --days`)
+# ---------------------------------------------------------------------------
+@dataclass
+class WindowResult:
+    """Per-product time-averaged grid over a date window.
+
+    The mean field is *not* coverage-masked — callers apply their own
+    ``n_min`` threshold against :attr:`n_valid` (FNR uses a combined
+    NO2 ∧ HCHO mask; raster uses its own product-only threshold).
+    """
+
+    LON: np.ndarray
+    LAT: np.ndarray
+    grid: np.ndarray            # time-mean, NaN where every day was missing
+    n_valid: np.ndarray         # int count of valid days per pixel
+    dates_requested: list[str]
+    dates_found: list[str]
+    dates_failed: dict[str, str]
+    n_pixels_total: int         # sum of swath pixels read across days
+    n_files_total: int          # sum of swath files scanned
+    n_broken_total: int         # sum of unreadable files
+
+
+def compute_window_mean(
+    *,
+    reader,
+    data_dir: str,
+    dates: list[str],
+    extent: tuple[float, float, float, float],
+    res: float,
+    qa_threshold: float,
+    label: str = "数据",
+    console: Console | None = None,
+) -> WindowResult:
+    """Read each date, regrid, return time-mean + per-pixel valid-day count.
+
+    Each day that succeeds contributes one ``(ny, nx)`` grid to the stack;
+    failed days (missing files / no valid pixels) become all-NaN slabs
+    so the caller can still tell which dates fell out.
+    """
+    if console is None:
+        console = Console()
+
+    stack: list[np.ndarray | None] = []
+    dates_found: list[str] = []
+    dates_failed: dict[str, str] = {}
+    n_pix_total = 0
+    n_files_total = 0
+    n_broken_total = 0
+    LON: np.ndarray | None = None
+    LAT: np.ndarray | None = None
+
+    for d in track(dates, description=f"[cyan]读取 {label} 窗口..."):
+        try:
+            s = reader.read(data_dir, d, extent, qa_threshold=qa_threshold)
+            _LON, _LAT, g = grid_data(s.lon, s.lat, s.values, extent, res)
+            LON, LAT = _LON, _LAT
+            stack.append(g)
+            dates_found.append(d)
+            n_pix_total += int(s.n_pixels)
+            n_files_total += int(s.n_files)
+            n_broken_total += int(s.n_broken)
+        except (FileNotFoundError, ValueError) as e:
+            dates_failed[d] = str(e).splitlines()[0]
+            stack.append(None)
+
+    if LON is None or LAT is None:
+        first_errors = "\n  ".join(
+            f"{d}: {msg}" for d, msg in list(dates_failed.items())[:5]
+        )
+        raise ValueError(
+            f"窗口 {dates[0]}~{dates[-1]} 内 {label} 全部失败：\n  {first_errors}"
+        )
+
+    shape = LON.shape
+    filled = [g if g is not None else np.full(shape, np.nan) for g in stack]
+    arr = np.stack(filled, axis=0)  # (n_days, ny, nx)
+    with np.errstate(invalid="ignore"):
+        mean = np.nanmean(arr, axis=0)
+    n_valid = np.isfinite(arr).sum(axis=0).astype(np.int16)
+
+    return WindowResult(
+        LON=LON,
+        LAT=LAT,
+        grid=mean,
+        n_valid=n_valid,
+        dates_requested=list(dates),
+        dates_found=dates_found,
+        dates_failed=dates_failed,
+        n_pixels_total=n_pix_total,
+        n_files_total=n_files_total,
+        n_broken_total=n_broken_total,
+    )
+
+
+# ---------------------------------------------------------------------------
+# FNR result container
+# ---------------------------------------------------------------------------
+@dataclass
+class FnrResult:
+    """Output of :func:`compute_fnr`.
+
+    Grids are all ``(ny, nx)`` on the same LON/LAT meshgrid.
+    """
+
+    LON: np.ndarray
+    LAT: np.ndarray
+    fnr: np.ndarray           # HCHO_mean / NO2_mean, masked
+    hcho_mean: np.ndarray     # raw masked mean, 10^15 molec/cm²
+    no2_mean: np.ndarray      # raw masked mean, 10^15 molec/cm²
+    hcho_mean_filled: np.ndarray  # small-gap-filled diagnostic field
+    no2_mean_filled: np.ndarray   # small-gap-filled diagnostic field
+    n_valid_hcho: np.ndarray  # int count of valid days per pixel
+    n_valid_no2: np.ndarray   # same for NO2
+    dates_requested: list[str]
+    dates_found_hcho: list[str]
+    dates_found_no2: list[str]
+    dates_failed_hcho: dict[str, str]  # date → error message
+    dates_failed_no2: dict[str, str]
+    n_min: int
+    no2_min_column: float
+    diagnostic_masks: dict[str, np.ndarray]
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+def compute_fnr(
+    region: RegionInfo,
+    dates: list[str],
+    *,
+    res: float,
+    qa_threshold: float,
+    n_min: int,
+    raster_dir_no2: str,
+    raster_dir_hcho: str,
+    no2_min_column: float = NO2_MIN_COLUMN,
+    smooth_sigma: float | None = None,
+    console: Console | None = None,
+) -> FnrResult:
+    """Read NO2 + HCHO over a date window and compute per-pixel FNR.
+
+    Each daily swath/grid is first binned onto the same target grid, then
+    the two time-stacks are averaged and divided. Pixels with fewer than
+    ``n_min`` valid days in *either* product, or with mean NO2 below
+    ``no2_min_column``, are masked to NaN.
+    """
+    if console is None:
+        console = Console()
+
+    buf = 1.0  # extent buffer to avoid edge artifacts during regridding
+    read_extent = (
+        region.extent[0] - buf,
+        region.extent[1] + buf,
+        region.extent[2] - buf,
+        region.extent[3] + buf,
+    )
+
+    no2_reader = get_product_info("no2").reader_cls()
+    hcho_reader = get_product_info("hcho").reader_cls()
+
+    # --- Read each product over the window via the shared helper ---
+    no2_win = compute_window_mean(
+        reader=no2_reader,
+        data_dir=raster_dir_no2,
+        dates=dates,
+        extent=read_extent,
+        res=res,
+        qa_threshold=qa_threshold,
+        label="NO2",
+        console=console,
+    )
+    hcho_win = compute_window_mean(
+        reader=hcho_reader,
+        data_dir=raster_dir_hcho,
+        dates=dates,
+        extent=read_extent,
+        res=res,
+        qa_threshold=qa_threshold,
+        label="HCHO",
+        console=console,
+    )
+
+    LON, LAT = no2_win.LON, no2_win.LAT
+    shape = LON.shape
+
+    # --- Combined coverage mask: need n_min valid days in BOTH products ---
+    coverage_ok = (no2_win.n_valid >= n_min) & (hcho_win.n_valid >= n_min)
+
+    # --- NO2-min mask: avoid dividing by tiny NO2 backgrounds ---
+    no2_ok = np.isfinite(no2_win.grid) & (no2_win.grid >= no2_min_column)
+
+    # HCHO retrieval noise can yield negative columns; do not let those
+    # become negative FNR values that classify as VOC-limited.
+    hcho_ok = np.isfinite(hcho_win.grid) & (hcho_win.grid >= 0)
+
+    valid = coverage_ok & no2_ok & hcho_ok
+
+    fnr = np.full(shape, np.nan)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        fnr[valid] = hcho_win.grid[valid] / no2_win.grid[valid]
+
+    # Keep raw mean fields for JSON statistics, and separately prepare
+    # small-gap-filled diagnostic fields for users who want a less holey
+    # view of the underlying columns. The FNR field itself is never filled.
+    hcho_raw = mask_to_region(LON, LAT, hcho_win.grid, region.geometry)
+    no2_raw = mask_to_region(LON, LAT, no2_win.grid, region.geometry)
+    hcho_filled = fill_nan_gaps(LON, LAT, hcho_win.grid)
+    no2_filled = fill_nan_gaps(LON, LAT, no2_win.grid)
+
+    # --- Mask to region boundary ---
+    fnr = mask_to_region(LON, LAT, fnr, region.geometry)
+    hcho_filled = mask_to_region(LON, LAT, hcho_filled, region.geometry)
+    no2_filled = mask_to_region(LON, LAT, no2_filled, region.geometry)
+
+    if smooth_sigma is not None:
+        fnr_valid_mask = np.isfinite(fnr)
+        fnr = smooth_grid(fnr, region.geometry, LON, LAT, sigma=smooth_sigma)
+        # smooth_grid interpolates over NaNs before convolution. Restore the
+        # scientific validity mask so smoothing cannot create new FNR pixels.
+        fnr[~fnr_valid_mask] = np.nan
+
+    return FnrResult(
+        LON=LON,
+        LAT=LAT,
+        fnr=fnr,
+        hcho_mean=hcho_raw,
+        no2_mean=no2_raw,
+        hcho_mean_filled=hcho_filled,
+        no2_mean_filled=no2_filled,
+        n_valid_hcho=hcho_win.n_valid,
+        n_valid_no2=no2_win.n_valid,
+        dates_requested=list(dates),
+        dates_found_hcho=hcho_win.dates_found,
+        dates_found_no2=no2_win.dates_found,
+        dates_failed_hcho=hcho_win.dates_failed,
+        dates_failed_no2=no2_win.dates_failed,
+        n_min=n_min,
+        no2_min_column=no2_min_column,
+        diagnostic_masks={
+            "coverage_ok": coverage_ok,
+            "no2_ok": no2_ok,
+            "hcho_ok": hcho_ok,
+            "final_valid": np.isfinite(fnr),
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# Regime helpers (used by the plotter and the JSON builder)
+# ---------------------------------------------------------------------------
+def classify_regime(fnr: np.ndarray) -> np.ndarray:
+    """Return int codes: 0=VOC-limited, 1=transition, 2=NOx-limited, -1=NaN."""
+    code = np.full(fnr.shape, -1, dtype=np.int8)
+    valid = np.isfinite(fnr)
+    code[valid & (fnr < FNR_VOC_LIMIT)] = 0
+    code[valid & (fnr >= FNR_VOC_LIMIT) & (fnr <= FNR_NOX_LIMIT)] = 1
+    code[valid & (fnr > FNR_NOX_LIMIT)] = 2
+    return code
+
+
+def regime_percentages(fnr: np.ndarray) -> dict[str, float]:
+    """% of valid pixels in each regime."""
+    code = classify_regime(fnr)
+    valid_total = int((code >= 0).sum())
+    if valid_total == 0:
+        return {"voc_limited": 0.0, "transition": 0.0, "nox_limited": 0.0}
+    return {
+        "voc_limited": round(100 * int((code == 0).sum()) / valid_total, 1),
+        "transition": round(100 * int((code == 1).sum()) / valid_total, 1),
+        "nox_limited": round(100 * int((code == 2).sum()) / valid_total, 1),
+    }