cavapy 2.1.3__tar.gz → 2.1.4__tar.gz

{cavapy-2.1.3 → cavapy-2.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cavapy
-Version: 2.1.3
+Version: 2.1.4
 Summary: CAVA Python package. Retrive climate data.
 License: Apache-2.0
 License-File: LICENSE
@@ -77,6 +77,12 @@ A single `get_climate_data()` call orchestrates a full pipeline:
 | **Bias correction** | ERA5 is automatically fetched as the reference; EQM is trained and applied — no external tools needed |
 | **Domain validation** | If your bounding box falls outside the chosen CORDEX domain, a corrected domain is suggested |
 
+Unit conversion is enabled by default for backward compatibility. Pass
+`convert_units=False` to keep the values and `units` metadata provided by the
+source (for example, temperature in kelvin). This option cannot be combined
+with `bias_correction=True`, because raw ERA5 and CORDEX units are not directly
+compatible for every variable.
+
 ---
 
 ## Data Coverage

{cavapy-2.1.3 → cavapy-2.1.4}/README.md

@@ -47,6 +47,12 @@ A single `get_climate_data()` call orchestrates a full pipeline:
 | **Bias correction** | ERA5 is automatically fetched as the reference; EQM is trained and applied — no external tools needed |
 | **Domain validation** | If your bounding box falls outside the chosen CORDEX domain, a corrected domain is suggested |
 
+Unit conversion is enabled by default for backward compatibility. Pass
+`convert_units=False` to keep the values and `units` metadata provided by the
+source (for example, temperature in kelvin). This option cannot be combined
+with `bias_correction=True`, because raw ERA5 and CORDEX units are not directly
+compatible for every variable.
+
 ---
 
 ## Data Coverage

{cavapy-2.1.3 → cavapy-2.1.4}/cavapy/cava_download.py

@@ -242,6 +242,7 @@ def _climate_data_for_variable(
     bias_correction: bool,
     historical: bool,
     remote: bool,
+    convert_units: bool = True,
     dataset: str = "CORDEX-CORE",
     retry_log_level: int = logging.WARNING,
 ) -> xr.DataArray:
@@ -262,6 +263,7 @@ def _climate_data_for_variable(
             gcm=gcm,
             rcm=rcm,
             rcp=rcp,
+            convert_units=convert_units,
             retry_log_level=retry_log_level,
         )
 
@@ -292,6 +294,7 @@ def _climate_data_for_variable(
             gcm=gcm,
             rcm=rcm,
             rcp=rcp,
+            convert_units=convert_units,
             retry_log_level=retry_log_level,
         )
         downloaded_models = list(
@@ -412,6 +415,7 @@ def _download_data(
     gcm: str,
     rcm: str,
     rcp: str,
+    convert_units: bool = True,
     retry_log_level: int = logging.WARNING,
 ) -> xr.DataArray:
     """Download a dataset, subset it to the bbox, and perform unit/calendar handling."""
@@ -556,35 +560,36 @@ def _download_data(
                 else:
                     raise
 
-        if obs:
-            if var in ["t2mx", "t2mn", "t2m"]:
-                ds_cropped -= 273.15  # Convert from Kelvin to Celsius
-                ds_cropped.attrs["units"] = "°C"
-            elif var == "tp":
-                ds_cropped *= 1000  # Convert precipitation
-                ds_cropped.attrs["units"] = "mm"
-            elif var == "ssrd":
-                ds_cropped /= 86400  # Convert from J/m^2 to W/m^2
-                ds_cropped.attrs["units"] = "W m-2"
-            elif var == "sfcwind":
-                ds_cropped = ds_cropped * (
-                    4.87 / np.log((67.8 * 10) - 5.42)
-                )  # Convert wind speed from 10 m to 2 m
-                ds_cropped.attrs["units"] = "m s-1"
-        else:
-            if variable in ["tas", "tasmax", "tasmin"]:
-                ds_cropped -= 273.15  # Convert from Kelvin to Celsius
-                ds_cropped.attrs["units"] = "°C"
-            elif variable == "pr":
-                ds_cropped *= 86400  # Convert from kg m^-2 s^-1 to mm/day
-                ds_cropped.attrs["units"] = "mm"
-            elif variable == "rsds":
-                ds_cropped.attrs["units"] = "W m-2"
-            elif variable == "sfcWind":
-                ds_cropped = ds_cropped * (
-                    4.87 / np.log((67.8 * 10) - 5.42)
-                )  # Convert wind speed from 10 m to 2 m
-                ds_cropped.attrs["units"] = "m s-1"
+        if convert_units:
+            if obs:
+                if var in ["t2mx", "t2mn", "t2m"]:
+                    ds_cropped -= 273.15  # Convert from Kelvin to Celsius
+                    ds_cropped.attrs["units"] = "°C"
+                elif var == "tp":
+                    ds_cropped *= 1000  # Convert precipitation
+                    ds_cropped.attrs["units"] = "mm"
+                elif var == "ssrd":
+                    ds_cropped /= 86400  # Convert from J/m^2 to W/m^2
+                    ds_cropped.attrs["units"] = "W m-2"
+                elif var == "sfcwind":
+                    ds_cropped = ds_cropped * (
+                        4.87 / np.log((67.8 * 10) - 5.42)
+                    )  # Convert wind speed from 10 m to 2 m
+                    ds_cropped.attrs["units"] = "m s-1"
+            else:
+                if variable in ["tas", "tasmax", "tasmin"]:
+                    ds_cropped -= 273.15  # Convert from Kelvin to Celsius
+                    ds_cropped.attrs["units"] = "°C"
+                elif variable == "pr":
+                    ds_cropped *= 86400  # Convert from kg m^-2 s^-1 to mm/day
+                    ds_cropped.attrs["units"] = "mm"
+                elif variable == "rsds":
+                    ds_cropped.attrs["units"] = "W m-2"
+                elif variable == "sfcWind":
+                    ds_cropped = ds_cropped * (
+                        4.87 / np.log((67.8 * 10) - 5.42)
+                    )  # Convert wind speed from 10 m to 2 m
+                    ds_cropped.attrs["units"] = "m s-1"
 
         # Fetch only the requested years, inside the retry loop; downstream
         # time-core operations (interpolate_na, bias correction) need it in memory.
@@ -615,12 +620,14 @@ def _download_data(
         raise last_exc
 
     if obs:
+        unit_handling = "unit conversion" if convert_units else "source units retained"
         log.info(
-            f"ERA5 data for {variable} has been processed: unit conversion ({ds_cropped.attrs.get('units', 'unknown units')}), time selection ({min(years)}-{max(years)})"
+            f"ERA5 data for {variable} has been processed: {unit_handling} ({ds_cropped.attrs.get('units', 'unknown units')}), time selection ({min(years)}-{max(years)})"
         )
     else:
+        unit_handling = "unit conversion" if convert_units else "source units retained"
         log.info(
-            f"CORDEX data for {variable} has been processed: unit conversion ({ds_cropped.attrs.get('units', 'unknown units')}), calendar transformation (360-day to Gregorian), time selection ({years[0]}-{years[-1]})"
+            f"CORDEX data for {variable} has been processed: {unit_handling} ({ds_cropped.attrs.get('units', 'unknown units')}), calendar transformation (360-day to Gregorian), time selection ({years[0]}-{years[-1]})"
         )
 
     return ds_cropped

{cavapy-2.1.3 → cavapy-2.1.4}/cavapy/cavapy.py

@@ -116,6 +116,7 @@ def _get_climate_data_single(
     xlim: tuple[float, float] | None = None,
     ylim: tuple[float, float] | None = None,
     remote: bool = True,
+    convert_units: bool = True,
     variables: list[str] | None = None,
     num_processes: int = len(VALID_VARIABLES),
     max_threads_per_process: int = 3,
@@ -186,6 +187,11 @@ def _get_climate_data_single(
             "Cannot apply bias_correction=True when using dataset='CORDEX-CORE-BC'. "
             "The CORDEX-CORE-BC dataset is already bias-corrected using ISIMIP methodology."
         )
+    if bias_correction and not convert_units:
+        raise ValueError(
+            "convert_units=False cannot be used with bias_correction=True because "
+            "ERA5 and CORDEX source units are not directly compatible."
+        )
     
     # Validate variables if provided
     if variables is not None:
@@ -234,6 +240,7 @@ def _get_climate_data_single(
                     bias_correction=bias_correction,
                     historical=historical,
                     remote=remote,
+                    convert_units=convert_units,
                     dataset=dataset,
                 )
             except Exception as exc:
@@ -262,6 +269,7 @@ def _get_climate_data_single(
                         "bias_correction": bias_correction,
                         "historical": historical,
                         "remote": remote,
+                        "convert_units": convert_units,
                         "dataset": dataset,
                     },
                 )
@@ -350,6 +358,7 @@ def get_climate_data(
     xlim: tuple[float, float] | None = None,
     ylim: tuple[float, float] | None = None,
     remote: bool = True,
+    convert_units: bool = True,
     variables: list[str] | None = None,
     num_processes: int = len(VALID_VARIABLES),
     max_threads_per_process: int = 3,
@@ -391,6 +400,8 @@ def get_climate_data(
     xlim (tuple or None): Longitudinal bounds of the region of interest. Use only when country is None (default: None).
     ylim (tuple or None): Latitudinal bounds of the region of interest. Use only when country is None (default: None).
     remote (bool): Flag to work with remote data or not (default: True).
+    convert_units (bool): Whether to convert source data to cavapy's standard units.
+        Set to False to preserve the values and units stored by the source (default: True).
     variables (list[str] or None): List of variables to process. Must be a subset of {VALID_VARIABLES}. If None, all variables are processed. (default: None).
     num_processes (int): Number of processes to use, one per variable for a single combo.
         If num_processes <= 1 or only one variable is requested, variables run sequentially.
@@ -425,6 +436,7 @@ def get_climate_data(
             xlim=xlim,
             ylim=ylim,
             remote=remote,
+            convert_units=convert_units,
             variables=variables,
             num_processes=num_processes,
             max_threads_per_process=max_threads_per_process,
@@ -452,6 +464,11 @@ def get_climate_data(
             "Cannot apply bias_correction=True when using dataset='CORDEX-CORE-BC'. "
             "The CORDEX-CORE-BC dataset is already bias-corrected using ISIMIP methodology."
         )
+    if bias_correction and not convert_units:
+        raise ValueError(
+            "convert_units=False cannot be used with bias_correction=True because "
+            "ERA5 and CORDEX source units are not directly compatible."
+        )
 
     if years_up_to is None:
         raise ValueError("years_up_to is required when obs is False")
@@ -483,6 +500,7 @@ def get_climate_data(
             xlim=xlim,
             ylim=ylim,
             remote=remote,
+            convert_units=convert_units,
             variables=variables,
             num_processes=num_processes,
             max_threads_per_process=max_threads_per_process,
@@ -535,6 +553,7 @@ def get_climate_data(
         "bias_correction": bias_correction,
         "historical": historical,
         "remote": remote,
+        "convert_units": convert_units,
         "dataset": dataset,
         "retry_log_level": retry_log_level,
     }

{cavapy-2.1.3 → cavapy-2.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cavapy"
-version = "2.1.3"
+version = "2.1.4"
 description = "CAVA Python package. Retrive climate data."
 authors = ["Riccardo Soldan <riccardosoldan@hotmail.it>", "Oleh Lokshyn <olokshyn@gmail.com>"]
 readme = "README.md"