ETo 2.1.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ETo
-Version: 2.1.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/

{eto-2.1.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.1.0'
+__version__ = '2.2.0'

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

@@ -3,6 +3,7 @@
 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
@@ -23,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, validate=True):
+                 day_of_year=None, hour=None, dates=None, validate=True, time_label='start', rs_rso_init=None):
 
         if data is None:
             pass
@@ -51,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)
@@ -61,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)
@@ -69,7 +72,8 @@ 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, validate=validate)
+                           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-2.1.0 → eto-2.2.0}/eto/methods/ETo.py

@@ -3,20 +3,24 @@
 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'):
+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 or int
-        The max realistic value of ETo (mm).
-    min_ETo : float or int
-        The min realistic value of ETo (mm).
+    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
     -------
@@ -31,7 +35,7 @@ def eto_fao(self, max_ETo=15, min_ETo=0, ref_crop='short'):
 
     ######
     ## ETo equation — select Cn and Cd based on ref_crop and frequency
-    if 'h' in self.freq.lower():
+    if is_hourly(self.freq):
         if ref_crop == 'tall':
             Cn = 66
             Cd = np.where(self.ts_param['R_n'] > 0, 0.25, 1.7)
@@ -49,7 +53,9 @@ def eto_fao(self, max_ETo=15, min_ETo=0, ref_crop='short'):
         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
-    ETo_FAO = np.maximum(ETo_FAO, min_ETo)
-    ETo_FAO[ETo_FAO > max_ETo] = np.nan
+    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 np.round(ETo_FAO, 2)
+    return ETo_FAO if decimals is None else np.round(ETo_FAO, decimals)

{eto-2.1.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,7 +28,7 @@ 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

{eto-2.1.0 → eto-2.2.0}/eto/param_est.py

@@ -4,9 +4,10 @@ Function for parameter estimation.
 """
 import warnings
 import numpy as np
+from eto.util import is_hourly, TIME_LABELS, RS_RSO_MIN
 
 
-def param_est(self, data, 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, validate=True):
+def param_est(self, data, 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, validate=True, time_label='start', rs_rso_init=None):
     """
     Function to estimate the parameters necessary to calculate reference ET (ETo) from the `FAO 56 paper <http://www.fao.org/docrep/X0490E/X0490E00.htm>`_ 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.
 
@@ -21,9 +22,13 @@ def param_est(self, data, freq='D', z_msl=None, lat=None, lon=None, TZ_lon=None,
     lat : float, int, or None
         Latitude (decimal degrees).
     lon : float, int, or None
-        Longitude (decimal degrees).
+        Longitude in decimal degrees, **east-positive** (e.g. 172.5 for Canterbury, -16.25 for
+        16°15'W). Since 2.2.0; earlier versions applied FAO-56's west-positive formula to this
+        argument, so east-positive input put hourly solar time about 2·lon/15 h out (about an hour
+        for NZ with ``TZ_lon`` = 0).
     TZ_lon : float, int, or None
-        Longitude of the center of the time zone (decimal degrees).
+        Longitude of the centre of the time zone of ``hour``, east-positive (0 for UTC, 180 for
+        NZST).
     z_u : float or int
         Height of wind speed measurement (m). Default is 2 m.
     K_rs : float
@@ -41,11 +46,32 @@ def param_est(self, data, freq='D', z_msl=None, lat=None, lon=None, TZ_lon=None,
     validate : bool
         If True (default), warn when input values are outside physically
         reasonable ranges.
+    time_label : str
+        Hourly only. Whether ``hour`` labels the **start** of its one-hour period ('start', default:
+        the period is [hour, hour+1)) or its **end** ('end': (hour-1, hour]).
+    rs_rso_init : float or None
+        Hourly only. The Rs/Rso ratio carried into the first night of the series, i.e. the value from
+        the previous chunk (see ``self.rs_rso_last``). If None and the series starts at night, 1.0 is
+        used for the hours before the first reference period, with a warning.
 
     Returns
     -------
-    None (populates self.ts_param and self.est_val)
+    None (populates self.ts_param and self.est_val, and for hourly data self.rs_rso_last)
+
+    Notes
+    -----
+    **Night-time cloudiness (hourly).** FAO-56 (Ch. 3, hourly Rnl) sets Rs/Rso at night equal to the
+    value for the period 2-3 hours before sunset, where the solar time angle at the period's midpoint
+    satisfies ``ws - 0.79 <= w <= ws - 0.52``. That value is carried forward through every hour with
+    Rso = 0 until the next such period. It is state: pass the previous chunk's ``rs_rso_last`` as
+    ``rs_rso_init`` so a series computed in chunks equals one computed whole. (Versions before 2.2.0
+    set Rs/Rso = 1 at night, i.e. assumed clear nights.) Hourly Rs/Rso is limited to [0.3, 1] (ASCE-EWRI
+    2005; FAO-56 gives only the upper limit; daily keeps FAO-56's [0, 1]), and hourly extraterrestrial radiation integrates only the sunlit
+    part of an hour that straddles sunrise or sunset (ASCE-EWRI).
     """
+    hourly = is_hourly(freq)
+    if time_label not in TIME_LABELS:
+        raise ValueError(f'time_label must be one of {TIME_LABELS}, got {time_label!r}')
 
     met_names = ['R_n', 'R_s', 'G', 'T_min', 'T_max', 'T_mean', 'T_dew', 'RH_min', 'RH_max', 'RH_mean', 'n_sun', 'U_z', 'P', 'e_a']
     self.freq = freq
@@ -85,7 +111,7 @@ def param_est(self, data, freq='D', z_msl=None, lat=None, lon=None, TZ_lon=None,
 
     ####################################
     ###### Check to make sure minimum requirements are met
-    if 'h' in freq.lower():
+    if hourly:
         T_mean_bool = np.isnan(self.ts_param['T_mean']).any()
         RH_mean_bool = np.isnan(self.ts_param['RH_mean']).any()
         e_a_bool = np.isnan(self.ts_param['e_a']).any()
@@ -122,7 +148,7 @@ def param_est(self, data, freq='D', z_msl=None, lat=None, lon=None, TZ_lon=None,
     self.ts_param['T_mean'][mask] = (self.ts_param['T_max'][mask] + self.ts_param['T_min'][mask])/2
 
     ## Vapor pressures
-    if 'h' in freq.lower():
+    if hourly:
         self.ts_param['e_mean'] = 0.6108*np.exp(17.27*self.ts_param['T_mean']/(self.ts_param['T_mean']+237.3))
         mask = np.isnan(self.ts_param['e_a'])
         self.ts_param['e_a'][mask] = self.ts_param['e_mean'][mask]*self.ts_param['RH_mean'][mask]/100
@@ -162,7 +188,7 @@ def param_est(self, data, freq='D', z_msl=None, lat=None, lon=None, TZ_lon=None,
         self.ts_param['T_dew'][mask] = 237.3 * ln_ratio / (17.27 - ln_ratio)
 
     # VPD
-    if 'h' in freq.lower():
+    if hourly:
         self.ts_param['VPD'] = self.ts_param['e_mean'] - self.ts_param['e_a']
     else:
         self.ts_param['VPD'] = self.ts_param['e_s'] - self.ts_param['e_a']
@@ -176,21 +202,37 @@ def param_est(self, data, freq='D', z_msl=None, lat=None, lon=None, TZ_lon=None,
 
     # R_a
     phi = lat*np.pi/180
-    delta = 0.409*np.sin(2*np.pi*Day/365-1.39)
-    d_r = 1+0.033*np.cos(2*np.pi*Day/365)
-    w_s = np.arccos(-np.tan(phi)*np.tan(delta))
 
-    if 'h' in freq.lower():
-        hour_vec = hour
+    if hourly:
+        if lon is None or TZ_lon is None:
+            raise ValueError('lon and TZ_lon are required for hourly data')
+        # Solar time at the period midpoint (FAO-56 Eq 31-33, east-positive longitudes). Labels may
+        # be in any time zone (e.g. UTC), so the solar time can fall on the previous or next day:
+        # the declination and sunset angle use that solar day.
+        t_mid = np.asarray(hour, dtype=np.float64) + (0.5 if time_label == 'start' else -0.5)
         b = (2*np.pi*(Day - 81))/364
         S_c = 0.1645*np.sin(2*b) - 0.1255*np.cos(b) - 0.025*np.sin(b)
-        w = np.pi/12*(((hour_vec+0.5) + 0.06667*(TZ_lon - lon) + S_c) - 12)
-        w_1 = w - (np.pi*1)/24
-        w_2 = w + (np.pi*1)/24
+        # lon - TZ_lon wrapped to [-180, 180): the same place given as 183.5 or -176.5 is the same offset.
+        dlon = (lon - TZ_lon + 180) % 360 - 180
+        t_solar = t_mid + 0.06667*dlon + S_c
+        day_shift = np.floor(t_solar/24)
+        Day = Day + day_shift
+        t_solar = t_solar - 24*day_shift
+        w = np.pi/12*(t_solar - 12)
+        delta = 0.409*np.sin(2*np.pi*Day/365-1.39)
+        d_r = 1+0.033*np.cos(2*np.pi*Day/365)
+        w_s = np.arccos(-np.tan(phi)*np.tan(delta))
+        # Period start and end angles clipped to sunrise/sunset (ASCE-EWRI 2005), so an hour that
+        # straddles the horizon integrates only its sunlit part instead of netting night against day.
+        w_1 = np.clip(w - (np.pi*1)/24, -w_s, w_s)
+        w_2 = np.clip(w + (np.pi*1)/24, -w_s, w_s)
 
         self.ts_param['R_a'] = 12*60/np.pi*0.082*d_r*((w_2 - w_1)*np.sin(phi)*np.sin(delta) + np.cos(phi)*np.cos(delta)*(np.sin(w_2) - np.sin(w_1)))
         self.ts_param['R_a'] = np.maximum(self.ts_param['R_a'], 0)
     else:
+        delta = 0.409*np.sin(2*np.pi*Day/365-1.39)
+        d_r = 1+0.033*np.cos(2*np.pi*Day/365)
+        w_s = np.arccos(-np.tan(phi)*np.tan(delta))
         self.ts_param['R_a'] = 24*60/np.pi*0.082*d_r*(w_s*np.sin(phi)*np.sin(delta) + np.cos(phi)*np.cos(delta)*np.sin(w_s))
 
     # Daylight hours
@@ -215,9 +257,32 @@ def param_est(self, data, freq='D', z_msl=None, lat=None, lon=None, TZ_lon=None,
     # R_ns from R_s
     R_ns = (1 - alb)*self.ts_param['R_s']
 
-    # R_nl — safe R_s/R_so ratio to avoid division by zero when R_so=0
-    Rs_Rso = np.where(R_so > 0, np.minimum(self.ts_param['R_s'] / np.where(R_so > 0, R_so, 1.0), 1.0), 1.0)
-    if 'h' in freq.lower():
+    # R_nl — R_s/R_so capped at 1 (FAO-56); hourly also floored at RS_RSO_MIN (ASCE-EWRI), because a dark
+    # hour's ratio is carried through the night. Daily is unchanged (FAO-56 as published). No division
+    # where R_so = 0.
+    rs_rso_min = RS_RSO_MIN if hourly else 0.0
+    Rs_Rso = np.where(R_so > 0, np.clip(self.ts_param['R_s'] / np.where(R_so > 0, R_so, 1.0), rs_rso_min, 1.0), np.nan)
+    if hourly:
+        # Night (R_so = 0): the ratio from the last period 2-3 h before sunset (FAO-56), carried as state.
+        ref = (w >= w_s - 0.79) & (w <= w_s - 0.52) & np.isfinite(Rs_Rso)
+        carried = np.where(ref, Rs_Rso, np.nan)
+        idx = np.where(np.isfinite(carried), np.arange(n), -1)
+        np.maximum.accumulate(idx, out=idx)
+        if rs_rso_init is None:
+            if ((idx < 0) & ~(R_so > 0)).any():
+                warnings.warn('Hourly series starts at night with no prior Rs/Rso (rs_rso_init); using 1.0 '
+                              '(clear sky) until the first period 2-3 h before sunset')
+            init = 1.0
+        else:
+            init = float(np.clip(rs_rso_init, RS_RSO_MIN, 1.0))
+        carried = np.where(idx >= 0, carried[np.maximum(idx, 0)], init)
+        Rs_Rso = np.where(R_so > 0, Rs_Rso, carried)
+        self.rs_rso_last = float(carried[-1]) if n else init
+    else:
+        Rs_Rso = np.where(R_so > 0, Rs_Rso, 1.0)
+    self.ts_param['R_so'] = R_so
+    self.ts_param['Rs_Rso'] = Rs_Rso
+    if hourly:
         R_nl = (2.043e-10)*((self.ts_param['T_mean'] + 273.16)**4)*(0.34-0.14*self.ts_param['e_a']**0.5)*(1.35*Rs_Rso - 0.35)
     else:
         R_nl = (4.903e-9)*(((self.ts_param['T_max'] + 273.16)**4 + (self.ts_param['T_min'] + 273.16)**4)/2)*(0.34-0.14*self.ts_param['e_a']**0.5)*(1.35*Rs_Rso - 0.35)
@@ -230,12 +295,12 @@ def param_est(self, data, freq='D', z_msl=None, lat=None, lon=None, TZ_lon=None,
     # G
     mask = np.isnan(self.ts_param['G'])
     self.est_val[mask] += 10
-    if 'h' in freq.lower():
+    if hourly:
         day_mask = mask & (self.ts_param['R_n'] > 0)
         night_mask = mask & (self.ts_param['R_n'] <= 0)
         self.ts_param['G'][day_mask] = 0.1 * self.ts_param['R_n'][day_mask]
         self.ts_param['G'][night_mask] = 0.5 * self.ts_param['R_n'][night_mask]
-    elif freq.upper() == 'M':
+    elif str(freq).lower() in ('m', '1m'):
         G_monthly = np.zeros(n)
         G_monthly[1:] = 0.14 * (self.ts_param['T_mean'][1:] - self.ts_param['T_mean'][:-1])
         self.ts_param['G'][mask] = G_monthly[mask]

eto-2.2.0/eto/tests/test_hourly_fao.py

@@ -0,0 +1,245 @@
+"""
+Hourly FAO-56 checks added in 2.2.0: Example 19, solar time with east-positive longitude and
+interval labels, and the night-time Rs/Rso carried as state.
+"""
+import warnings
+
+import numpy as np
+import pytest
+
+from eto import ETo
+
+# FAO-56 Example 19: N'Diaye, Senegal, 16°13'N 16°15'W, 8 m, 1 October (J = 274), Lz = 15° W.
+EX19 = dict(z_msl=8, lat=16 + 13 / 60, lon=-16.25, TZ_lon=-15.0)
+
+
+def ex19(hour, T, RH, u2, Rs, **kw):
+    data = {'T_mean': np.array([T]), 'RH_mean': np.array([RH]), 'U_z': np.array([u2]), 'R_s': np.array([Rs])}
+    return ETo(data, 'h', day_of_year=np.array([274]), hour=np.array([hour]), **EX19, **kw)
+
+
+def test_example19_day_period():
+    et = ex19(14, 38.0, 52.0, 3.3, 2.450)
+    p = et.ts_param
+    assert p['R_a'][0] == pytest.approx(3.543, abs=0.002)
+    assert p['R_so'][0] == pytest.approx(2.658, abs=0.002)
+    assert p['Rs_Rso'][0] == pytest.approx(0.922, abs=0.001)
+    assert p['R_n'][0] == pytest.approx(1.749, abs=0.003)
+    assert et.eto_fao()[0] == pytest.approx(0.63)
+
+
+def test_example19_night_period_uses_the_carried_ratio():
+    et = ex19(2, 28.0, 90.0, 1.9, 0.0, rs_rso_init=0.8)
+    p = et.ts_param
+    assert p['Rs_Rso'][0] == 0.8
+    assert p['R_n'][0] == pytest.approx(-0.100, abs=0.002)
+    assert et.eto_fao()[0] == pytest.approx(0.0)
+
+
+def nz_day(time_label='start', lon=171.5, TZ_lon=0.0):
+    """One January day of hourly UTC labels at a Canterbury point."""
+    n = 24
+    data = {'T_mean': np.full(n, 20.0), 'RH_mean': np.full(n, 60.0), 'U_z': np.full(n, 2.0), 'R_s': np.full(n, 0.5)}
+    hours = np.arange(n) + (1 if time_label == 'end' else 0)
+    return ETo(data, 'h', z_msl=300, lat=-43.5, lon=lon, TZ_lon=TZ_lon, day_of_year=np.full(n, 15),
+               hour=hours, time_label=time_label, rs_rso_init=1.0)
+
+
+def test_extraterrestrial_radiation_peaks_in_the_hour_holding_solar_noon():
+    # Solar noon at 171.5°E on 15 January is about 00:40 UTC (equation of time about -9 min). With
+    # west-positive arithmetic on east-positive input the peak moves to the 23 UTC hour.
+    et = nz_day('start')
+    assert int(np.argmax(et.ts_param['R_a'])) == 0
+    # The same instant expressed in NZST labels (TZ 180°E) peaks in the 12 h period.
+    data = {'T_mean': np.full(24, 20.0), 'RH_mean': np.full(24, 60.0), 'R_s': np.full(24, 0.5)}
+    nzst = ETo(data, 'h', z_msl=300, lat=-43.5, lon=171.5, TZ_lon=180.0, day_of_year=np.full(24, 15),
+               hour=np.arange(24), rs_rso_init=1.0)
+    assert int(np.argmax(nzst.ts_param['R_a'])) == 12
+
+
+def test_period_ending_labels_shift_by_one_hour():
+    start = nz_day('start').ts_param['R_a']
+    end = nz_day('end').ts_param['R_a']
+    np.testing.assert_allclose(end, start)  # labels 1..24 'end' are the same periods as 0..23 'start'
+
+
+def test_time_label_is_validated():
+    with pytest.raises(ValueError, match='time_label'):
+        nz_day('middle')
+
+
+@pytest.mark.parametrize('freq', ['3h', 'month', '30min', '60min', 'T', 'x'])
+def test_frequency_must_match_exactly(freq):
+    data = {'T_mean': np.full(3, 20.0), 'RH_mean': np.full(3, 60.0), 'T_min': np.full(3, 10.0), 'T_max': np.full(3, 25.0)}
+    with pytest.raises(ValueError, match='Unsupported frequency'):
+        ETo(data, freq, z_msl=10, lat=-43.5, lon=171.5, TZ_lon=0.0, day_of_year=np.array([1, 2, 3]),
+            hour=np.array([0, 1, 2]))
+
+
+def three_days(cloud=(0.5, 0.9, 0.3)):
+    """Hourly UTC series at 171.5°E: R_s = cloud factor of the day times clear-sky Rso."""
+    n = 72
+    hours = np.arange(n) % 24
+    doy = 15 + np.arange(n) // 24
+    clear = ETo({'T_mean': np.full(n, 15.0), 'RH_mean': np.full(n, 70.0)}, 'h', z_msl=300, lat=-43.5,
+                lon=171.5, TZ_lon=0.0, day_of_year=doy, hour=hours, rs_rso_init=1.0).ts_param['R_so']
+    # UTC hours 0-5 of day d are the NZ afternoon of that day (NZST = UTC+12): the day's cloud factor.
+    # Sunset is near 08 UTC, so the FAO reference period (2-3 h before sunset) is the 05 UTC hour.
+    # The dusk hours 06-07 get 0.7 and the NZ morning (UTC 12-23) 0.95, so a ratio taken from the
+    # wrong hour (a dusk hour, the morning) is visible.
+    day_cloud = np.array(cloud)[np.arange(n) // 24]
+    rs = clear * np.select([hours <= 5, hours <= 11], [day_cloud, 0.7], 0.95)
+    data = {'T_mean': np.full(n, 15.0), 'RH_mean': np.full(n, 70.0), 'U_z': np.full(n, 2.0), 'R_s': rs}
+    return data, doy, hours
+
+
+def run(data, doy, hours, sl, init):
+    sub = {k: v[sl] for k, v in data.items()}
+    return ETo(sub, 'h', z_msl=300, lat=-43.5, lon=171.5, TZ_lon=0.0, day_of_year=doy[sl], hour=hours[sl],
+               rs_rso_init=init)
+
+
+def test_night_uses_the_ratio_from_two_to_three_hours_before_sunset():
+    data, doy, hours = three_days()
+    et = run(data, doy, hours, slice(None), 1.0)
+    p = et.ts_param
+    night = p['R_so'] <= 0
+    # Every night hour after the first evening carries that evening's ratio, never the morning's
+    # 0.95 or the clear-sky 1.0.
+    after_first_evening = night & (np.arange(72) > 12)
+    assert after_first_evening.sum() > 15
+    # In January the whole NZ night (about 09:30-18:00 UTC) lies inside one UTC day, whose afternoon
+    # is the evening before it.
+    expect = np.array([0.5, 0.9, 0.3])[np.arange(72) // 24]
+    np.testing.assert_allclose(p['Rs_Rso'][after_first_evening], expect[after_first_evening])
+
+
+def test_chunked_equals_unchunked_with_boundaries_at_night():
+    # Boundaries placed in NZ night and low-sun hours (UTC 10-18 is 22:00-06:00 NZST), where the
+    # carried state is used. A boundary at UTC 00 (NZ noon) would test nothing.
+    data, doy, hours = three_days()
+    whole = run(data, doy, hours, slice(None), 1.0)
+    # Also every single cut, including those between the reference hour and dark, where the state
+    # must be the reference ratio and not the last hour's own ratio.
+    for cuts in ([14], [11, 40], [17, 38, 62], [19, 43], *([c] for c in range(1, 72))):
+        edges = [0, *cuts, 72]
+        init = 1.0
+        parts = []
+        for a, b in zip(edges[:-1], edges[1:]):
+            et = run(data, doy, hours, slice(a, b), init)
+            parts.append(et.ts_param['R_n'])
+            init = et.rs_rso_last
+        np.testing.assert_array_equal(np.concatenate(parts), whole.ts_param['R_n'])
+
+
+def test_series_starting_at_night_warns_without_an_initial_ratio_and_not_with_one():
+    data, doy, hours = three_days()
+    with pytest.warns(UserWarning, match='starts at night'):
+        run(data, doy, hours, slice(14, 30), None)
+    with warnings.catch_warnings():
+        warnings.simplefilter('error')
+        run(data, doy, hours, slice(14, 30), 0.7)
+
+
+def test_raw_mode_keeps_negative_unrounded_values():
+    # A saturated night (RH 100 %, so no vapour deficit) with net longwave loss: FAO-56 gives a small
+    # negative value (dew). Example 19's own night value is +0.004 mm, shown as 0.00.
+    et = ex19(2, 10.0, 100.0, 1.0, 0.0, rs_rso_init=0.8)
+    raw = et.eto_fao(min_ETo=None, max_ETo=None, decimals=None)
+    assert raw[0] < 0
+    assert raw[0] != np.round(raw[0], 2)
+    assert et.eto_fao()[0] == 0.0
+
+
+def test_west_longitude_with_utc_labels_finds_the_evening_reference():
+    # At 120°W the local evening falls after 00 UTC, so solar time must wrap into the previous day;
+    # without the wrap the reference period is never found and nights keep the initial 1.0.
+    n = 48
+    hours = np.arange(n) % 24
+    doy = 180 + np.arange(n) // 24
+    base = dict(z_msl=100, lat=40.0, lon=-120.0, TZ_lon=0.0, day_of_year=doy, hour=hours)
+    clear = ETo({'T_mean': np.full(n, 20.0), 'RH_mean': np.full(n, 50.0)}, 'h', rs_rso_init=1.0, **base).ts_param['R_so']
+    et = ETo({'T_mean': np.full(n, 20.0), 'RH_mean': np.full(n, 50.0), 'R_s': 0.6 * clear}, 'h', rs_rso_init=1.0, **base)
+    night = et.ts_param['R_so'] <= 0
+    later_nights = night & (np.arange(n) > 24)
+    assert later_nights.any()
+    np.testing.assert_allclose(et.ts_param['Rs_Rso'][later_nights], 0.6)
+
+
+
+# --- review thalweg-step0-code-1 ----------------------------------------------------------------
+
+
+def test_reference_is_the_hour_two_to_three_hours_before_sunset():
+    # Defect caught: a reference window one hour off (3-4 h before sunset). Each afternoon hour gets its
+    # own cloud factor, so the carried night value identifies the hour it came from.
+    n = 24
+    hours = np.arange(n)
+    doy = np.full(n, 15)
+    base = dict(z_msl=300, lat=-43.5, lon=171.5, TZ_lon=0.0, day_of_year=doy, hour=hours, rs_rso_init=1.0)
+    clear = ETo({'T_mean': np.full(n, 15.0), 'RH_mean': np.full(n, 70.0)}, 'h', **base).ts_param['R_so']
+    factor = np.full(n, 0.95)
+    factor[:8] = [0.40, 0.45, 0.50, 0.55, 0.60, 0.65, 0.70, 0.75]  # UTC 0-7 = NZST 12-19
+    et = ETo({'T_mean': np.full(n, 15.0), 'RH_mean': np.full(n, 70.0), 'R_s': factor * clear}, 'h', **base)
+    p = et.ts_param
+    night = p['R_so'] <= 0
+    # Which afternoon hour satisfies FAO-56's window: compute it from the solar angle directly.
+    phi = np.deg2rad(-43.5)
+    delta = 0.409 * np.sin(2 * np.pi * 15 / 365 - 1.39)
+    ws = np.arccos(-np.tan(phi) * np.tan(delta))
+    b = 2 * np.pi * (15 - 81) / 364
+    sc = 0.1645 * np.sin(2 * b) - 0.1255 * np.cos(b) - 0.025 * np.sin(b)
+    w = np.pi / 12 * ((hours + 0.5) + 0.06667 * (171.5 - 0.0) + sc - 24 * ((hours + 0.5 + 0.06667 * 171.5 + sc) >= 24) - 12)
+    ref = (w >= ws - 0.79) & (w <= ws - 0.52)
+    assert ref.sum() == 1
+    k = int(np.flatnonzero(ref)[0])
+    np.testing.assert_allclose(p['Rs_Rso'][night & (hours > k)], factor[k])
+
+
+def test_carried_ratio_is_the_capped_value():
+    # Defect caught: carrying the raw ratio. A reference hour with R_s above clear sky carries 1.0.
+    data, doy, hours = three_days(cloud=(1.4, 1.4, 1.4))
+    et = run(data, doy, hours, slice(None), 0.5)
+    p = et.ts_param
+    later_nights = (p['R_so'] <= 0) & (np.arange(72) > 12)
+    np.testing.assert_allclose(p['Rs_Rso'][later_nights], 1.0)
+
+
+def test_rs_rso_is_floored_at_0_3():
+    data, doy, hours = three_days(cloud=(0.05, 0.05, 0.05))
+    et = run(data, doy, hours, slice(None), 0.05)
+    r = et.ts_param['Rs_Rso']
+    assert np.nanmin(r) == pytest.approx(0.3)
+    later_nights = (et.ts_param['R_so'] <= 0) & (np.arange(72) > 12)
+    np.testing.assert_allclose(r[later_nights], 0.3)
+    assert (et.ts_param['R_n'][later_nights] < 0).all()  # net longwave stays a loss at night
+
+
+def test_longitude_difference_wraps_across_the_antimeridian():
+    a = nz_day('start', lon=183.5).ts_param['R_a']
+    b = nz_day('start', lon=-176.5).ts_param['R_a']
+    np.testing.assert_allclose(a, b)
+    c = nz_day('start', lon=171.5, TZ_lon=180.0).ts_param['R_a']
+    d = nz_day('start', lon=171.5, TZ_lon=-180.0).ts_param['R_a']
+    np.testing.assert_allclose(c, d)
+
+
+def test_sunrise_and_sunset_hours_integrate_only_the_sunlit_part():
+    # Defect caught: integrating the whole hour, netting night (negative) against day. Compare each
+    # hour's R_a with a fine numerical integral of the instantaneous extraterrestrial radiation.
+    et = nz_day('start')
+    ra = et.ts_param['R_a']
+    phi = np.deg2rad(-43.5)
+    for h in range(24):
+        # UTC labels at 171.5°E: local solar time = UTC + 11.4 h, so UTC 13-23 fall on the next solar day.
+        b0 = 2 * np.pi * (15 - 81) / 364
+        sc0 = 0.1645 * np.sin(2 * b0) - 0.1255 * np.cos(b0) - 0.025 * np.sin(b0)
+        day = 15 + int(np.floor((h + 0.5 + 0.06667 * 171.5 + sc0) / 24))
+        delta = 0.409 * np.sin(2 * np.pi * day / 365 - 1.39)
+        dr = 1 + 0.033 * np.cos(2 * np.pi * day / 365)
+        # The equation of time (S_c) is taken from the label's day, as the package does; its change
+        # across one day is under a minute.
+        t = h + (np.arange(600) + 0.5) / 600
+        w = np.pi / 12 * (((t + 0.06667 * 171.5 + sc0) % 24) - 12)
+        inst = 0.082 * dr * np.maximum(np.sin(phi) * np.sin(delta) + np.cos(phi) * np.cos(delta) * np.cos(w), 0)
+        assert ra[h] == pytest.approx(inst.mean() * 60, abs=2e-3), h

eto-2.2.0/eto/util.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+"""
+Utility functions.
+"""
+
+HOURLY = ('h', '1h')
+DAILY = ('d', '1d')
+MONTHLY = ('m', '1m')
+TIME_LABELS = ('start', 'end')
+RS_RSO_MIN = 0.3
+"""Lower limit on Rs/Rso (ASCE-EWRI 2005). FAO-56 states only the upper limit of 1; below about 0.26 its
+cloudiness factor (1.35 Rs/Rso - 0.35) turns negative, i.e. net longwave becomes a gain."""
+
+
+def is_hourly(freq):
+    """
+    True for an hourly frequency, False for daily or monthly; anything else raises.
+
+    Accepted (case-insensitive): 'h' / '1h' (hourly), 'D' / '1D' (daily), 'M' / '1M' (monthly). The
+    equations assume exactly these periods, so other strings ('3h', '30min', 'T', 'month') are refused
+    rather than silently computed with the wrong period.
+    """
+    f = str(freq).lower()
+    if f in HOURLY:
+        return True
+    if f in DAILY or f in MONTHLY:
+        return False
+    raise ValueError(f'Unsupported frequency {freq!r}: use "h" (hourly), "D" (daily) or "M" (monthly)')

eto-2.1.0/eto/util.py

@@ -1,4 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-Utility functions.
-"""