A Python Toolkit for Reference Evapotranspiration ($ET_o$ ) Calculation Directly from Pandas DataFrames
This repository provides a standardized Python implementation for estimating reference evapotranspiration (
This documentation is structured into two main sections:
-
Functional Guide: A practical overview of how to import, call, and implement the core functions for
$ET_o$ calculation within your research workflow. - Theoretical Framework: A detailed technical reference covering the underlying physical formulas, coefficient derivations, required inputs, etc. for each supported method.
pip install "git+https://github.com/RuiGao9/pyETo.git" The examples/eto_playground.ipynb notebook provides a comprehensive implementation of reference evapotranspiration (
To get started, initialize the environment by importing the core modules:
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import pyETo
# from py_eto import helpers
# from py_eto.helpers import calc_es_ea, calc_gamma, calc_pressure, calc_delta, convert_energyPreparing a dataframe and feed it to the py_eto.pm_daily funciton:
df['ETo_PM_Daily'] = py_eto.pm_daily(
t_mean=df['T'],
u2=df['u2'],
rn=convert_energy(df['Rn']),
g=df['G'],
es=calc_es_ea(df['T'], df['RH'])[0],
ea=calc_es_ea(df['T'], df['RH'])[1],
delta=calc_delta(df['T']),
gamma=calc_gamma(calc_pressure(df['Elevation']), t_mean=df['T']),
reference='short',
)Preparing a dataframe and feed it to the py_eto.pm_hourly funciton:
df['ETo_PM_Hourly'] = py_eto.pm_hourly(
t_hr=df['T'],
u2_hr=df['u2'],
rn_hr=convert_energy(df['Rn']),
es_hr=calc_es_ea(df['T'], df['rh_hr'])[0],
ea_hr=calc_es_ea(df['T'], df['rh_hr'])[1],
delta_hr=calc_delta(df['T']),
gamma_hr=calc_gamma(calc_pressure(df['Elevation']), t_mean=df['T']),
g_hr=convert_energy(df['G']),
reference='short',
)Preparing a dataframe and feed it to the py_eto.hargreaves funciton:
df['ETo_Hargreaves'], df['Ra'] = py_eto.hargreaves(
t_min=df['Tmin'],
t_max=df['Tmax'],
latitude=df['Latitude'],
doy=df['DOY'],
year=2025
)where:
-
$ET_o$ : reference ET (mm/day)
-
$T$ : air temperature at 2 m height ($\degree C$ ),required input -
$u_2$ : wind speed at 2 m height ($m/s$ ),required input -
$R_n$ : net radiation at crop surface ($Wh/m^2/day \cdot 0.0036 = MJ/m^2/day$ ),required input
-
$G$ : soil heat flux ($MJ/m^2/day$ ), usually ~0 for daily time step,optional input
-
$e_s$ : saturation vapor pressure ($kPa$ ),optional input -
$e_a$ : actual vapor pressure ($kPa$ ),optional input
-
$\Delta$ : slope of the saturation vapor pressure curve ($kPa/\degree C$ ),can be calculated -
$\gamma$ : psychrometric constant ($kPa/\degree C$ ),can be calculated
-
$C_n, C_d$ : they are parameters which can be found in the Table 8-1 below. For California (e.g., CIMIS), the short-reference parameter is used:$C_n=900, C_d=0.34$
Figure 1. Conceptual framework of the Penman-Monteith workflow, which is easy to understand how to use values from meteorological stations for $ET_o$ calculation.
where:
-
$T$ : mean daily air temperature ($\degree C$ ),required input -
$e_s(T)$ : saturation vapor pressure at temperature T ($\degree C$ ), in$kPa$ ,can be calculatedas below
where the required input
where:
-
$c_p$ : specific heat of moist air,$~1.013 \times 10^{-3}MJ/kg/^\circ C$ -
$\epsilon$ : the ratio of molecular weight of water vapor to dry air, ~$0.622$ -
$\lambda$ : the latent heat of vaporization,$2.45~MJ/kg$ -
$P$ : atmospheric pressure (kPa),optional input
-
$h$ : meters above sea level (m),required input
The physical framework remains consistent with the daily step. The difference are listed below:
-
Dynamic Aerodynamic Coefficients (
$C_n$ and$C_d$ ): These parameters are adjusted based on the reference crop type (short - grass vs. tall - alfalfa) and prevailing radiation conditions (Table 8-1). -
Diurnal Partitioning via Net Radiation (
$R_n$ ): The sign and magnitude of$R_n$ are utilized as the primary threshold to differentiate between daytime ($R_n > 0$ ) and nighttime ($R_n \le 0$ ) conditions. -
Ground Heat Flux (
$G$ ) as One Optional Input: The model provides the flexibility to utilize either measured or estimated soil heat flux data. If$G$ is directly monitored (e.g., via heat flux plates), the function prioritizes these observations for higher precision. In the absence of ground measurements, the model automatically estimates$G$ as a dynamic fraction of net radiation ($R_n$ ), applying distinct scaling factors for daytime and nighttime to capture the diurnal energy exchange between the surface and the subsurface.
where:
-
$0.0023$ : the empirical value -
$T_{max}$ : the maximum temperature in that day ($\degree C$ ) -
$T_{min}$ : the minimum temperature in that day ($\degree C$ ) -
$T_{c}$ :$\frac{T_{max}+T_{min}}{2}$ in that day ($\degree C$ ) -
$R_a$ : extraterrestrial radiation, which can be estimated by latitude and the day of the year, as explained below:
Figure 2. Conceptual framework of the Hargreaves workflow.
where:
-
$d_r$ : relative distance from the earth to the sun -
$DOY$ : day of the year -
$w_s$ : sunset hour angle (rad) -
$\phi_l$ : latitude (rad) -
$\delta$ : declination of the sun (rad) -
$\lambda$ : latent heat of vvaporization,$\lambda=2.54 MJ/kg$
- Task Committee on Revision of Manual 70. (2016, April). Evaporation, evapotranspiration, and irrigation water requirements. American Society of Civil Engineers.
- Torres, A. F., Walker, W. R., & McKee, M. (2011). Forecasting daily potential evapotranspiration using machine learning and limited climatic data. Agricultural Water Management, 98(4), 553-562.
Gao, R., Safeeq, M., & Viers, J. (2026). A Python Toolkit for Reference Evapotranspiration (
- Creation date: 2026-03-20
- Last update: 2026-03-24
- Contact: If you encounter any issues or have questions, please contact Rui Gao: