rsplot 0.3.1.dev3__py3-none-any.whl → 0.3.2.dev4__py3-none-any.whl

rsplot/result_builders/overlay.py

@@ -6,7 +6,11 @@ from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
-from rsplot.result_builders.common import serialize_region
+from rsplot.result_builders.common import (
+    member_basic_stats,
+    serialize_member,
+    serialize_region,
+)
 from rsplot.result_builders.raster import build_raster_result
 from rsplot.result_builders.station import build_station_result
 
@@ -36,6 +40,10 @@ def build_overlay_result(
     unit: str,
     cities_gdf: gpd.GeoDataFrame | None,
     output: str,
+    display_grid: np.ndarray | None = None,
+    display_lon: np.ndarray | None = None,
+    display_lat: np.ndarray | None = None,
+    time_matching: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Combine raster and station result blocks without shared duplication."""
     raster_block = build_raster_result(
@@ -47,6 +55,9 @@ def build_overlay_result(
         LAT=LAT,
         grid=grid,
         swath_meta=swath_meta,
+        display_grid=display_grid,
+        display_lon=display_lon,
+        display_lat=display_lat,
         vmin=raster_vmin,
         vmax=raster_vmax,
         output=output,
@@ -60,11 +71,25 @@ def build_overlay_result(
         cities_gdf=cities_gdf,
         output=output,
     )
+    if region.members:
+        from rsplot.readers.guokong import mask_stations_to_region
+
+        station_block["member_stats"] = []
+        for member in region.members:
+            selected = mask_stations_to_region(data, member.geometry)
+            station_block["member_stats"].append(
+                {
+                    "region": serialize_member(member),
+                    "n_stations": int(selected.n_stations),
+                    "n_valid": int(selected.n_valid),
+                    "stats": member_basic_stats(selected.values),
+                }
+            )
     for key in ("command", "image", "region"):
         raster_block.pop(key, None)
         station_block.pop(key, None)
 
-    return {
+    result = {
         "command": "overlay",
         "image": output,
         "region": serialize_region(region),
@@ -73,3 +98,8 @@ def build_overlay_result(
         "raster": raster_block,
         "station": station_block,
     }
+    if prod_info.sensor == "gems":
+        result["sensor"] = "gems"
+    if time_matching is not None:
+        result["time_matching"] = time_matching
+    return result

rsplot/result_builders/raster.py

@@ -7,6 +7,8 @@ from typing import TYPE_CHECKING, Any
 import numpy as np
 
 from rsplot.result_builders.common import (
+    grid_boundary_policy,
+    grid_member_stats,
     grid_per_admin_stats,
     grid_stats,
     serialize_region,
@@ -32,6 +34,9 @@ def build_raster_result(
     vmin: float,
     vmax: float,
     output: str,
+    display_grid: np.ndarray | None = None,
+    display_lon: np.ndarray | None = None,
+    display_lat: np.ndarray | None = None,
     window: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Build the stable JSON sidecar payload for a raster run."""
@@ -56,9 +61,36 @@ def build_raster_result(
             total_key="total_region_pixels",
         ),
     }
+    if prod_info.sensor == "gems":
+        result["sensor"] = "gems"
+        result["quantity"] = prod_info.quantity
+        result["statistics_basis"] = "unfilled_unsmoothed_grid"
+        result["input_timezone"] = "Asia/Shanghai"
     if window is not None:
         result["window"] = window
 
+    if display_grid is not None:
+        result["boundary_policy"] = grid_boundary_policy(
+            LON if display_lon is None else display_lon,
+            LAT if display_lat is None else display_lat,
+            display_grid,
+            region,
+        )
+
+    if (
+        display_grid is not None
+        and swath_meta.get("display_support") == "fixed_analysis_valid_cells"
+    ):
+        result["boundary_policy"]["display"]["clip"] = (
+            "administrative_geometry_and_fixed_analysis_valid_cells"
+        )
+        result["boundary_policy"]["display"]["grid_shape"] = list(
+            display_grid.shape
+        )
+
+    if region.members:
+        result["member_stats"] = grid_member_stats(LON, LAT, grid, region)
+
     sub_gdf = region.sub_boundary_gdf
     if sub_gdf is not None and len(sub_gdf) > 0:
         result["spatial_summary"] = grid_per_admin_stats(

rsplot/result_builders/reconstruct.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, Any
 import numpy as np
 
 from rsplot.result_builders.common import (
+    grid_boundary_policy,
     grid_per_admin_stats,
     grid_stats,
     serialize_region,
@@ -29,6 +30,7 @@ def build_reconstruct_result(
     vmin: float,
     vmax: float,
     output: str,
+    display_grid: np.ndarray | None = None,
 ) -> dict[str, Any]:
     """Build the stable JSON sidecar payload for a reconstructed grid."""
     stats = grid_stats(
@@ -72,6 +74,11 @@ def build_reconstruct_result(
         "stats": stats,
     }
 
+    if display_grid is not None:
+        result["boundary_policy"] = grid_boundary_policy(
+            LON, LAT, display_grid, region
+        )
+
     sub_gdf = region.sub_boundary_gdf
     if sub_gdf is not None and len(sub_gdf) > 0:
         result["spatial_summary"] = grid_per_admin_stats(

rsplot/temporal.py

@@ -7,9 +7,9 @@ remain available for compatibility.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime, timedelta
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 import numpy as np
@@ -135,6 +135,7 @@ class WindowResult:
     n_pixels_total: int
     n_files_total: int
     n_broken_total: int
+    daily_metadata: dict[str, Any] = field(default_factory=dict)
 
 
 def compute_window_mean(
@@ -156,6 +157,7 @@ def compute_window_mean(
     valid_counts: np.ndarray | None = None
     dates_found: list[str] = []
     dates_failed: dict[str, str] = {}
+    daily_metadata: dict[str, Any] = {}
     n_pix_total = 0
     n_files_total = 0
     n_broken_total = 0
@@ -164,19 +166,22 @@ def compute_window_mean(
 
     for date in track(dates, description=f"[cyan]读取 {label} 窗口..."):
         try:
-            swath = reader.read(
-                data_dir,
-                date,
-                extent,
+            batch = read_scan_mean(
+                reader=reader,
+                data_dir=data_dir,
+                request=date,
+                extent=extent,
+                res=res,
                 qa_threshold=qa_threshold,
             )
-            day_lon, day_lat, grid = grid_data(
-                swath.lon,
-                swath.lat,
-                swath.values,
-                extent,
-                res,
-            )
+            if batch.metadata:
+                daily_metadata[date] = batch.metadata
+            n_pix_total += batch.n_pixels
+            n_files_total += batch.n_files
+            n_broken_total += batch.n_broken
+            day_lon, day_lat, grid = batch.LON, batch.LAT, batch.grid
+            if not np.isfinite(grid).any():
+                raise ValueError(batch.failure_message())
             LON, LAT = day_lon, day_lat
             if sum_grid is None:
                 sum_grid = np.zeros(grid.shape, dtype=float)
@@ -185,9 +190,6 @@ def compute_window_mean(
             np.add(sum_grid, grid, out=sum_grid, where=finite)
             valid_counts += finite
             dates_found.append(date)
-            n_pix_total += int(swath.n_pixels)
-            n_files_total += int(swath.n_files)
-            n_broken_total += int(swath.n_broken)
         except (FileNotFoundError, ValueError) as e:
             dates_failed[date] = str(e).splitlines()[0]
 
@@ -221,4 +223,125 @@ def compute_window_mean(
         n_pixels_total=n_pix_total,
         n_files_total=n_files_total,
         n_broken_total=n_broken_total,
+        daily_metadata=daily_metadata,
+    )
+
+
+@dataclass
+class ScanMean:
+    """An unfilled grid mean with per-cell temporal sample counts."""
+
+    LON: np.ndarray
+    LAT: np.ndarray
+    grid: np.ndarray
+    n_valid: np.ndarray
+    n_pixels: int
+    n_files: int
+    n_broken: int
+    metadata: dict[str, Any]
+
+    def failure_message(self) -> str:
+        """Keep CLI errors compact; full per-file diagnostics stay in JSON."""
+        message = (
+            f"{self.metadata.get('request', '')} 区域内无有效扫描 "
+            f"({self.n_files} 文件, {self.n_broken} 损坏)。"
+        )
+        examples = list(self.metadata.get("failed_files", {}).items())[:3]
+        if examples:
+            from pathlib import Path
+
+            message += " " + "; ".join(
+                f"{Path(path).name}: {error}" for path, error in examples
+            )
+        return message
+
+
+def read_scan_mean(
+    *,
+    reader: BaseReader,
+    data_dir: str,
+    request: str,
+    extent: tuple[float, float, float, float],
+    res: float,
+    qa_threshold: float = 0.5,
+) -> ScanMean:
+    """Grid each scan independently, then average valid scans equally."""
+    # A NaN sentinel establishes the grid even if every scan is invalid.
+    lon, lat, template = grid_data(
+        np.array([extent[0]]),
+        np.array([extent[2]]),
+        np.array([np.nan]),
+        extent,
+        res,
+    )
+    footprints = getattr(reader, "uses_footprints", False)
+    if footprints:
+        from rsplot.geo.footprints import overlap_mean, regular_grid
+
+        lon, lat = regular_grid(extent, res)
+        template = np.full(lon.shape, np.nan)
+    total = np.zeros(template.shape, dtype=float)
+    counts = np.zeros(template.shape, dtype=np.int32)
+    n_pixels = n_files = n_broken = 0
+    scans = []
+    iterator = getattr(reader, "iter_scans", None)
+    scans_iter = (
+        iterator(data_dir, request, extent, qa_threshold)
+        if iterator is not None
+        else (reader.read(data_dir, request, extent, qa_threshold),)
+    )
+    for scan in scans_iter:
+        n_pixels += scan.n_pixels
+        n_files += scan.n_files
+        n_broken += scan.n_broken
+        if scan.metadata:
+            scans.append(scan.metadata)
+        if not scan.n_pixels:
+            continue
+        if footprints:
+            if scan.corner_lon is None or scan.corner_lat is None:
+                raise ValueError("GEMS 扫描缺少像元边界，不能退回中心点分箱。")
+            grid = overlap_mean(
+                scan.corner_lon, scan.corner_lat, scan.values, lon, lat, res
+            )
+        else:
+            _, _, grid = grid_data(
+                scan.lon, scan.lat, scan.values, extent, res
+            )
+        valid = np.isfinite(grid)
+        np.add(total, grid, out=total, where=valid)
+        counts += valid
+    mean = np.full(template.shape, np.nan)
+    np.divide(total, counts, out=mean, where=counts > 0)
+    covered = counts[counts > 0]
+    metadata = {
+        "request": request,
+        "input_timezone": "Asia/Shanghai",
+        "aggregation": "scan" if len(request) == 12 else "equal_scan_mean",
+        "scans": scans,
+        "n_scans_found": len(scans),
+        "n_scans_valid": sum(s.get("n_pixels", 0) > 0 for s in scans),
+        "failed_files": {s["file"]: s["error"] for s in scans if "error" in s},
+        "coverage_scope": "read_extent",
+        "read_extent": list(extent),
+        "coverage_scans": {
+            "min": int(covered.min()) if covered.size else 0,
+            "max": int(covered.max()) if covered.size else 0,
+            "mean": float(covered.mean()) if covered.size else 0.0,
+        },
+    }
+    if footprints:
+        metadata["spatial_aggregation"] = "footprint_overlap_area_mean"
+        metadata["area_crs"] = "EPSG:6933"
+        metadata["analysis_resolution_deg"] = res
+        metadata["grid_alignment"] = "global_multiples_of_resolution"
+    return ScanMean(
+        lon,
+        lat,
+        mean,
+        counts,
+        n_pixels,
+        n_files,
+        n_broken,
+        metadata if scans else {},
     )

{rsplot-0.3.1.dev3.dist-info → rsplot-0.3.2.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rsplot
-Version: 0.3.1.dev3
+Version: 0.3.2.dev4
 Summary: CLI tool for plotting Remote Sensing data, designed for Agent.
 Project-URL: Repository, https://git.lug.ustc.edu.cn/yaoyhu/rsplot
 Project-URL: GitHub, https://github.com/yaoyhu/rsplot
@@ -217,6 +217,7 @@ Requires-Dist: geopandas>=0.13
 Requires-Dist: matplotlib>=3.7
 Requires-Dist: netcdf4>=1.7.3
 Requires-Dist: numpy>=1.24
+Requires-Dist: pyproj>=3.1
 Requires-Dist: rich>=13.0.0
 Requires-Dist: scipy>=1.10
 Requires-Dist: shapely>=2.0
@@ -436,6 +437,219 @@ writes a JSON sidecar with the same base name. Reconstructed-grid JSON records
 both the China-time input and matched UTC archive hour, source file, native and
 output resolution, regional statistics, administrative summaries, and hotspots.
 
+## Select multiple regions without configuration
+
+`raster` and `overlay` accept a quoted, comma-separated region argument.
+Use English or Chinese commas; surrounding whitespace and embedded line
+breaks are ignored in a list. Province, city, and qualified county/township
+names can be mixed. County and township names still require their city,
+e.g. `中山市/东区街道`. Other commands retain their single-region input.
+
+```bash
+# One map covering three selected townships.
+uv run rsplot raster \
+  "中山市/东区街道,中山市/南区街道,中山市/石岐街道" 20260907 \
+  --sensor gems -p o3pr --cf 1 --res 0.075 --smooth 0 \
+  --basemap none -o ./logs/zhongshan/three_streets_raster.png
+
+# The same daily satellite field with observations at 19:00 China time.
+uv run rsplot overlay \
+  "中山市/东区街道,中山市/南区街道,中山市/石岐街道" 20260907 \
+  --sensor gems -p o3pr --station-datetime 2026090719 \
+  --cf 1 --res 0.075 --smooth 0 --basemap none \
+  -o ./logs/zhongshan/three_streets_overlay.png
+```
+
+These examples use your existing product/station data paths. Optional
+`--data-dir` for raster or `--raster-dir` for overlay overrides the satellite
+root; no named region group needs to be added to configuration.
+
+Every member is resolved before reading data. Repeated aliases are removed
+in first-occurrence order; empty items and unknown names fail with an explicit
+error instead of silently omitting regions. The map reads and processes the
+combined extent once, but colors only the union of the selected geometries,
+preserving holes and gaps between disconnected regions. Each member retains
+its boundary and label. Defaults use the coarsest selected level; combined
+maps use automatic geographic ticks. Explicit plot options still take
+precedence. Far-apart selections share one map with intervening whitespace.
+
+Combined maps use `联合区域（N个）` as their default name. The JSON adds
+`region.members` with canonical qualified names, administrative levels and
+extents. Existing overall statistics operate on the geometric union, without
+double-counting parent/child overlaps. `member_stats` summarizes each selected
+member using that same statistical grid; for overlay these lists are under
+`raster.member_stats` and `station.member_stats`. A member with no valid data
+remains in the list with zero valid counts and null numeric summaries.
+Members may overlap, so their counts must not be added to recover the union
+count. Grid centers exactly on a member boundary are excluded from that
+member's statistics, even if they lie inside the combined region. Station
+selection retains the existing boundary-tolerance rule. `spatial_summary`
+continues to describe subdivisions, independently of selected-member stats.
+Single-region inputs retain their existing output contract.
+
+Run the isolated multi-region regressions:
+
+```bash
+uv run python -m unittest discover -s tests -p 'test_multi_regions.py' -v
+```
+
+## Raster boundaries and regional statistics
+
+`raster`, `overlay`, `forecast` (including station overlays), and
+`reconstruct` prepare separate display and statistics grids:
+
+- **Display:** retain valid grid cells that intersect the administrative
+  geometry, even when their centers are outside. Clip the colored layer to
+  the actual boundary, including holes and disconnected islands. Display
+  smoothing uses surrounding values but preserves the input valid-cell mask.
+- **Statistics:** select grid centers **strictly inside** the geometry;
+  centers exactly on the boundary are excluded. Each valid selected cell has
+  equal weight. Coverage is the valid selected-cell count divided by the
+  total selected-cell count, not the percentage of colored land area.
+  Existing product-specific gap-filling and statistical smoothing behavior
+  remains unchanged; GEMS statistics remain unfilled and unsmoothed.
+
+The PNG sidecar adds `boundary_policy` with the selection and weighting
+rules, the displayed intersecting-cell count, and the count whose centers
+are outside. For `overlay`, this block is nested under `raster`.
+A small region can display overlapping cells while having no interior grid
+centers: its statistics then report zero valid cells and null summaries.
+This change does not increase the satellite's native resolution or fill
+missing observations.
+
+Run boundary-selection and actual rendering regressions (including holes
+and both PlateCarree and Mercator projections):
+
+```bash
+uv run python -m unittest discover -s tests -p 'test_boundary_display.py' -v
+```
+
+## GEMS satellite products
+
+Use `--sensor gems` with `raster`, `recent`, and `overlay`. Omitting
+`--sensor` retains TROPOMI behavior. GEMS FNR and satellite trend curves are
+not included in this release.
+
+Configure the three archive roots in `[paths.data_dirs]`:
+
+```toml
+gems_no2 = "/path/to/GEMS/NO2"
+gems_hcho = "/path/to/GEMS/HCHO"
+gems_o3 = "/path/to/GEMS/O3"
+```
+
+Alternatively set `RSPLOT_DATA_DIR_GEMS_NO2`, `RSPLOT_DATA_DIR_GEMS_HCHO`,
+and `RSPLOT_DATA_DIR_GEMS_O3`. Each root contains `YYYYMM/DD/*.nc`.
+`--data-dir` (`--raster-dir` for overlay) overrides the configured root.
+
+| Product | GEMS variable | Display unit |
+| --- | --- | --- |
+| `no2` | `Data Fields/ColumnAmountNO2Trop` | 10¹⁵ molecules/cm² |
+| `hcho` | `Data Fields/ColumnAmount` | 10¹⁵ molecules/cm² |
+| `o3` | `product/total_ozone_column` | DU |
+| `o3pr` | `product/troposphere_ozone_column` | DU |
+
+Both ozone quantities use the O3P files in `gems_o3`; `o3pr` reads the
+provided tropospheric column without reintegrating the profile. Neither
+quantity represents surface ozone concentration.
+
+GEMS dates and scan requests use **Asia/Shanghai**. `YYYYMMDDHHMM` selects
+an exact nominal scan; `YYYYMMDD` computes the day's valid-scan mean.
+For example, `202609010845` selects the `20260901_0045` UTC archive scan.
+The filename is the nominal scan time, not a simultaneous observation time
+for every pixel: GEMS scans begin at :45 UTC and take about 30 minutes
+([NESC operation schedule](https://nesc.nier.go.kr/en/html/satellite/operation.do)).
+Missing scan requests report available local times instead of selecting a
+replacement. Duplicate files for one nominal scan are rejected; use a root
+containing one archive version.
+
+```bash
+# Exact scan, daily mean, and multi-day mean.
+rsplot raster 安徽 202609011145 --sensor gems -p no2 \
+  --basemap none --output /tmp/gems_no2_scan.png
+rsplot raster 安徽 20260901 --sensor gems -p hcho \
+  --basemap none --output /tmp/gems_hcho_daily.png
+rsplot raster 安徽 20260901-20260902 --sensor gems -p o3pr \
+  --basemap none --output /tmp/gems_o3pr_window.png
+
+# Recent daily regional statistics (JSON only).
+rsplot recent 安徽 20260902 --days 2 --source raster --sensor gems -p no2 \
+  --output /tmp/gems_no2_recent.json
+
+# 11:45 China-time scan with observations at the nearest hour, 12:00.
+rsplot overlay 安徽 202609011145 --sensor gems -p no2 \
+  --basemap none --output /tmp/gems_no2_overlay.png
+# Use --station-datetime YYYYMMDDHH for an intentional time override.
+```
+
+Each scan is first remapped by pixel/target overlap area in the equal-area
+EPSG:6933 projection, onto a **globally aligned 0.05° analysis grid**. This is
+a numerical analysis spacing, not native satellite resolution. Daily means
+weight valid scans equally at each grid cell; multi-day means then weight
+valid days equally. A daily cell needs at least one valid scan. Window `--n-min`
+continues to count **days**, using the existing product defaults, and is not
+available for a single scan. These are means of available daytime scans,
+not full 24-hour means. Empty scans and failed files do not contribute zeros.
+
+For GEMS `raster` and `overlay`, **`--res` controls only the display grid**.
+Display cells receive area-weighted analysis values and are clipped to the
+fixed analysis grid's valid-cell union and the administrative boundary.
+Changing `--res` can change displayed averages, but cannot move the valid
+support or change the scientific statistics. `--smooth` is applied on the
+fixed analysis grid for display only, preserving its valid mask. GEMS
+`recent` uses the same 0.05° analysis spacing and ignores `--res`.
+TROPOMI keeps its existing resolution behavior.
+
+When available, GEMS pixel boundaries use file `CornerLongitude` and
+`CornerLatitude` arrays. The checked O3P and NO2 files have centers only;
+their quadrilateral boundaries are **estimates from adjacent unfiltered
+native centers**, with linear extrapolation at the outer scan edge. Missing
+geolocation is not interpolated, and rejected retrievals do not contribute
+values. This is not a recovery of official footprints or extra observations.
+Analysis cells need positive-area overlap with valid footprints; their
+coverage percentage counts valid analysis centers, not precisely observed
+land area. Subcell gaps remain below the 0.05° analysis spacing.
+
+Sidecars record `footprint_source` per scan, `spatial_aggregation`,
+`area_crs`, `analysis_resolution_deg`, `display_resolution_deg`, and
+`display_support`. The compatibility `swath.resolution_deg` describes the
+analysis grid. Statistics differ from the previous center-point-binning
+implementation, but remain identical across display resolutions.
+
+The initial GEMS filter retains final quality flag **0**, finite coordinates
+and columns, SZA/VZA below 70°, and a nonnegative cloud measure no greater
+than `--cf` (default 0.5). The cloud measures differ: NO2 uses `CloudFraction`,
+HCHO uses `CloudRadianceFraction`, and O3P uses `effective_cloud_fraction`.
+`--qa` applies only to TROPOMI and is rejected for GEMS. Quality-filtered
+negative columns are retained; HCHO gap-filled flag classes are excluded.
+This explicit filter is recorded with each file's version and variable in
+JSON; quality flag meanings must not be transferred between products.
+
+GEMS JSON statistics, spatial summaries, and hotspots use the **unfilled,
+unsmoothed** regional grid. Smoothing affects the map only and cannot create
+new valid cells. Sidecars include `sensor`, `quantity`, the requested local
+time, nominal UTC/local scan times, actual observation time ranges, filter
+settings, file failures, and scan-count summaries. Window metadata retains
+per-day diagnostics. Existing TROPOMI fields remain compatible; the boundary
+policy block described above is additive.
+
+GEMS `overlay` accepts an exact scan or a daily mean. A daily mean requires
+an explicit `--station-datetime YYYYMMDDHH`; its title and JSON distinguish
+the daily satellite mean from the hourly station observation, without a
+fictitious scan-time offset. Exact scans match the nearest station hour
+(at most 30 minutes, ties forward). A missing station hour is an error.
+`--station-datetime` records a manual override and its time difference.
+NO2 pairs with NO2; O3/O3PR pair with O3; HCHO requires an explicit `--var`.
+Satellite columns and station concentrations retain independent colorbars
+and units; the map shows spatial juxtaposition, not a column-to-surface
+conversion.
+
+Run the self-contained GEMS regressions without adding pytest:
+
+```bash
+uv run python -m unittest discover -s tests -p 'test_gems.py' -v
+```
+
 ## License
 
 This project is distributed under the license in `LICENSE`.