ETo 2.0.0__tar.gz → 2.2.0__tar.gz

{eto-2.0.0 → eto-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ETo
-Version: 2.0.0
+Version: 2.2.0
 Summary: Class and functions to estimate reference ET
 Project-URL: Homepage, https://github.com/mullenkamp/ETo
 Project-URL: Documentation, https://mullenkamp.github.io/ETo/
@@ -24,11 +24,21 @@ Description-Content-Type: text/markdown
 
 # ETo
 
-**A Python package for calculating reference evapotranspiration**
+**A Python package for calculating reference and crop evapotranspiration**
 
 ---
 
-ETo calculates reference evapotranspiration (ETo) using the [UN-FAO 56 paper](http://www.fao.org/docrep/X0490E/X0490E00.htm) methodology. It estimates missing meteorological parameters from available data and supports both daily and hourly time steps.
+ETo calculates reference evapotranspiration (ETo) and crop evapotranspiration (ETc) using the [UN-FAO 56 paper](http://www.fao.org/docrep/X0490E/X0490E00.htm) methodology. It estimates missing meteorological parameters from available data and supports daily, hourly, and monthly time steps.
+
+## Features
+
+- **FAO 56 Penman-Monteith** reference ET (short and tall reference crops)
+- **Hargreaves** simplified daily ET
+- **Crop evapotranspiration** — single Kc, dual Kc (Kcb + Ke), and water stress adjustment (Ks)
+- **Built-in crop coefficients** for 23 major crops (FAO 56 Table 12)
+- **Automatic parameter estimation** with quality tracking
+- **Input validation** with configurable warnings
+- **Derived outputs** — VPD, T_dew (back-calculated), clear-sky radiation
 
 ## Documentation
 
@@ -61,5 +71,13 @@ data = {
 dates = np.arange('2020-01-01', '2020-01-04', dtype='datetime64[D]')
 
 et = ETo(data, freq='D', z_msl=500, lat=-43.6, dates=dates)
+
+# Reference ET
 eto = et.eto_fao()  # np.ndarray of ETo in mm
+
+# Crop ET (single Kc)
+etc = et.etc(crop='maize_grain', stage='mid')  # ETc = Kc × ETo
+
+# Tall reference crop (ASCE alfalfa)
+etr = et.eto_fao(ref_crop='tall')
 ```

eto-2.2.0/README.md

@@ -0,0 +1,59 @@
+# ETo
+
+**A Python package for calculating reference and crop evapotranspiration**
+
+---
+
+ETo calculates reference evapotranspiration (ETo) and crop evapotranspiration (ETc) using the [UN-FAO 56 paper](http://www.fao.org/docrep/X0490E/X0490E00.htm) methodology. It estimates missing meteorological parameters from available data and supports daily, hourly, and monthly time steps.
+
+## Features
+
+- **FAO 56 Penman-Monteith** reference ET (short and tall reference crops)
+- **Hargreaves** simplified daily ET
+- **Crop evapotranspiration** — single Kc, dual Kc (Kcb + Ke), and water stress adjustment (Ks)
+- **Built-in crop coefficients** for 23 major crops (FAO 56 Table 12)
+- **Automatic parameter estimation** with quality tracking
+- **Input validation** with configurable warnings
+- **Derived outputs** — VPD, T_dew (back-calculated), clear-sky radiation
+
+## Documentation
+
+Full documentation is available at [mullenkamp.github.io/ETo](https://mullenkamp.github.io/ETo/).
+
+## Installation
+
+```bash
+pip install eto
+```
+
+or:
+
+```bash
+conda install -c mullenkamp eto
+```
+
+The only dependency is [NumPy](https://numpy.org/).
+
+## Quick Example
+
+```python
+import numpy as np
+from eto import ETo
+
+data = {
+    'T_min': np.array([10.0, 12.0, 8.0]),
+    'T_max': np.array([25.0, 28.0, 22.0]),
+}
+dates = np.arange('2020-01-01', '2020-01-04', dtype='datetime64[D]')
+
+et = ETo(data, freq='D', z_msl=500, lat=-43.6, dates=dates)
+
+# Reference ET
+eto = et.eto_fao()  # np.ndarray of ETo in mm
+
+# Crop ET (single Kc)
+etc = et.etc(crop='maize_grain', stage='mid')  # ETc = Kc × ETo
+
+# Tall reference crop (ASCE alfalfa)
+etr = et.eto_fao(ref_crop='tall')
+```

{eto-2.0.0 → eto-2.2.0}/eto/__init__.py

@@ -2,4 +2,4 @@ from eto.core import ETo
 import eto.datasets
 import eto.methods
 
-__version__ = '2.0.0'
+__version__ = '2.2.0'

{eto-2.0.0 → eto-2.2.0}/eto/core.py

@@ -3,9 +3,12 @@
 Class to estimate reference ET (ETo) from the FAO 56 paper using a minimum of T_min and T_max for daily estimates and T_mean and RH_mean for hourly, but utilizing the maximum number of available met parameters. The function prioritizes the estimation of specific parameters based on the available input data.
 """
 import numpy as np
+from eto.util import is_hourly
 from eto.param_est import param_est
 from eto.methods.ETo import eto_fao
 from eto.methods.hargreaves import hargreaves
+from eto.crop_coefficients import etc, etc_adj, kc_adjust
+from eto.methods.dual_kc import etc_dual
 
 
 class ETo(object):
@@ -21,18 +24,20 @@ class ETo(object):
         T_min, T_max, T_mean, T_dew, RH_min, RH_max, RH_mean, n_sun, U_z,
         P, e_a). All arrays must have the same length.
     freq : str
-        Time frequency: 'D' for daily, 'H' or 'h' for hourly.
+        Time frequency: 'D' for daily, 'h' (or 'H') for hourly, 'M' for monthly.
     day_of_year : np.ndarray of int, or None
         Day of year (1-366). Required if dates is not provided.
     hour : np.ndarray of int, or None
         Hour of day (0-23). Required for hourly frequency if dates is not provided.
     dates : np.ndarray of datetime64, or None
         Datetime array. Used to derive day_of_year and hour if they are not provided.
+    time_label, rs_rso_init
+        Hourly only; see :func:`eto.param_est.param_est`.
     """
 
     def __init__(self, data=None, freq='D', z_msl=None, lat=None, lon=None, TZ_lon=None,
                  z_u=2, K_rs=0.16, a_s=0.25, b_s=0.5, alb=0.23,
-                 day_of_year=None, hour=None, dates=None):
+                 day_of_year=None, hour=None, dates=None, validate=True, time_label='start', rs_rso_init=None):
 
         if data is None:
             pass
@@ -49,7 +54,7 @@ class ETo(object):
             if dates is not None:
                 dates = np.asarray(dates)
                 day_of_year = (dates.astype('datetime64[D]') - dates.astype('datetime64[Y]')).astype(int) + 1
-                if 'h' in freq.lower():
+                if is_hourly(freq):
                     hour = (dates - dates.astype('datetime64[D]')).astype('timedelta64[h]').astype(int)
             elif day_of_year is not None:
                 day_of_year = np.asarray(day_of_year)
@@ -59,7 +64,7 @@ class ETo(object):
             # Validate temporal array lengths
             if len(day_of_year) != n:
                 raise ValueError('day_of_year length must match data array length')
-            if 'h' in freq.lower():
+            if is_hourly(freq):
                 if hour is None:
                     raise ValueError('hour array or dates must be provided for hourly frequency')
                 hour = np.asarray(hour)
@@ -67,10 +72,14 @@ class ETo(object):
                     raise ValueError('hour length must match data array length')
 
             self.param_est(data, freq, z_msl, lat, lon, TZ_lon, z_u, K_rs, a_s, b_s, alb,
-                           day_of_year=day_of_year, hour=hour)
+                           day_of_year=day_of_year, hour=hour, validate=validate,
+                           time_label=time_label, rs_rso_init=rs_rso_init)
 
 
 ### Add in the ETo methods
 ETo.param_est = param_est
 ETo.eto_fao = eto_fao
 ETo.eto_hargreaves = hargreaves
+ETo.etc = etc
+ETo.etc_dual = etc_dual
+ETo.etc_adj = etc_adj

eto-2.2.0/eto/crop_coefficients.py

@@ -0,0 +1,123 @@
+# -*- coding: utf-8 -*-
+"""
+Crop coefficient functions for ETc estimation (FAO 56).
+"""
+import numpy as np
+
+
+# FAO 56 Table 12 — single crop coefficients (Kc_ini, Kc_mid, Kc_end)
+KC_TABLE = {
+    'alfalfa':          (0.40, 1.20, 1.15),
+    'barley':           (0.30, 1.15, 0.25),
+    'beans_dry':        (0.40, 1.15, 0.35),
+    'beans_green':      (0.50, 1.05, 0.90),
+    'cabbage':          (0.70, 1.05, 0.95),
+    'cotton':           (0.35, 1.15, 0.70),
+    'grape':            (0.30, 0.85, 0.45),
+    'groundnut':        (0.40, 1.15, 0.60),
+    'lettuce':          (0.70, 1.00, 0.95),
+    'maize_grain':      (0.30, 1.20, 0.60),
+    'maize_sweet':      (0.30, 1.15, 1.05),
+    'millet':           (0.30, 1.00, 0.30),
+    'onion_dry':        (0.70, 1.05, 0.75),
+    'peanut':           (0.40, 1.15, 0.60),
+    'potato':           (0.50, 1.15, 0.75),
+    'rice':             (1.05, 1.20, 0.90),
+    'sorghum':          (0.30, 1.00, 0.55),
+    'soybean':          (0.40, 1.15, 0.50),
+    'sugarcane':        (0.40, 1.25, 0.75),
+    'sunflower':        (0.35, 1.15, 0.35),
+    'tomato':           (0.60, 1.15, 0.80),
+    'wheat_winter':     (0.70, 1.15, 0.25),
+    'wheat_spring':     (0.30, 1.15, 0.25),
+}
+
+
+def kc_adjust(Kc, u2, RH_min, h):
+    """
+    Climate adjustment of Kc for non-standard conditions (FAO 56 Eq 62).
+
+    Parameters
+    ----------
+    Kc : float
+        Tabulated crop coefficient (Kc_mid or Kc_end).
+    u2 : float
+        Mean daily wind speed at 2 m (m/s).
+    RH_min : float
+        Mean minimum relative humidity (%).
+    h : float
+        Mean plant height (m).
+
+    Returns
+    -------
+    float
+        Adjusted Kc.
+    """
+    return Kc + (0.04*(u2 - 2) - 0.004*(RH_min - 45)) * (h/3)**0.3
+
+
+def etc(self, Kc=None, crop=None, stage=None, **kwargs):
+    """
+    Crop evapotranspiration ETc = Kc * ETo (FAO 56 Eq 58, single Kc).
+
+    Parameters
+    ----------
+    Kc : float or np.ndarray, optional
+        Crop coefficient. If not provided, looked up from KC_TABLE.
+    crop : str, optional
+        Crop name (key in KC_TABLE). Required if Kc is not provided.
+    stage : str, optional
+        Growth stage: 'ini', 'mid', or 'end'. Required if crop is provided
+        without Kc.
+    **kwargs
+        Passed to eto_fao().
+
+    Returns
+    -------
+    np.ndarray
+        ETc in mm.
+    """
+    if Kc is None:
+        if crop is None:
+            raise ValueError('Either Kc or crop must be provided')
+        crop_lower = crop.lower()
+        if crop_lower not in KC_TABLE:
+            raise ValueError(f'Unknown crop: {crop}. Available: {sorted(KC_TABLE.keys())}')
+        if stage is None:
+            raise ValueError('stage must be provided when using crop lookup')
+        stage_idx = {'ini': 0, 'mid': 1, 'end': 2}
+        if stage not in stage_idx:
+            raise ValueError(f"stage must be 'ini', 'mid', or 'end', got '{stage}'")
+        Kc = KC_TABLE[crop_lower][stage_idx[stage]]
+
+    return np.asarray(Kc) * self.eto_fao(**kwargs)
+
+
+def etc_adj(self, Kc, TAW, Dr, p=0.5, **kwargs):
+    """
+    Adjusted ETc under water stress (FAO 56 Eq 84).
+
+    ETc_adj = Ks * Kc * ETo
+
+    Parameters
+    ----------
+    Kc : float or np.ndarray
+        Crop coefficient.
+    TAW : float or np.ndarray
+        Total available water in root zone (mm).
+    Dr : float or np.ndarray
+        Root zone depletion (mm).
+    p : float
+        Depletion fraction for no stress (default 0.5).
+    **kwargs
+        Passed to eto_fao().
+
+    Returns
+    -------
+    np.ndarray
+        ETc_adj in mm.
+    """
+    TAW = np.asarray(TAW, dtype=np.float64)
+    Dr = np.asarray(Dr, dtype=np.float64)
+    Ks = np.clip((TAW - Dr) / ((1 - p) * TAW), 0, 1)
+    return Ks * np.asarray(Kc) * self.eto_fao(**kwargs)

eto-2.2.0/eto/methods/ETo.py

@@ -0,0 +1,61 @@
+# -*- coding: utf-8 -*-
+"""
+Function to estimate reference ET (ETo) from the FAO 56 paper using a minimum of T_min and T_max for daily estimates and T_mean and RH_mean for hourly, but utilizing the maximum number of available met parameters.
+"""
+import numpy as np
+from eto.util import is_hourly
+
+
+def eto_fao(self, max_ETo=15, min_ETo=0, ref_crop='short', decimals=2):
+    """
+    Function to estimate reference ET (ETo) from the `FAO 56 paper <http://www.fao.org/docrep/X0490E/X0490E00.htm>`_ [1]_ using a minimum of T_min and T_max for daily estimates and T_mean and RH_mean for hourly, but optionally utilising the maximum number of available met parameters.
+
+    Parameters
+    ----------
+    max_ETo : float, int or None
+        The max realistic value of ETo (mm); higher values become NaN. None disables the check.
+    min_ETo : float, int or None
+        The min realistic value of ETo (mm); lower values are raised to it. None keeps negative
+        values (raw FAO-56, e.g. night-time dew).
+    ref_crop : str
+        Reference crop type: 'short' (FAO 56 grass) or 'tall' (ASCE alfalfa).
+    decimals : int or None
+        Decimal places of the result; None returns it unrounded.
+
+    Returns
+    -------
+    np.ndarray
+        Estimated ETo in mm.
+
+    References
+    ----------
+
+    .. [1] Allen, R. G., Pereira, L. S., Raes, D., & Smith, M. (1998). Crop evapotranspiration-Guidelines for computing crop water requirements-FAO Irrigation and drainage paper 56. FAO, Rome, 300(9), D05109.
+    """
+
+    ######
+    ## ETo equation — select Cn and Cd based on ref_crop and frequency
+    if is_hourly(self.freq):
+        if ref_crop == 'tall':
+            Cn = 66
+            Cd = np.where(self.ts_param['R_n'] > 0, 0.25, 1.7)
+        else:
+            Cn = 37
+            Cd = 0.34
+        ETo_FAO = (0.408*self.ts_param['delta']*(self.ts_param['R_n'] - self.ts_param['G']) + self.ts_param['gamma']*Cn/(self.ts_param['T_mean'] + 273)*self.ts_param['U_2']*(self.ts_param['e_mean'] - self.ts_param['e_a']))/(self.ts_param['delta'] + self.ts_param['gamma']*(1 + Cd*self.ts_param['U_2']))
+    else:
+        if ref_crop == 'tall':
+            Cn = 1600
+            Cd = 0.38
+        else:
+            Cn = 900
+            Cd = 0.34
+        ETo_FAO = (0.408*self.ts_param['delta']*(self.ts_param['R_n'] - self.ts_param['G']) + self.ts_param['gamma']*Cn/(self.ts_param['T_mean'] + 273)*self.ts_param['U_2']*(self.ts_param['e_s'] - self.ts_param['e_a']))/(self.ts_param['delta'] + self.ts_param['gamma']*(1 + Cd*self.ts_param['U_2']))
+
+    ## Clamp negatives to min_ETo, NaN for suspect highs
+    if min_ETo is not None:
+        ETo_FAO = np.maximum(ETo_FAO, min_ETo)
+    if max_ETo is not None:
+        ETo_FAO = np.where(ETo_FAO > max_ETo, np.nan, ETo_FAO)
+
+    return ETo_FAO if decimals is None else np.round(ETo_FAO, decimals)

eto-2.2.0/eto/methods/dual_kc.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+"""
+Dual crop coefficient method (FAO 56 Eq 58).
+"""
+import numpy as np
+
+
+def etc_dual(self, Kcb, Ke=None, Kr=None, Kc_max=None, few=None, **kwargs):
+    """
+    Dual crop coefficient ETc = (Kcb + Ke) * ETo (FAO 56 Eq 58).
+
+    Parameters
+    ----------
+    Kcb : float or np.ndarray
+        Basal crop coefficient.
+    Ke : float or np.ndarray, optional
+        Soil evaporation coefficient. If not provided, estimated from
+        Kr, Kc_max, few, and Kcb.
+    Kr : float or np.ndarray, optional
+        Evaporation reduction coefficient (0-1). Required if Ke not provided.
+    Kc_max : float or np.ndarray, optional
+        Maximum Kc following rain/irrigation. Required if Ke not provided.
+    few : float or np.ndarray, optional
+        Fraction of soil surface wetted and exposed (0-1). Required if Ke
+        not provided.
+    **kwargs
+        Passed to eto_fao().
+
+    Returns
+    -------
+    np.ndarray
+        ETc in mm.
+    """
+    if Ke is None:
+        if Kr is None or Kc_max is None or few is None:
+            raise ValueError('When Ke is not provided, Kr, Kc_max, and few are required')
+        Kcb = np.asarray(Kcb, dtype=np.float64)
+        Kr = np.asarray(Kr, dtype=np.float64)
+        Kc_max = np.asarray(Kc_max, dtype=np.float64)
+        few = np.asarray(few, dtype=np.float64)
+        # FAO 56 Eq 71: Ke = Kr * (Kc_max - Kcb), limited by few * Kc_max
+        Ke = np.minimum(Kr * (Kc_max - Kcb), few * Kc_max)
+
+    return (np.asarray(Kcb) + np.asarray(Ke)) * self.eto_fao(**kwargs)

{eto-2.0.0 → eto-2.2.0}/eto/methods/hargreaves.py

@@ -5,6 +5,7 @@ Created on Sun May 13 09:45:39 2018
 @author: MichaelEK
 """
 import numpy as np
+from eto.util import is_hourly
 
 
 def hargreaves(self, max_ETo=15, min_ETo=0):
@@ -27,13 +28,13 @@ def hargreaves(self, max_ETo=15, min_ETo=0):
     ######
     ## ETo equation
 
-    if 'h' in self.freq.lower():
+    if is_hourly(self.freq):
         raise ValueError('Hargreaves should not be calculated at time frequencies of less than a day.')
 
     ETo_Har = 0.0023*(self.ts_param['T_mean'] + 17.8)*((self.ts_param['T_max'] - self.ts_param['T_min']) **0.5)*self.ts_param['R_a']*0.408
 
-    ## Remove extreme values
+    ## Clamp negatives to min_ETo, NaN for suspect highs
+    ETo_Har = np.maximum(ETo_Har, min_ETo)
     ETo_Har[ETo_Har > max_ETo] = np.nan
-    ETo_Har[ETo_Har < min_ETo] = np.nan
 
     return np.round(ETo_Har, 2)