meteoraster 3.0__tar.gz → 3.1__tar.gz

{meteoraster-3.0/meteoraster.egg-info → meteoraster-3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meteoraster
-Version: 3.0
+Version: 3.1
 Summary: Module for handling distributed ensemble and probabilistic forecast data (5-D meteorological rasters)
 Author-email: Jose Pedro Matos <jose.matos@tecnico.ulisboa.pt>
 License-Expression: Apache-2.0
@@ -238,10 +238,19 @@ ts = mr.get_values_from_latlon(lat=35.0, lon=0.0)
 
 ```python
 # agg: DataFrame indexed by production date, columns MultiIndex(zone, leadtime, ensemble_member)
-# centroids: DataFrame of zone centroids (x, y)
+# centroids: DataFrame of zone centroids (x, y) and grid_fraction (share of the zone on the grid)
 agg, centroids = mr.get_values_from_KML("zones.kml", nameField="zone_id")
+
+# v3.0 numbers (square-degree weights) instead of true WGS84 areas
+agg, centroids = mr.get_values_from_KML("zones.kml", nameField="zone_id",
+                                        area_weighting="planar")
 ```
 
+Coordinates are WGS84 lon/lat of cell **centres** (curvilinear 2-D grids included);
+KML edges are straight lines in lon/lat. Weights are true WGS84 areas by default.
+A zone partly outside the grid is averaged over the part inside and warns
+(`on_partial=`); a reused `coverage_info` must match the raster's grid.
+
 Spatial **quantiles** over the same zones, area-weighted so a cell half inside a
 zone carries half the probability mass:
 
@@ -543,6 +552,12 @@ changed for any zone touching the edge of the grid: the legacy builder gave the
 outermost row and column no weight and took its validity threshold from the first
 zone. `ensemble_member` labels are now 0-based, matching the other extractors.
 
+Since **v3.1** the default weights are true WGS84 areas (`area_weighting='ellipsoidal'`)
+instead of square degrees. Square degrees over-weight the poleward side of a zone by
+roughly tan(lat) x lat-span: measured 1 % less rain over a Zambezi-sized basin, 0.02 %
+on the Vesdre catchments, 8 % on a single cell weight for a 5 deg zone at 60 N. Pass
+`area_weighting='planar'` to reproduce v3.0 exactly.
+
 **`meteoraster.zonal`** — needs no `MeteoRaster`; takes plain coordinate arrays.
 
 | Member | Description |
@@ -553,7 +568,8 @@ zone. `ensemble_member` labels are now 0-based, matching the other extractors.
 | `quantiles_from_coverage(coverage, values, quantiles, pool_axes=(), …)` | Area-weighted spatial quantiles per zone. |
 | `weighted_quantiles(values, weights, quantiles, method='hazen')` | The quantile primitive. Reduces exactly to `np.quantile` for equal weights. |
 | `Coverage.save/load`, `Coverage.matches`, `grid_fingerprint` | Persist a coverage to a pickle-free `.npz` and check it against a grid; the fingerprint hashes the coordinates, so a shifted grid of the same shape is a miss. |
-| `cell_corners`, `cell_areas`, `cell_bounds` | The grid geometry, extrapolated half a cell at the boundary so no cell is skipped. |
+| `cell_corners`, `cell_areas`, `cell_bounds` | The grid geometry, extrapolated half a cell at the boundary so no cell is skipped. `cell_areas(..., 'ellipsoidal')` gives km². |
+| `ring_area`, `geometry_area`, `authalic_latitude` | Exact WGS84 areas (km²) of lon/lat rings and ogr polygons, used by `area_weighting='ellipsoidal'`. |
 
 **`meteoraster.io`** — the portable read path.
 

{meteoraster-3.0 → meteoraster-3.1}/README.md

@@ -185,10 +185,19 @@ ts = mr.get_values_from_latlon(lat=35.0, lon=0.0)
 
 ```python
 # agg: DataFrame indexed by production date, columns MultiIndex(zone, leadtime, ensemble_member)
-# centroids: DataFrame of zone centroids (x, y)
+# centroids: DataFrame of zone centroids (x, y) and grid_fraction (share of the zone on the grid)
 agg, centroids = mr.get_values_from_KML("zones.kml", nameField="zone_id")
+
+# v3.0 numbers (square-degree weights) instead of true WGS84 areas
+agg, centroids = mr.get_values_from_KML("zones.kml", nameField="zone_id",
+                                        area_weighting="planar")
 ```
 
+Coordinates are WGS84 lon/lat of cell **centres** (curvilinear 2-D grids included);
+KML edges are straight lines in lon/lat. Weights are true WGS84 areas by default.
+A zone partly outside the grid is averaged over the part inside and warns
+(`on_partial=`); a reused `coverage_info` must match the raster's grid.
+
 Spatial **quantiles** over the same zones, area-weighted so a cell half inside a
 zone carries half the probability mass:
 
@@ -490,6 +499,12 @@ changed for any zone touching the edge of the grid: the legacy builder gave the
 outermost row and column no weight and took its validity threshold from the first
 zone. `ensemble_member` labels are now 0-based, matching the other extractors.
 
+Since **v3.1** the default weights are true WGS84 areas (`area_weighting='ellipsoidal'`)
+instead of square degrees. Square degrees over-weight the poleward side of a zone by
+roughly tan(lat) x lat-span: measured 1 % less rain over a Zambezi-sized basin, 0.02 %
+on the Vesdre catchments, 8 % on a single cell weight for a 5 deg zone at 60 N. Pass
+`area_weighting='planar'` to reproduce v3.0 exactly.
+
 **`meteoraster.zonal`** — needs no `MeteoRaster`; takes plain coordinate arrays.
 
 | Member | Description |
@@ -500,7 +515,8 @@ zone. `ensemble_member` labels are now 0-based, matching the other extractors.
 | `quantiles_from_coverage(coverage, values, quantiles, pool_axes=(), …)` | Area-weighted spatial quantiles per zone. |
 | `weighted_quantiles(values, weights, quantiles, method='hazen')` | The quantile primitive. Reduces exactly to `np.quantile` for equal weights. |
 | `Coverage.save/load`, `Coverage.matches`, `grid_fingerprint` | Persist a coverage to a pickle-free `.npz` and check it against a grid; the fingerprint hashes the coordinates, so a shifted grid of the same shape is a miss. |
-| `cell_corners`, `cell_areas`, `cell_bounds` | The grid geometry, extrapolated half a cell at the boundary so no cell is skipped. |
+| `cell_corners`, `cell_areas`, `cell_bounds` | The grid geometry, extrapolated half a cell at the boundary so no cell is skipped. `cell_areas(..., 'ellipsoidal')` gives km². |
+| `ring_area`, `geometry_area`, `authalic_latitude` | Exact WGS84 areas (km²) of lon/lat rings and ogr polygons, used by `area_weighting='ellipsoidal'`. |
 
 **`meteoraster.io`** — the portable read path.
 

{meteoraster-3.0 → meteoraster-3.1}/meteoraster/meteoraster.py

@@ -20,6 +20,15 @@ class MeteoRaster(object):
     '''
     Custom class to handle meteorological raster files, including ensembles and forecasts
 
+    v3.1:
+        get_values_from_KML / get_quantiles_from_KML weight by true WGS84 area
+        (area_weighting='ellipsoidal', new default) instead of square degrees, which
+        over-weighted the poleward side of a zone by ~tan(lat) * lat-span. Pass
+        area_weighting='planar' to reproduce v3.0 exactly. A zone partly outside
+        the grid now warns (on_partial=) and centroids carry its grid_fraction. A
+        reused coverage_info built for another grid raises instead of aggregating
+        the wrong cells.
+
     v3.0:
         BREAKING - four readers are gone. meteoraster.utils keeps only
         readERA5Land_monthly and read_ERA5Land_hourly; readERA5_monthly, read_GFS,
@@ -178,7 +187,7 @@ class MeteoRaster(object):
         Untested support for pd.DateOffset
     '''
     
-    VERSION = '3.0'
+    VERSION = '3.1'
     VERBOSE = True
     ENSEMBLEMEMBERpOSITION = 1
 
@@ -287,6 +296,10 @@ class MeteoRaster(object):
         if crs is None:
             crs = ccrs.PlateCarree()
 
+        # Recent PROJ (seen on 9.8) rejects central_longitude=None ("+pm" with no value)
+        if central_longitude is None:
+            central_longitude = 0.0
+
         plt.figure(figsize=figsize)
         projection = projection_fun(central_longitude=central_longitude, **projection_kwargs)
         ax = plt.axes(projection=projection)
@@ -412,7 +425,8 @@ class MeteoRaster(object):
         return ax
 
     def get_values_from_KML(self, kml, nameField=None, coverage_info=None, getCoverageInfo=False,
-                            elementwise=False, min_coverage=None, on_error='raise'):
+                            elementwise=False, min_coverage=None, on_error='raise',
+                            area_weighting=None, on_partial='warn'):
         '''
         Area-weighted mean of each KML zone, per production, member and leadtime.
 
@@ -434,6 +448,13 @@ class MeteoRaster(object):
               zonal.MIN_COVERAGE.
         elementwise: accepted for backwards compatibility and ignored. It skipped the
               missing-data renormalisation, which apply_coverage now always applies.
+        area_weighting: 'ellipsoidal' (default, true WGS84 areas), 'cos_lat', or
+              'planar' (square degrees) to reproduce v3.0 numbers. See zonal.
+        on_partial: 'warn' (default), 'raise' or 'ignore' for zones partly outside
+              the grid; centroids['grid_fraction'] holds the share inside.
+
+        A reused coverage_info must have been built for this exact grid (checked by
+        fingerprint for zonal.Coverage, by shape for the legacy tuple).
         '''
 
         if elementwise:
@@ -447,10 +468,13 @@ class MeteoRaster(object):
         if isinstance(coverage_info, type(None)):
             coverage = _zonal.coverage_from_kml(kml, self.latitudes, self.longitudes,
                                                 name_field=nameField, on_error=on_error,
-                                                normalize='area')
+                                                normalize='area',
+                                                area_weighting=area_weighting or _zonal.DEFAULT_AREA_WEIGHTING,
+                                                on_partial=on_partial)
             coverage_info = coverage
         else:
             coverage = self.__as_coverage(coverage_info)
+            self.__check_coverage(coverage)
 
         agg = self.__groupByCoverage(coverage, min_coverage)
 
@@ -464,7 +488,8 @@ class MeteoRaster(object):
     def get_quantiles_from_KML(self, kml, nameField=None, coverage_info=None, getCoverageInfo=False,
                                resampling=None, quantiles=(0.01, 0.1, 0.5, 0.9, 0.99),
                                pool=('space',), min_coverage=None, method='hazen',
-                               precision=None, on_error='raise'):
+                               precision=None, on_error='raise', area_weighting=None,
+                               on_partial='warn'):
         '''
         Area-weighted spatial quantiles over the KML zones.
 
@@ -501,6 +526,7 @@ class MeteoRaster(object):
         method: 'hazen' (default) or 'linear'. See zonal.weighted_quantiles.
         precision: accepted for backwards compatibility, ignored, and warns when
               passed - the result no longer depends on it.
+        area_weighting, on_partial: as in get_values_from_KML.
         '''
 
         if precision is not None:
@@ -515,10 +541,13 @@ class MeteoRaster(object):
         if isinstance(coverage_info, type(None)):
             coverage = _zonal.coverage_from_kml(kml, self.latitudes, self.longitudes,
                                                 name_field=nameField, on_error=on_error,
-                                                normalize='cell_fraction')
+                                                normalize='cell_fraction',
+                                                area_weighting=area_weighting or _zonal.DEFAULT_AREA_WEIGHTING,
+                                                on_partial=on_partial)
             coverage_info = coverage
         else:
             coverage = self.__as_coverage(coverage_info)
+            self.__check_coverage(coverage)
 
         agg = self.__groupByQuantile(coverage, resampling, quantiles, pool, min_coverage, method)
 
@@ -546,6 +575,16 @@ class MeteoRaster(object):
         raise TypeError('coverage_info must be a zonal.Coverage or a legacy '
                         '(coverage, columns, centroids) tuple.')
 
+    def __check_coverage(self, coverage):
+        '''
+        Raises if a reused coverage was built for a different grid.
+        '''
+
+        if not coverage.matches(self.latitudes, self.longitudes):
+            raise ValueError('coverage_info was built for a different grid (shape %s or '
+                             'coordinates differ from this raster %s). Rebuild it from the KML.'
+                             % (coverage.shape, self.latitudes.shape))
+
     def get_cropped(self, from_prod_date=dt.datetime(1900, 1, 1), to_prod_date=dt.datetime(2199, 12, 31),
                    from_lat=-90, to_lat=90, from_lon=-180, to_lon=180,
                    from_leadtime=None, to_leadtime=None):

{meteoraster-3.0 → meteoraster-3.1}/meteoraster/zonal.py

@@ -16,9 +16,15 @@ Properties worth knowing:
   weighting the whole grid. Peak memory is one block, not block x zones.
 - Missing data is renormalised and the coverage threshold applied *per zone and per
   slice*, never taking one zone as representative of the others.
-- Weights are areas in square degrees (`area_weighting='planar'`). They are
-  normalised per zone, so the cos(latitude) factor nearly cancels across a basin;
-  for continental or high-latitude zones pass `area_weighting='cos_lat'`.
+- Coordinates are WGS84 lon/lat of cell *centres*; KML edges are straight lines
+  in lon/lat. Overlaps are cut in that plane.
+- Weights default to true WGS84 areas (`area_weighting='ellipsoidal'`, exact on
+  the authalic sphere). `'planar'` (square degrees, the v3.0 default) is kept as a
+  fall-back. Normalising per zone does *not* cancel the cos(latitude) factor:
+  planar weights within a zone are off by ~tan(lat) * lat_span (5 deg span at
+  60 deg: ~15 %). `'cos_lat'` scales each overlap by its cell-centre cos(lat).
+- A zone partly outside the grid is averaged over the part inside; the fraction
+  inside is `Coverage.grid_fraction` and `on_partial` warns about it.
 
 Since v3.0 MeteoRaster.get_values_from_KML and get_quantiles_from_KML both run on
 this module; the coverage builder they used before got the first and third points
@@ -43,7 +49,16 @@ from . import _lazy
 #: changes how the stored weights read.
 NORMALISATIONS = ('area', 'cell_fraction', 'none')
 
-AREA_WEIGHTINGS = ('planar', 'cos_lat')
+AREA_WEIGHTINGS = ('ellipsoidal', 'cos_lat', 'planar')
+
+DEFAULT_AREA_WEIGHTING = 'ellipsoidal'
+
+#: A zone whose grid_fraction is below 1 - this is reported by on_partial.
+GRID_FRACTION_TOLERANCE = 1e-3
+
+# WGS84 semi-major axis (m) and first eccentricity.
+_WGS84_A = 6378137.0
+_WGS84_E = 0.0818191908426215
 
 #: Weighted-quantile plotting positions. See weighted_quantiles() for why
 #: 'hazen' is the default rather than the numpy-'linear'-compatible option.
@@ -132,9 +147,11 @@ def cell_bounds(corner_lat, corner_lon):
     return lat_min, lat_max, lon_min, lon_max
 
 
-def cell_areas(corner_lat, corner_lon):
+def cell_areas(corner_lat, corner_lon, area_weighting='planar'):
     '''
-    Returns each cell's area (rows, cols) by the shoelace formula on its quad.
+    Returns each cell's area (rows, cols) from its quad.
+
+    'planar': square degrees (shoelace). 'ellipsoidal': km^2 on WGS84.
     '''
 
     x = np.stack((corner_lon[:-1, :-1], corner_lon[:-1, 1:],
@@ -142,6 +159,9 @@ def cell_areas(corner_lat, corner_lon):
     y = np.stack((corner_lat[:-1, :-1], corner_lat[:-1, 1:],
                   corner_lat[1:, 1:], corner_lat[1:, :-1]))
 
+    if area_weighting == 'ellipsoidal':
+        return ring_area(x, y)
+
     total = np.zeros(x.shape[1:], dtype=float)
     for i in range(4):
         j = (i + 1) % 4
@@ -150,6 +170,71 @@ def cell_areas(corner_lat, corner_lon):
     return np.abs(total) * 0.5
 
 
+def authalic_latitude(latitudes):
+    '''
+    Returns the WGS84 authalic latitude (degrees): equal-area latitude on a sphere.
+    '''
+
+    e = _WGS84_E
+    sin_phi = np.sin(np.radians(np.clip(np.asarray(latitudes, dtype=float), -90.0, 90.0)))
+
+    def q(s):
+        return (1 - e ** 2) * (s / (1 - (e * s) ** 2)
+                               - np.log((1 - e * s) / (1 + e * s)) / (2 * e))
+
+    return np.degrees(np.arcsin(np.clip(q(sin_phi) / q(1.0), -1.0, 1.0)))
+
+
+def _authalic_radius_km():
+    e = _WGS84_E
+    q_pole = (1 - e ** 2) * (1 / (1 - e ** 2) - np.log((1 - e) / (1 + e)) / (2 * e))
+
+    return _WGS84_A * np.sqrt(q_pole / 2) / 1000.0
+
+
+def ring_area(lon, lat):
+    '''
+    Area (km^2) enclosed by rings on WGS84, edges straight in lon/lat.
+
+    lon, lat: [n_vertices, ...] degrees; the ring closes itself (a repeated
+    first vertex adds a zero-length edge). Exact on the authalic sphere for edges
+    linear in (lon, authalic lat), i.e. the integral of cos(beta) dbeta dlon.
+    No antimeridian handling.
+    '''
+
+    lam = np.radians(np.asarray(lon, dtype=float))
+    beta = np.radians(authalic_latitude(lat))
+
+    d_lam = np.roll(lam, -1, axis=0) - lam
+    beta_next = np.roll(beta, -1, axis=0)
+    # (cos b1 - cos b2) / (b2 - b1), stable as b2 -> b1
+    strip = np.sin(0.5 * (beta + beta_next)) * np.sinc((beta_next - beta) / (2 * np.pi))
+
+    return np.abs((d_lam * strip).sum(axis=0)) * _authalic_radius_km() ** 2
+
+
+def geometry_area(geometry):
+    '''
+    Area (km^2) on WGS84 of an ogr polygon, multipolygon or collection (holes subtracted).
+    '''
+
+    name = geometry.GetGeometryName()
+    if name == 'POLYGON':
+        total = 0.0
+        for i in range(geometry.GetGeometryCount()):
+            points = np.asarray(geometry.GetGeometryRef(i).GetPoints() or [], dtype=float)
+            if points.shape[0] < 3:
+                continue
+            area = float(ring_area(points[:, 0], points[:, 1]))
+            total += area if i == 0 else -area
+        return total
+    if name in ('MULTIPOLYGON', 'GEOMETRYCOLLECTION'):
+        return sum(geometry_area(geometry.GetGeometryRef(i))
+                   for i in range(geometry.GetGeometryCount()))
+
+    return 0.0
+
+
 def grid_fingerprint(latitudes, longitudes):
     '''
     Returns a sha256 hex digest of the grid geometry.
@@ -201,6 +286,8 @@ class Coverage:
     offsets    : len(zones)+1 offsets into cell_index / weight
     cell_index : flat (row * cols + col) indices, concatenated over zones
     weight     : matching weights, concatenated over zones
+    grid_fraction : per zone, share of the polygon's area that lies on the grid
+                    (None for coverages built before v3.1)
     '''
 
     zones: list
@@ -213,6 +300,7 @@ class Coverage:
     normalize: str = 'area'
     area_weighting: str = 'planar'
     fingerprint: str = ''
+    grid_fraction: np.ndarray = None
 
     def __len__(self):
         return len(self.zones)
@@ -226,6 +314,10 @@ class Coverage:
             raise ValueError('offsets must have len(zones)+1 entries.')
         if self.cell_index.size != self.weight.size:
             raise ValueError('cell_index and weight must have the same length.')
+        if self.grid_fraction is not None:
+            self.grid_fraction = np.asarray(self.grid_fraction, dtype=np.float64)
+            if self.grid_fraction.size != len(self.zones):
+                raise ValueError('grid_fraction must have one entry per zone.')
 
     @property
     def shape(self):
@@ -314,8 +406,13 @@ class Coverage:
             centroids = pd.DataFrame({'x': np.full(len(self), np.nan),
                                       'y': np.full(len(self), np.nan)}, index=self.zones)
 
+        extra = {}
+        if self.grid_fraction is not None:
+            extra['grid_fraction'] = self.grid_fraction
+
         np.savez_compressed(
             str(file),
+            **extra,
             zones=np.asarray([str(z) for z in self.zones], dtype='U'),
             grid=np.asarray([self.rows, self.cols], dtype='int64'),
             offsets=self.offsets,
@@ -338,13 +435,18 @@ class Coverage:
             meta = [str(v) for v in payload['meta']]
             centroids = pd.DataFrame({'x': payload['centroid_x'],
                                       'y': payload['centroid_y']}, index=zones)
+            grid_fraction = None
+            if 'grid_fraction' in payload.files:
+                grid_fraction = payload['grid_fraction']
+                centroids['grid_fraction'] = grid_fraction
 
             return cls(zones=zones, rows=rows, cols=cols,
                        offsets=payload['offsets'],
                        cell_index=payload['cell_index'],
                        weight=payload['weight'],
                        centroids=centroids,
-                       normalize=meta[0], area_weighting=meta[1], fingerprint=meta[2])
+                       normalize=meta[0], area_weighting=meta[1], fingerprint=meta[2],
+                       grid_fraction=grid_fraction)
 
     def matches(self, latitudes, longitudes):
         '''
@@ -576,12 +678,17 @@ def _as_geometry(ogr, geometry):
 
 def coverage_from_geometries(latitudes, longitudes, geometries, names=None,
                              halo=1, buffer=None, normalize='area',
-                             area_weighting='planar', min_area=0.0,
-                             on_empty='warn'):
+                             area_weighting=DEFAULT_AREA_WEIGHTING, min_area=0.0,
+                             on_empty='warn', on_partial='warn'):
     '''
     Builds a Coverage by exact fractional overlap of each cell with each polygon.
 
-    geometries: ogr.Geometry, WKB bytes or WKT strings.
+    geometries: ogr.Geometry, WKB bytes or WKT strings, WGS84 lon/lat.
+    area_weighting: 'ellipsoidal' (km^2 on WGS84, default), 'cos_lat', or
+                'planar' (square degrees; reproduces v3.0).
+    min_area:   overlaps at or below this are dropped, in the units of the
+                overlap before normalisation (square degrees for 'planar' and
+                'cos_lat', km^2 for 'ellipsoidal').
     halo:       extra rings of candidate cells. The envelope prefilter is already
                 conservative, so this is only numerical insurance; it is cheap
                 because non-overlapping candidates contribute zero area and are
@@ -592,6 +699,9 @@ def coverage_from_geometries(latitudes, longitudes, geometries, names=None,
     buffer:     legacy envelope padding in degrees, applied in addition to halo.
     on_empty:   what to do about a zone that caught no cell ('warn', 'raise',
                 'ignore'). It used to be a ValueError from min() of an empty array.
+    on_partial: what to do about a zone partly outside the grid ('warn', 'raise',
+                'ignore'). Its mean is taken over the part inside, renormalised,
+                so it looks plausible; `grid_fraction` says how much is inside.
     '''
 
     if normalize not in NORMALISATIONS:
@@ -600,6 +710,8 @@ def coverage_from_geometries(latitudes, longitudes, geometries, names=None,
         raise ValueError('area_weighting must be one of %s.' % ', '.join(AREA_WEIGHTINGS))
     if on_empty not in ('warn', 'raise', 'ignore'):
         raise ValueError("on_empty must be 'warn', 'raise' or 'ignore'.")
+    if on_partial not in ('warn', 'raise', 'ignore'):
+        raise ValueError("on_partial must be 'warn', 'raise' or 'ignore'.")
 
     ogr = _lazy.ogr()
     latitudes, longitudes = as_grid(latitudes, longitudes)
@@ -607,7 +719,10 @@ def coverage_from_geometries(latitudes, longitudes, geometries, names=None,
 
     corner_lat, corner_lon = cell_corners(latitudes, longitudes)
     lat_min, lat_max, lon_min, lon_max = cell_bounds(corner_lat, corner_lon)
-    areas = cell_areas(corner_lat, corner_lon) if normalize == 'cell_fraction' else None
+    areas = None
+    if normalize == 'cell_fraction':
+        areas = cell_areas(corner_lat, corner_lon,
+                           'ellipsoidal' if area_weighting == 'ellipsoidal' else 'planar')
 
     scale = None
     if area_weighting == 'cos_lat':
@@ -623,13 +738,18 @@ def coverage_from_geometries(latitudes, longitudes, geometries, names=None,
     offsets = [0]
     all_index, all_weight = [], []
     centroid_x, centroid_y = [], []
-    empty = []
+    grid_fraction = []
+    empty, wide = [], []
 
     pad = 0.0 if buffer is None else float(buffer)
 
     for name, raw in zip(names, geometries):
         polygon = _as_geometry(ogr, raw)
         west, east, south, north = polygon.GetEnvelope()
+        if east - west > 180:
+            wide.append(name)
+        polygon_area = geometry_area(polygon)
+        inside_area = 0.0
 
         # Conservative: a cell can only intersect the polygon if its bounding box
         # overlaps the polygon's envelope.
@@ -665,7 +785,9 @@ def coverage_from_geometries(latitudes, longitudes, geometries, names=None,
             # line or a point; Area() would warn on stdout and return 0 anyway.
             if overlap.GetDimension() != 2:
                 continue
-            area = overlap.Area()
+            true_area = geometry_area(overlap)
+            inside_area += true_area
+            area = true_area if area_weighting == 'ellipsoidal' else overlap.Area()
             if area <= min_area:
                 continue
 
@@ -680,6 +802,7 @@ def coverage_from_geometries(latitudes, longitudes, geometries, names=None,
 
         if not index:
             empty.append(name)
+        grid_fraction.append(min(inside_area / polygon_area, 1.0) if polygon_area > 0 else 0.0)
 
         weight = np.asarray(weight, dtype=float)
         if normalize == 'area' and weight.size and weight.sum() > 0:
@@ -698,7 +821,22 @@ def coverage_from_geometries(latitudes, longitudes, geometries, names=None,
         if on_empty == 'warn':
             warnings.warn(message)
 
-    centroids = pd.DataFrame({'x': centroid_x, 'y': centroid_y}, index=names)
+    partial = ['%s (%.1f%%)' % (name, 100 * fraction) for name, fraction in zip(names, grid_fraction)
+               if name not in empty and fraction < 1 - GRID_FRACTION_TOLERANCE]
+    if partial and on_partial != 'ignore':
+        message = ('%d zone(s) lie partly outside the grid: %s (share inside). Their means '
+                   'cover only that share.' % (len(partial), ', '.join(partial)))
+        if on_partial == 'raise':
+            raise ValueError(message)
+        warnings.warn(message)
+
+    if wide:
+        warnings.warn('%d zone(s) span more than 180 deg of longitude: %s. Polygons crossing '
+                      'the antimeridian are not supported; split them at +/-180.'
+                      % (len(wide), ', '.join(wide)))
+
+    centroids = pd.DataFrame({'x': centroid_x, 'y': centroid_y,
+                              'grid_fraction': grid_fraction}, index=names)
 
     return Coverage(
         zones=names, rows=rows, cols=cols,
@@ -707,6 +845,7 @@ def coverage_from_geometries(latitudes, longitudes, geometries, names=None,
         weight=(np.concatenate(all_weight) if all_weight else np.zeros(0, float)),
         centroids=centroids, normalize=normalize, area_weighting=area_weighting,
         fingerprint=grid_fingerprint(latitudes, longitudes),
+        grid_fraction=np.asarray(grid_fraction, dtype=float),
     )
 
 

{meteoraster-3.0 → meteoraster-3.1/meteoraster.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meteoraster
-Version: 3.0
+Version: 3.1
 Summary: Module for handling distributed ensemble and probabilistic forecast data (5-D meteorological rasters)
 Author-email: Jose Pedro Matos <jose.matos@tecnico.ulisboa.pt>
 License-Expression: Apache-2.0
@@ -238,10 +238,19 @@ ts = mr.get_values_from_latlon(lat=35.0, lon=0.0)
 
 ```python
 # agg: DataFrame indexed by production date, columns MultiIndex(zone, leadtime, ensemble_member)
-# centroids: DataFrame of zone centroids (x, y)
+# centroids: DataFrame of zone centroids (x, y) and grid_fraction (share of the zone on the grid)
 agg, centroids = mr.get_values_from_KML("zones.kml", nameField="zone_id")
+
+# v3.0 numbers (square-degree weights) instead of true WGS84 areas
+agg, centroids = mr.get_values_from_KML("zones.kml", nameField="zone_id",
+                                        area_weighting="planar")
 ```
 
+Coordinates are WGS84 lon/lat of cell **centres** (curvilinear 2-D grids included);
+KML edges are straight lines in lon/lat. Weights are true WGS84 areas by default.
+A zone partly outside the grid is averaged over the part inside and warns
+(`on_partial=`); a reused `coverage_info` must match the raster's grid.
+
 Spatial **quantiles** over the same zones, area-weighted so a cell half inside a
 zone carries half the probability mass:
 
@@ -543,6 +552,12 @@ changed for any zone touching the edge of the grid: the legacy builder gave the
 outermost row and column no weight and took its validity threshold from the first
 zone. `ensemble_member` labels are now 0-based, matching the other extractors.
 
+Since **v3.1** the default weights are true WGS84 areas (`area_weighting='ellipsoidal'`)
+instead of square degrees. Square degrees over-weight the poleward side of a zone by
+roughly tan(lat) x lat-span: measured 1 % less rain over a Zambezi-sized basin, 0.02 %
+on the Vesdre catchments, 8 % on a single cell weight for a 5 deg zone at 60 N. Pass
+`area_weighting='planar'` to reproduce v3.0 exactly.
+
 **`meteoraster.zonal`** — needs no `MeteoRaster`; takes plain coordinate arrays.
 
 | Member | Description |
@@ -553,7 +568,8 @@ zone. `ensemble_member` labels are now 0-based, matching the other extractors.
 | `quantiles_from_coverage(coverage, values, quantiles, pool_axes=(), …)` | Area-weighted spatial quantiles per zone. |
 | `weighted_quantiles(values, weights, quantiles, method='hazen')` | The quantile primitive. Reduces exactly to `np.quantile` for equal weights. |
 | `Coverage.save/load`, `Coverage.matches`, `grid_fingerprint` | Persist a coverage to a pickle-free `.npz` and check it against a grid; the fingerprint hashes the coordinates, so a shifted grid of the same shape is a miss. |
-| `cell_corners`, `cell_areas`, `cell_bounds` | The grid geometry, extrapolated half a cell at the boundary so no cell is skipped. |
+| `cell_corners`, `cell_areas`, `cell_bounds` | The grid geometry, extrapolated half a cell at the boundary so no cell is skipped. `cell_areas(..., 'ellipsoidal')` gives km². |
+| `ring_area`, `geometry_area`, `authalic_latitude` | Exact WGS84 areas (km²) of lon/lat rings and ogr polygons, used by `area_weighting='ellipsoidal'`. |
 
 **`meteoraster.io`** — the portable read path.
 

{meteoraster-3.0 → meteoraster-3.1}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "meteoraster"
-version = "3.0"
+version = "3.1"
 description = "Module for handling distributed ensemble and probabilistic forecast data (5-D meteorological rasters)"
 readme = "README.md"
 requires-python = ">=3.11"

{meteoraster-3.0 → meteoraster-3.1}/tests/test_meteo_raster_base.py

@@ -231,7 +231,8 @@ def test_get_values_from_kml_covers_the_grid_border(grid_raster, grid_kml):
 
     pytest.importorskip('osgeo')
 
-    agg, centroids = grid_raster.get_values_from_KML(kml=str(grid_kml), nameField='zone_id')
+    agg, centroids = grid_raster.get_values_from_KML(kml=str(grid_kml), nameField='zone_id',
+                                                     area_weighting='planar')
 
     whole = agg.xs('whole', axis=1, level='zone')
     middle = agg.xs('middle', axis=1, level='zone')

{meteoraster-3.0 → meteoraster-3.1}/tests/test_quantiles.py

@@ -225,3 +225,15 @@ def test_dateoffset_leadtimes_cannot_be_pooled_with_a_rule(two_zone_kml):
         two_zone_kml, nameField='zone_id', quantiles=[1.0],
         pool=('space', 'leadtime'), resampling=None)
     assert aggregate[('whole', 1.0)].iloc[0] == pytest.approx(20.0)
+
+
+def test_a_coverage_for_another_grid_is_rejected(grid_raster, two_zone_kml):
+    _, _, coverage = grid_raster.get_quantiles_from_KML(kml=str(two_zone_kml), nameField='zone_id',
+                                                        getCoverageInfo=True)
+    shifted = grid_raster.copy()
+    shifted.latitudes = shifted.latitudes + 0.25
+
+    with pytest.raises(ValueError, match='different grid'):
+        shifted.get_quantiles_from_KML(kml=str(two_zone_kml), coverage_info=coverage)
+    with pytest.raises(ValueError, match='different grid'):
+        shifted.get_values_from_KML(kml=str(two_zone_kml), coverage_info=coverage)

{meteoraster-3.0 → meteoraster-3.1}/tests/test_zonal.py

@@ -3,11 +3,15 @@ Numeric tests for meteoraster.zonal on a grid whose weights are computable on pa
 
 The 3x3 fixture grid (see conftest) has cells of area exactly 1, spanning
 lon [j-0.5, j+0.5] and lat [2-i-0.5, 2-i+0.5], so every expected weight below is
-an exact fraction rather than a tolerance.
+an exact fraction rather than a tolerance. Those are square-degree weights, so the
+on-paper tests pin area_weighting='planar'; the WGS84 weighting is tested against
+pyproj at the end.
 '''
 
 from __future__ import annotations
 
+import warnings
+
 import numpy as np
 import pandas as pd
 import pytest
@@ -16,6 +20,8 @@ from meteoraster import zonal
 from conftest import (GRID_LATS, GRID_LONS, RING_WHOLE, RING_MIDDLE, RING_WEST_HALF,
                       RING_ONE_AND_QUARTER, gdal_required, write_kml)
 
+PLANAR = dict(area_weighting='planar')
+
 WHOLE_WKT = 'POLYGON ((-0.5 -0.5, 2.5 -0.5, 2.5 2.5, -0.5 2.5, -0.5 -0.5))'
 MIDDLE_WKT = 'POLYGON ((0.5 0.5, 1.5 0.5, 1.5 1.5, 0.5 1.5, 0.5 0.5))'
 WEST_HALF_WKT = 'POLYGON ((-0.5 1.5, 0.0 1.5, 0.0 2.5, -0.5 2.5, -0.5 1.5))'
@@ -79,7 +85,8 @@ def test_as_grid_rejects_a_degenerate_grid():
 
 @gdal_required
 def test_whole_grid_zone_catches_every_cell_including_the_corners():
-    coverage = zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [WHOLE_WKT], ['all'])
+    coverage = zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [WHOLE_WKT], ['all'],
+                                              **PLANAR)
 
     index, weight = coverage.cells(0)
 
@@ -174,7 +181,8 @@ def test_halo_does_not_change_the_weights():
 @gdal_required
 def test_cos_lat_weighting_rescales_but_keeps_a_uniform_field():
     values = np.full((1, 3, 3), 4.0)
-    planar = zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [WHOLE_WKT], ['all'])
+    planar = zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [WHOLE_WKT], ['all'],
+                                            **PLANAR)
     scaled = zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [WHOLE_WKT], ['all'],
                                            area_weighting='cos_lat')
 
@@ -269,7 +277,8 @@ def test_polygon_with_a_hole(tmp_path):
         '</coordinates></LinearRing></innerBoundaryIs>'
         '</Polygon></Placemark></Document></kml>\n', encoding='utf-8')
 
-    coverage = zonal.coverage_from_kml(path, GRID_LATS, GRID_LONS, name_field='zone_id')
+    coverage = zonal.coverage_from_kml(path, GRID_LATS, GRID_LONS, name_field='zone_id',
+                                       **PLANAR)
 
     index, weight = coverage.cells(0)
     assert 4 not in index.tolist()          # the centre cell is the hole
@@ -299,7 +308,8 @@ def test_name_field_falls_back_to_the_name_element(tmp_path):
 
 @gdal_required
 def test_area_weighted_mean_uses_the_whole_grid():
-    coverage = zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [WHOLE_WKT], ['all'])
+    coverage = zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [WHOLE_WKT], ['all'],
+                                              **PLANAR)
     values = np.arange(9, dtype=float).reshape(1, 3, 3)
 
     # mean(0..8) = 4.0, not the centre cell's 4 by coincidence: see the asymmetric
@@ -318,7 +328,8 @@ def test_weighted_mean_of_partial_cells():
 
 @gdal_required
 def test_missing_data_is_renormalised_per_zone():
-    coverage = zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [WHOLE_WKT], ['all'])
+    coverage = zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [WHOLE_WKT], ['all'],
+                                              **PLANAR)
     values = np.arange(9, dtype=float).reshape(1, 3, 3)
 
     values[0, 0, 0] = np.nan
@@ -567,3 +578,111 @@ def test_quantiles_from_coverage_respects_min_coverage():
     got = zonal.quantiles_from_coverage(coverage, values, [0.5], min_coverage=0.8)
 
     assert np.isnan(got[0, 0, 0])
+
+
+# --------------------------------------------------------------------------- #
+# WGS84 area weighting, grid fraction, reuse checks
+# --------------------------------------------------------------------------- #
+
+def _geod_rectangle_km2(west, east, south, north):
+    '''pyproj area of a lon/lat rectangle, parallels densified so geodesic == straight.'''
+    pyproj = pytest.importorskip('pyproj')
+    t = np.linspace(0.0, 1.0, 400)
+    lons = np.concatenate([west + (east - west) * t, np.full(t.size, east),
+                           east - (east - west) * t, np.full(t.size, west)])
+    lats = np.concatenate([np.full(t.size, south), south + (north - south) * t,
+                           np.full(t.size, north), north - (north - south) * t])
+    area, _ = pyproj.Geod(ellps='WGS84').polygon_area_perimeter(lons, lats)
+    return abs(area) / 1e6
+
+
+@pytest.mark.parametrize('south', [-89.0, -45.0, 0.0, 30.0, 60.0, 75.0, 88.0])
+def test_ellipsoidal_ring_area_matches_pyproj(south):
+    expected = _geod_rectangle_km2(10.0, 12.0, south, south + 1)
+
+    area = zonal.ring_area(np.array([10.0, 12.0, 12.0, 10.0]),
+                           np.array([south, south, south + 1, south + 1]))
+
+    assert area == pytest.approx(expected, rel=1e-6)
+
+
+def test_ellipsoidal_cell_areas_are_true_areas():
+    lats = np.array([60.5, 60.0, 59.5])
+    lons = np.array([0.0, 0.5, 1.0])
+    corner_lat, corner_lon = zonal.cell_corners(lats, lons)
+
+    areas = zonal.cell_areas(corner_lat, corner_lon, 'ellipsoidal')
+
+    assert areas[0, 0] == pytest.approx(_geod_rectangle_km2(-0.25, 0.25, 60.25, 60.75), rel=1e-6)
+    assert areas[2, 0] == pytest.approx(_geod_rectangle_km2(-0.25, 0.25, 59.25, 59.75), rel=1e-6)
+
+
+@gdal_required
+def test_ellipsoidal_is_the_default_and_planar_reproduces_v30():
+    lats = np.arange(70.0, 49.0, -1.0)
+    lons = np.arange(0.0, 6.0, 1.0)
+    wkt = 'POLYGON ((0.3 50.3, 5.3 50.3, 5.3 69.3, 0.3 69.3, 0.3 50.3))'
+    field = np.broadcast_to(np.meshgrid(lons, lats)[1], (1,) + (lats.size, lons.size))
+
+    default = zonal.coverage_from_geometries(lats, lons, [wkt], ['z'])
+    planar = zonal.coverage_from_geometries(lats, lons, [wkt], ['z'], area_weighting='planar')
+
+    assert default.area_weighting == 'ellipsoidal'
+    # planar is the plain-degree centroid; true areas pull it south (cos lat)
+    planar_mean = zonal.apply_coverage(planar, field)[0, 0]
+    true_mean = zonal.apply_coverage(default, field)[0, 0]
+    assert planar_mean == pytest.approx(59.8, abs=1e-6)
+    assert true_mean < planar_mean - 0.5
+
+
+@gdal_required
+def test_grid_fraction_reports_a_zone_partly_outside_the_grid():
+    half_out = 'POLYGON ((1.5 -0.5, 3.5 -0.5, 3.5 2.5, 1.5 2.5, 1.5 -0.5))'
+
+    with pytest.warns(UserWarning, match='partly outside the grid'):
+        coverage = zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [WHOLE_WKT, half_out],
+                                                  ['all', 'half'])
+
+    np.testing.assert_allclose(coverage.grid_fraction, [1.0, 0.5], rtol=1e-3)
+    assert coverage.centroids.loc['half', 'grid_fraction'] == pytest.approx(0.5, rel=1e-3)
+
+    with pytest.raises(ValueError, match='partly outside the grid'):
+        zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [half_out], ['half'],
+                                       on_partial='raise')
+
+
+@gdal_required
+def test_a_zone_on_the_grid_border_is_fully_inside():
+    with warnings.catch_warnings():
+        warnings.simplefilter('error')
+        coverage = zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [WHOLE_WKT, QUARTER_WKT],
+                                                  ['all', 'quarter'])
+
+    np.testing.assert_allclose(coverage.grid_fraction, 1.0)
+
+
+@gdal_required
+def test_an_antimeridian_polygon_warns():
+    lats = np.array([56.0, 55.0, 54.0])
+    lons = np.array([178.0, 179.0, 180.0])
+    with pytest.warns(UserWarning, match='antimeridian'):
+        zonal.coverage_from_geometries(
+            lats, lons, ['POLYGON ((179 54.5, -179 54.5, -179 55.5, 179 55.5, 179 54.5))'],
+            ['dateline'], on_partial='ignore')
+
+
+@gdal_required
+def test_grid_fraction_round_trips_and_old_files_still_load(tmp_path):
+    coverage = zonal.coverage_from_geometries(GRID_LATS, GRID_LONS, [WHOLE_WKT], ['all'])
+    coverage.save(tmp_path / 'new.npz')
+    back = zonal.Coverage.load(tmp_path / 'new.npz')
+    np.testing.assert_allclose(back.grid_fraction, coverage.grid_fraction)
+    assert 'grid_fraction' in back.centroids.columns
+
+    # a v3.0 file has no grid_fraction key
+    coverage.grid_fraction = None
+    coverage.save(tmp_path / 'old.npz')
+    old = zonal.Coverage.load(tmp_path / 'old.npz')
+    assert old.grid_fraction is None
+    np.testing.assert_allclose(old.weight, coverage.weight)
+