cavapy 2.0.7__tar.gz → 2.1.0__tar.gz

{cavapy-2.0.7 → cavapy-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cavapy
-Version: 2.0.7
+Version: 2.1.0
 Summary: CAVA Python package. Retrive climate data.
 License: Apache-2.0
 License-File: LICENSE
@@ -8,7 +8,6 @@ Author: Riccardo Soldan
 Author-email: riccardosoldan@hotmail.it
 Requires-Python: >=3.11,<4.0
 Classifier: License :: OSI Approved :: Apache Software License
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -338,6 +337,6 @@ For advanced visualization and reporting, see [CAVAanalytics](https://risk-team.
 
 ## Citation and License
 
-- License: [MIT](LICENSE)
+- License: [Apache 2.0](LICENSE)
 - Package metadata and build details: [pyproject.toml](pyproject.toml)
 

{cavapy-2.0.7 → cavapy-2.1.0}/README.md

@@ -307,5 +307,5 @@ For advanced visualization and reporting, see [CAVAanalytics](https://risk-team.
 
 ## Citation and License
 
-- License: [MIT](LICENSE)
+- License: [Apache 2.0](LICENSE)
 - Package metadata and build details: [pyproject.toml](pyproject.toml)

{cavapy-2.0.7 → cavapy-2.1.0}/cavapy/cava_config.py

@@ -13,17 +13,18 @@ except ImportError:
     warnings.filterwarnings("ignore", category=UserWarning, module="cartopy.io")
 
 logger = logging.getLogger("climate")
-logger.handlers = []  # Remove any existing handlers
-handler = logging.StreamHandler()
-formatter = logging.Formatter(
-    "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
-    datefmt="%H:%M:%S",
-)
-handler.setFormatter(formatter)
-for hdlr in logger.handlers[:]:  # remove all old handlers
-    logger.removeHandler(hdlr)
-logger.addHandler(handler)
-logger.setLevel(logging.DEBUG)
+# Progress messages are part of the tool's UX, so a console handler is attached
+# by default -- but only when the host application has not already configured
+# this logger, and without touching handlers installed by the host.
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter(
+        "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
 
 VARIABLES_MAP = {
     "pr": "tp",
@@ -45,6 +46,7 @@ VALID_DOMAINS = [
     "AUS-22",
     "SAM-22",
     "CAM-22",
+    "CAS-22",
 ]
 VALID_RCPS = ["rcp26", "rcp85"]
 VALID_GCM = ["MOHC", "MPI", "NCC"]

{cavapy-2.0.7 → cavapy-2.1.0}/cavapy/cava_download.py

@@ -18,12 +18,10 @@ from .cava_config import (
     DEFAULT_YEARS_OBS,
     ERA5_DATA_LOCAL_PATH,
     ERA5_DATA_REMOTE_URL,
-    INVENTORY_DATA_LOCAL_PATH,
-    INVENTORY_DATA_REMOTE_URL,
     VARIABLES_MAP,
     logger,
 )
-from .cava_validation import _ensure_inventory_not_empty
+from .cava_validation import _filter_inventory
 
 
 SPATIAL_COORDS = {
@@ -68,6 +66,64 @@ def _suppress_stderr_fd():
         os.close(saved_fd)
 
 
+def _ensure_geographic_grid(ds: xr.Dataset, data: xr.DataArray, url: str) -> None:
+    """Fail fast when a file's 1-D coordinates are not geographic degrees.
+
+    Some server-side files carry 1-D 'longitude'/'latitude' coordinates that
+    are actually rotated-pole degrees or projected meters, with the true
+    geographic coordinates stored as 2-D 'lat'/'lon' arrays. Subsetting such
+    files by degrees would silently return data for the wrong region. The
+    check is value-based, so it stops firing automatically once the files are
+    interpolated to a regular grid, whatever their metadata says.
+    """
+    problems = []
+
+    lat = data.coords.get("latitude")
+    lon = data.coords.get("longitude")
+
+    # Projected coordinates (meters) are far outside any degree range.
+    if lat is not None and (np.abs(np.asarray(lat.values, dtype=float)) > 90).any():
+        problems.append("1-D latitude values outside [-90, 90]")
+    if lon is not None:
+        lon_values = np.asarray(lon.values, dtype=float)
+        if (lon_values < -180).any() or (lon_values > 360).any():
+            problems.append("1-D longitude values outside [-180, 360]")
+
+    # Rotated-pole coordinates look like plausible degrees, but such files also
+    # carry 2-D geographic 'lat' arrays that disagree with the 1-D axis.
+    if (
+        not problems
+        and lat is not None
+        and "lat" in ds.variables
+        and ds["lat"].ndim == 2
+    ):
+        deviation = float(np.abs(ds["lat"] - lat).max())
+        if deviation > 1.0:
+            problems.append(
+                "2-D geographic 'lat' deviates from the 1-D latitude axis "
+                f"by up to {deviation:.1f} degrees"
+            )
+
+    if problems:
+        raise ValueError(
+            f"Dataset is not on a regular longitude/latitude grid "
+            f"({'; '.join(problems)}): {url}\n"
+            "Subsetting it by geographic coordinates would return data for the "
+            "wrong region. This is a server-side issue with this file: it "
+            "needs to be interpolated to a regular grid like the other domains."
+        )
+
+
+def _floor_time_to_day(data: xr.DataArray) -> xr.DataArray:
+    """Drop the time-of-day component from the time axis.
+
+    ERA5 stamps daily values at 00:00 while CORDEX models use 12:00, and
+    xsdba requires identical time arrays between the reference and the
+    training data.
+    """
+    return data.assign_coords(time=data["time"].dt.floor("D"))
+
+
 def _coordinate_slice(coord: xr.DataArray, bounds: tuple[float, float]) -> slice:
     """Build a label slice matching the coordinate's native order."""
     values = np.asarray(coord.values, dtype=float)
@@ -193,41 +249,6 @@ def _climate_data_for_variable(
     """Fetch and process one variable, optionally bias-correcting and merging runs."""
     log = logger.getChild(variable)
 
-    pd.options.mode.chained_assignment = None
-    inventory_csv_url = (
-        INVENTORY_DATA_REMOTE_URL if remote else INVENTORY_DATA_LOCAL_PATH
-    )
-    data = pd.read_csv(inventory_csv_url)
-    column_to_use = "location" if remote else "hub"
-
-    # Filter data based on whether we need historical data
-    experiments = [rcp]
-    if historical or bias_correction:
-        experiments.append("historical")
-
-    # Determine activity filter based on dataset
-    activity_filter = "FAO" if dataset == "CORDEX-CORE" else "CRDX-ISIMIP-025"
-
-    filtered_data = data[
-        lambda x: (x["activity"].str.contains(activity_filter, na=False))
-        & (x["domain"] == cordex_domain)
-        & (x["model"].str.contains(gcm, na=False))
-        & (x["rcm"].str.contains(rcm, na=False))
-        & (x["experiment"].isin(experiments))
-    ][["experiment", column_to_use]]
-
-    # Fail early if nothing is found
-    _ensure_inventory_not_empty(
-        filtered_data,
-        dataset=dataset,
-        cordex_domain=cordex_domain,
-        gcm=gcm,
-        rcm=rcm,
-        experiments=experiments,
-        activity_filter=activity_filter,
-        log=log,
-    )
-
     future_obs = None
     if obs or bias_correction:
         future_obs = executor.submit(
@@ -246,6 +267,21 @@ def _climate_data_for_variable(
         )
 
     if not obs:
+        # Which experiments we need from the inventory
+        experiments = [rcp]
+        if historical or bias_correction:
+            experiments.append("historical")
+
+        filtered_data, column_to_use = _filter_inventory(
+            remote=remote,
+            dataset=dataset,
+            cordex_domain=cordex_domain,
+            gcm=gcm,
+            rcm=rcm,
+            experiments=experiments,
+            log=log,
+        )
+
         download_fn = partial(
             _thread_download_data,
             bbox=bbox,
@@ -283,6 +319,9 @@ def _climate_data_for_variable(
         if bias_correction and historical:
             # Load observations for bias correction
             ref = future_obs.result()
+            ref = _floor_time_to_day(ref)
+            hist = _floor_time_to_day(hist)
+            proj = _floor_time_to_day(proj)
             log.info("Training eqm with leave-one-out cross-validation")
 
             # Use leave-one-out cross-validation for historical bias correction
@@ -314,10 +353,16 @@ def _climate_data_for_variable(
         elif bias_correction and not historical:
             # Load observations for bias correction
             ref = future_obs.result()
+            ref = _floor_time_to_day(ref)
+            hist = _floor_time_to_day(hist)
+            proj = _floor_time_to_day(proj)
             log.info("Performing bias correction with eqm")
+            # Train on the historical run, which overlaps the ERA5 reference period.
+            # Training on the projection would fold the climate-change signal into
+            # the estimated bias and remove it from the corrected output.
             QM_mo = sdba.EmpiricalQuantileMapping.train(
                 ref,
-                proj,
+                hist,
                 group="time.month",
                 kind="*" if variable in ["pr", "rsds", "sfcWind"] else "+",
             )
@@ -496,6 +541,8 @@ def _download_data(
                 log.exception(msg)
                 raise ValueError(msg)
 
+            _ensure_geographic_grid(ds, ds_var, url)
+
             log.info("Connection established")
             ds_cropped = _select_spatial_subset(ds_var, bbox, log)
 

{cavapy-2.0.7 → cavapy-2.1.0}/cavapy/cava_plot.py

@@ -49,7 +49,11 @@ def plot_spatial_map(
         raise ValueError(f"Unsupported aggregation method: {aggregation}")
 
     # Create figure with cartopy
-    fig, ax = plt.subplots(figsize=figsize, subplot_kw={"projection": ccrs.PlateCarree()})
+    fig, ax = plt.subplots(
+        figsize=figsize,
+        layout="constrained",
+        subplot_kw={"projection": ccrs.PlateCarree()},
+    )
 
     # Plot data
     im = plot_data.plot(
@@ -84,7 +88,7 @@ def plot_spatial_map(
     gl.bottom_labels = True
 
     # Add colorbar
-    cbar = plt.colorbar(im, ax=ax, shrink=0.8, pad=0.02)
+    cbar = fig.colorbar(im, ax=ax, shrink=0.8, pad=0.02)
     if hasattr(plot_data, "units"):
         cbar.set_label(
             f"{plot_data.name} ({plot_data.units})", rotation=270, labelpad=20
@@ -100,12 +104,11 @@ def plot_spatial_map(
         else:
             title = f"{aggregation.title()} {var_name}"
 
-    ax.set_title(title, fontsize=14, pad=20)
-
-    plt.tight_layout()
+    # Avoid Cartopy's gridliner-based title repositioning producing non-finite bounds.
+    ax.set_title(title, fontsize=14, pad=20, y=1.0)
 
     if save_path:
-        plt.savefig(save_path, dpi=300, bbox_inches="tight")
+        fig.savefig(save_path, dpi=300, bbox_inches="tight")
 
     return fig
 

{cavapy-2.0.7 → cavapy-2.1.0}/cavapy/cava_validation.py

@@ -1,6 +1,7 @@
 """Validation helpers for input parameters and spatial domain checks."""
 
 import logging
+from functools import lru_cache
 
 import pandas as pd
 import cartopy.feature as cfeature
@@ -53,6 +54,68 @@ def _ensure_inventory_not_empty(
     raise ValueError(msg)
 
 
+@lru_cache(maxsize=None)
+def _read_inventory(csv_path_or_url: str) -> pd.DataFrame:
+    """Read the inventory CSV once per process and reuse it across requests."""
+    return pd.read_csv(csv_path_or_url)
+
+
+def _filter_inventory(
+    *,
+    remote: bool,
+    dataset: str,
+    cordex_domain: str,
+    gcm: str,
+    rcm: str,
+    experiments: list[str],
+    log: logging.Logger | None = None,
+) -> tuple[pd.DataFrame, str]:
+    """
+    Return the inventory rows matching the request and the URL column to use.
+
+    Raises:
+        ValueError: If no rows match, or if more than one dataset matches a
+            single experiment (the download path uses exactly one per experiment).
+    """
+    inventory_csv_url = (
+        INVENTORY_DATA_REMOTE_URL if remote else INVENTORY_DATA_LOCAL_PATH
+    )
+    data = _read_inventory(inventory_csv_url)
+    column_to_use = "location" if remote else "hub"
+    activity_filter = "FAO" if dataset == "CORDEX-CORE" else "CRDX-ISIMIP-025"
+
+    filtered_data = data[
+        (data["activity"].str.contains(activity_filter, na=False))
+        & (data["domain"] == cordex_domain)
+        & (data["model"].str.contains(gcm, na=False))
+        & (data["rcm"].str.contains(rcm, na=False))
+        & (data["experiment"].isin(experiments))
+    ][["experiment", column_to_use]].copy()
+
+    _ensure_inventory_not_empty(
+        filtered_data,
+        dataset=dataset,
+        cordex_domain=cordex_domain,
+        gcm=gcm,
+        rcm=rcm,
+        experiments=experiments,
+        activity_filter=activity_filter,
+        log=log,
+    )
+
+    experiment_counts = filtered_data["experiment"].value_counts()
+    ambiguous = experiment_counts[experiment_counts > 1]
+    if not ambiguous.empty:
+        raise ValueError(
+            f"Ambiguous inventory match for domain={cordex_domain}, gcm={gcm}, "
+            f"rcm={rcm}: multiple datasets found for experiment(s) "
+            f"{sorted(ambiguous.index)}. Please report this at "
+            "https://github.com/un-fao/cavapy/issues"
+        )
+
+    return filtered_data, column_to_use
+
+
 def _validate_urls(
     gcm: str = None,
     rcm: str = None,
@@ -70,42 +133,18 @@ def _validate_urls(
     log = logger.getChild("URL-validation")
 
     if obs is False:
-        inventory_csv_url = (
-            INVENTORY_DATA_REMOTE_URL if remote else INVENTORY_DATA_LOCAL_PATH
-        )
-        data = pd.read_csv(inventory_csv_url)
-
-        # Set the column to use based on whether the data is remote or local
-        column_to_use = "location" if remote else "hub"
-
         # Define which experiments we need
         experiments = [rcp]
         if historical or bias_correction:
             experiments.append("historical")
 
-        # Determine activity filter based on dataset
-        activity_filter = "FAO" if dataset == "CORDEX-CORE" else "CRDX-ISIMIP-025"
-
-        # Filter the data based on the conditions
-        filtered_data = data[
-            lambda x: (
-                x["activity"].str.contains(activity_filter, na=False)
-                & (x["domain"] == cordex_domain)
-                & (x["model"].str.contains(gcm, na=False))
-                & (x["rcm"].str.contains(rcm, na=False))
-                & (x["experiment"].isin(experiments))
-            )
-        ][["experiment", column_to_use]]
-
-        # Fail early if nothing is found
-        _ensure_inventory_not_empty(
-            filtered_data,
+        filtered_data, column_to_use = _filter_inventory(
+            remote=remote,
             dataset=dataset,
             cordex_domain=cordex_domain,
             gcm=gcm,
             rcm=rcm,
             experiments=experiments,
-            activity_filter=activity_filter,
             log=log,
         )
 
@@ -232,6 +271,19 @@ def _validate_gcm_rcm_combinations(cordex_domain: str, gcm: str, rcm: str):
             ("MPI", "Reg"),
             ("NCC", "Reg"),
         ],
+        "EUR-22": [
+            ("MOHC", "Reg"),  # Only REMO runs exist for EUR-22
+            ("MPI", "Reg"),
+            ("NCC", "Reg"),
+        ],
+        "NAM-22": [
+            ("MOHC", "Reg"),  # Only REMO runs exist for NAM-22
+            ("MPI", "Reg"),
+            ("NCC", "Reg"),
+        ],
+        "CAM-22": [
+            ("NCC", "Reg"),  # CAM-22 pairs RegCM4-7 with NOAA-GFDL, not NorESM
+        ],
     }
 
     if cordex_domain in invalid_combinations:
@@ -255,105 +307,54 @@ def _validate_gcm_rcm_combinations(cordex_domain: str, gcm: str, rcm: str):
             )
 
 
+# Geographic extents (min_lon, min_lat, max_lon, max_lat) of the regridded
+# 0.25-degree products served on THREDDS, measured from the datasets themselves
+# (August 2026). No served domain crosses the antimeridian: AUS-22 and EAS-22
+# are clipped at 180 degrees East.
+CORDEX_DOMAIN_EXTENTS = {
+    "NAM-22": (-171.75, 12.25, -22.25, 76.25),
+    "EUR-22": (-44.75, 22.00, 65.00, 72.50),
+    "SEA-22": (89.25, -15.25, 147.00, 26.50),
+    "AUS-22": (86.25, -53.25, 180.00, 12.75),
+    "WAS-22": (19.25, -15.75, 116.25, 45.75),
+    "EAS-22": (44.75, 0.25, 179.75, 62.25),
+    "SAM-22": (-106.25, -58.25, -16.25, 18.75),
+    "CAM-22": (-124.75, -19.75, -21.75, 35.25),
+    "AFR-22": (-24.25, -46.25, 59.75, 42.75),
+    "CAS-22": (10.75, 17.75, 140.25, 69.75),
+}
+
+
 def _validate_cordex_domain(xlim, ylim, cordex_domain):
     """Ensure the bbox is fully contained inside the selected CORDEX domain."""
-    # CORDEX domains data
-    cordex_domains_df = pd.DataFrame(
-        {
-            "min_lon": [
-                -33,
-                -28.3,
-                89.25,
-                86.75,
-                19.25,
-                44.0,
-                -106.25,
-                -115.0,
-                -24.25,
-                10.75,
-            ],
-            "min_lat": [
-                -28,
-                -23,
-                -15.25,
-                -54.25,
-                -15.75,
-                -4.0,
-                -58.25,
-                -14.5,
-                -46.25,
-                17.75,
-            ],
-            "max_lon": [
-                20,
-                18,
-                147.0,
-                -152.75,
-                116.25,
-                -172.0,
-                -16.25,
-                -30.5,
-                59.75,
-                140.25,
-            ],
-            "max_lat": [
-                28,
-                21.7,
-                26.5,
-                13.75,
-                45.75,
-                65.0,
-                18.75,
-                28.5,
-                42.75,
-                69.75,
-            ],
-            "cordex_domain": [
-                "NAM-22",
-                "EUR-22",
-                "SEA-22",
-                "AUS-22",
-                "WAS-22",
-                "EAS-22",
-                "SAM-22",
-                "CAM-22",
-                "AFR-22",
-                "CAS-22",
-            ],
-        }
-    )
+    if cordex_domain not in CORDEX_DOMAIN_EXTENTS:
+        raise ValueError(f"CORDEX domain '{cordex_domain}' is not recognized.")
 
-    def is_bbox_contained(bbox, domain):
-        """Check if bbox is contained within the domain bounding box."""
+    def is_bbox_contained(bbox, extent):
+        min_lon, min_lat, max_lon, max_lat = extent
         return (
-            bbox[0] >= domain["min_lon"]
-            and bbox[1] >= domain["min_lat"]
-            and bbox[2] <= domain["max_lon"]
-            and bbox[3] <= domain["max_lat"]
+            bbox[0] >= min_lon
+            and bbox[1] >= min_lat
+            and bbox[2] <= max_lon
+            and bbox[3] <= max_lat
         )
 
     user_bbox = [xlim[0], ylim[0], xlim[1], ylim[1]]
-    domain_row = cordex_domains_df[cordex_domains_df["cordex_domain"] == cordex_domain]
-
-    if domain_row.empty:
-        raise ValueError(f"CORDEX domain '{cordex_domain}' is not recognized.")
-
-    domain_bbox = domain_row.iloc[0]
-
-    if not is_bbox_contained(user_bbox, domain_bbox):
-        suggested_domains = cordex_domains_df[
-            cordex_domains_df.apply(
-                lambda row: is_bbox_contained(user_bbox, row), axis=1
-            )
-        ]
 
-        if suggested_domains.empty:
-            raise ValueError(
-                f"The bounding box {user_bbox} is outside of all available CORDEX domains."
-            )
+    if is_bbox_contained(user_bbox, CORDEX_DOMAIN_EXTENTS[cordex_domain]):
+        return
 
-        suggested_domain = suggested_domains.iloc[0]["cordex_domain"]
+    suggested_domains = [
+        domain
+        for domain, extent in CORDEX_DOMAIN_EXTENTS.items()
+        if is_bbox_contained(user_bbox, extent)
+    ]
 
+    if not suggested_domains:
         raise ValueError(
-            f"Bounding box {user_bbox} is not within '{cordex_domain}'. Suggested domain: '{suggested_domain}'."
+            f"The bounding box {user_bbox} is outside of all available CORDEX domains."
         )
+
+    raise ValueError(
+        f"Bounding box {user_bbox} is not within '{cordex_domain}'. Suggested domain: '{suggested_domains[0]}'."
+    )

{cavapy-2.0.7 → cavapy-2.1.0}/cavapy/cavapy.py

@@ -31,7 +31,7 @@ from .cava_validation import (
 
 _ANNOUNCEMENTS_ATTEMPTED = False
 _ANNOUNCEMENTS_ENV_DISABLE = "CAVAPY_NO_ANNOUNCEMENTS"
-_GITHUB_ISSUES_URL = "https://api.github.com/repos/Risk-Team/cavapy/issues"
+_GITHUB_ISSUES_URL = "https://api.github.com/repos/un-fao/cavapy/issues"
 _ANNOUNCEMENTS_LABEL = "announcement"
 _ANNOUNCEMENTS_TIMEOUT_S = 2
 _ANNOUNCEMENTS_PER_PAGE = 20

{cavapy-2.0.7 → cavapy-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cavapy"
-version = "2.0.7"
+version = "2.1.0"
 description = "CAVA Python package. Retrive climate data."
 authors = ["Riccardo Soldan <riccardosoldan@hotmail.it>", "Oleh Lokshyn <olokshyn@gmail.com>"]
 readme = "README.md"
@@ -8,7 +8,7 @@ license = "Apache-2.0"
 repository = "https://github.com/un-fao/cavapy"
 classifiers = [
     "Programming Language :: Python :: 3",
-    "License :: OSI Approved :: MIT License",
+    "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
 ]