API

This part of the documentation shows the full API reference of all public functions.

Evapotranspiration

pyeto.fao56_penman_monteith(net_rad, t, ws, svp, avp, delta_svp, psy, shf=0.0)

Estimate reference evapotranspiration (ETo) from a hypothetical short grass reference surface using the FAO-56 Penman-Monteith equation.

Based on equation 6 in Allen et al (1998).

Parameters:

• net_rad – Net radiation at crop surface [MJ m-2 day-1]. If necessary this can be estimated using net_rad().
• t – Air temperature at 2 m height [deg Kelvin].
• ws – Wind speed at 2 m height [m s-1]. If not measured at 2m, convert using wind_speed_at_2m().
• svp – Saturation vapour pressure [kPa]. Can be estimated using ``svp_from_t()’’.
• avp – Actual vapour pressure [kPa]. Can be estimated using a range of functions with names beginning with ‘avp_from’.
• delta_svp – Slope of saturation vapour pressure curve [kPa degC-1]. Can be estimated using delta_svp().
• psy – Psychrometric constant [kPa deg C]. Can be estimatred using psy_const_of_psychrometer() or psy_const().
• shf – Soil heat flux (G) [MJ m-2 day-1] (default is 0.0, which is reasonable for a daily or 10-day time steps). For monthly time steps shf can be estimated using monthly_soil_heat_flux() or monthly_soil_heat_flux2().

Returns:

Reference evapotranspiration (ETo) from a hypothetical grass reference surface [mm day-1].

Return type:

float

pyeto.hargreaves(tmin, tmax, tmean, et_rad)

Estimate reference evapotranspiration over grass (ETo) using the Hargreaves equation.

Generally, when solar radiation data, relative humidity data and/or wind speed data are missing, it is better to estimate them using the functions available in this module, and then calculate ETo the FAO Penman-Monteith equation. However, as an alternative, ETo can be estimated using the Hargreaves ETo equation.

Based on equation 52 in Allen et al (1998).

Parameters:

• tmin – Minimum daily temperature [deg C]
• tmax – Maximum daily temperature [deg C]
• tmean – Mean daily temperature [deg C]. If emasurements not available it can be estimated as (tmin + tmax) / 2.
• et_rad – Extraterrestrial radiation (Ra) [MJ m-2 day-1]. Can be estimated using et_rad().

Returns:

Reference evapotranspiration over grass (ETo) [mm day-1]

Return type:

float

pyeto.thornthwaite(monthly_t, monthly_mean_dlh, year=None)

Estimate monthly potential evapotranspiration (PET) using the Thornthwaite (1948) method.

Thornthwaite equation:

PET = 1.6 (L/12) (N/30) (10*Ta* / I)***a*

where:

• Ta is the mean daily air temperature [deg C, if negative use 0] of the month being calculated
• N is the number of days in the month being calculated
• L is the mean day length [hours] of the month being calculated
• a = (6.75 x 10-7)*I***3 - (7.71 x 10-5)*I***2 + (1.792 x 10-2)*I* + 0.49239
• I is a heat index which depends on the 12 monthly mean temperatures and is calculated as the sum of (Tai / 5)**1.514 for each month, where Tai is the air temperature for each month in the year

Parameters:

• monthly_t – Iterable containing mean daily air temperature for each month of the year [deg C].
• monthly_mean_dlh – Iterable containing mean daily daylight hours for each month of the year (hours]. These can be calculated using monthly_mean_daylight_hours().
• year – Year for which PET is required. The only effect of year is to change the number of days in February to 29 if it is a leap year. If it is left as the default (None), then the year is assumed not to be a leap year.

Returns:

Estimated monthly potential evaporation of each month of the year [mm/month]

Return type:

List of floats

Atmospheric pressure

pyeto.atm_pressure(altitude)

Estimate atmospheric pressure from altitude.

Calculated using a simplification of the ideal gas law, assuming 20 degrees Celsius for a standard atmosphere. Based on equation 7, page 62 in Allen et al (1998).

Parameters:altitude – Elevation/altitude above sea level [m] Returns:atmospheric pressure [kPa] Return type:float

Daylight hours

pyeto.daylight_hours(sha)

Calculate daylight hours from sunset hour angle.

Based on FAO equation 34 in Allen et al (1998).

Parameters:sha – Sunset hour angle [rad]. Can be calculated using sunset_hour_angle(). Returns:Daylight hours. Return type:float

pyeto.monthly_mean_daylight_hours(latitude, year=None)

Calculate mean daylight hours for each month of the year for a given latitude.

Parameters:

• latitude – Latitude [radians]
• year – Year for the daylight hours are required. The only effect of year is to change the number of days in Feb to 29 if it is a leap year. If left as the default, None, then a normal (non-leap) year is assumed.

Returns:

Mean daily daylight hours of each month of a year [hours]

Return type:

List of floats.

Humidity

Actual vapour pressure (ea)

pyeto.avp_from_rhmax(svp_tmin, rh_max)

Estimate actual vapour pressure (*e*a) from saturation vapour pressure at daily minimum temperature and maximum relative humidity

Based on FAO equation 18 in Allen et al (1998).

Parameters:

• svp_tmin – Saturation vapour pressure at daily minimum temperature [kPa]. Can be estimated using svp_from_t().
• rh_max – Maximum relative humidity [%]

Returns:

Actual vapour pressure [kPa]

Return type:

float

pyeto.avp_from_rhmean(svp_tmin, svp_tmax, rh_mean)

Estimate actual vapour pressure (ea) from saturation vapour pressure at daily minimum and maximum temperature, and mean relative humidity.

Based on FAO equation 19 in Allen et al (1998).

Parameters:

• svp_tmin – Saturation vapour pressure at daily minimum temperature [kPa]. Can be estimated using svp_from_t().
• svp_tmax – Saturation vapour pressure at daily maximum temperature [kPa]. Can be estimated using svp_from_t().
• rh_mean – Mean relative humidity [%] (average of RH min and RH max).

Returns:

Actual vapour pressure [kPa]

Return type:

float

pyeto.avp_from_rhmin_rhmax(svp_tmin, svp_tmax, rh_min, rh_max)

Estimate actual vapour pressure (ea) from saturation vapour pressure and relative humidity.

Based on FAO equation 17 in Allen et al (1998).

Parameters:

• svp_tmin – Saturation vapour pressure at daily minimum temperature [kPa]. Can be estimated using svp_from_t().
• svp_tmax – Saturation vapour pressure at daily maximum temperature [kPa]. Can be estimated using svp_from_t().
• rh_min – Minimum relative humidity [%]
• rh_max – Maximum relative humidity [%]

Returns:

Actual vapour pressure [kPa]

Return type:

float

pyeto.avp_from_tdew(tdew)

Estimate actual vapour pressure (ea) from dewpoint temperature.

Based on equation 14 in Allen et al (1998). As the dewpoint temperature is the temperature to which air needs to be cooled to make it saturated, the actual vapour pressure is the saturation vapour pressure at the dewpoint temperature.

This method is preferable to calculating vapour pressure from minimum temperature.

Parameters:tdew – Dewpoint temperature [deg C] Returns:Actual vapour pressure [kPa] Return type:float

pyeto.avp_from_tmin(tmin)

Estimate actual vapour pressure (ea) from minimum temperature.

This method is to be used where humidity data are lacking or are of questionable quality. The method assumes that the dewpoint temperature is approximately equal to the minimum temperature (tmin), i.e. the air is saturated with water vapour at tmin.

Note: This assumption may not hold in arid/semi-arid areas. In these areas it may be better to subtract 2 deg C from the minimum temperature (see Annex 6 in FAO paper).

Based on equation 48 in Allen et al (1998).

Parameters:tmin – Daily minimum temperature [deg C] Returns:Actual vapour pressure [kPa] Return type:float

pyeto.avp_from_twet_tdry(twet, tdry, svp_twet, psy_const)

Estimate actual vapour pressure (ea) from wet and dry bulb temperature.

Based on equation 15 in Allen et al (1998). As the dewpoint temperature is the temperature to which air needs to be cooled to make it saturated, the actual vapour pressure is the saturation vapour pressure at the dewpoint temperature.

This method is preferable to calculating vapour pressure from minimum temperature.

Values for the psychrometric constant of the psychrometer (psy_const) can be calculated using psyc_const_of_psychrometer().

Parameters:

• twet – Wet bulb temperature [deg C]
• tdry – Dry bulb temperature [deg C]
• svp_twet – Saturated vapour pressure at the wet bulb temperature [kPa]. Can be estimated using svp_from_t().
• psy_const – Psychrometric constant of the pyschrometer [kPa deg C-1]. Can be estimated using psy_const() or psy_const_of_psychrometer().

Returns:

Actual vapour pressure [kPa]

Return type:

float

Saturated vapour pressure (es)

pyeto.delta_svp(t)

Estimate the slope of the saturation vapour pressure curve at a given temperature.

Based on equation 13 in Allen et al (1998). If using in the Penman-Monteith t should be the mean air temperature.

Parameters:t – Air temperature [deg C]. Use mean air temperature for use in Penman-Monteith. Returns:Saturation vapour pressure [kPa degC-1] Return type:float

pyeto.mean_svp(tmin, tmax)

Estimate mean saturation vapour pressure, es [kPa] from minimum and maximum temperature.

Based on equations 11 and 12 in Allen et al (1998).

Mean saturation vapour pressure is calculated as the mean of the saturation vapour pressure at tmax (maximum temperature) and tmin (minimum temperature).

Parameters:

• tmin – Minimum temperature [deg C]
• tmax – Maximum temperature [deg C]

Returns:

Mean saturation vapour pressure (es) [kPa]

Return type:

float

pyeto.svp_from_t(t)

Estimate saturation vapour pressure (es) from air temperature.

Based on equations 11 and 12 in Allen et al (1998).

Parameters:t – Temperature [deg C] Returns:Saturation vapour pressure [kPa] Return type:float

Relative humidity (RH)

pyeto.rh_from_avp_svp(avp, svp)

Calculate relative humidity as the ratio of actual vapour pressure to saturation vapour pressure at the same temperature.

See Allen et al (1998), page 67 for details.

Parameters:

• avp – Actual vapour pressure [units do not matter so long as they are the same as for svp]. Can be estimated using functions whose name begins with ‘avp_from’.
• svp – Saturated vapour pressure [units do not matter so long as they are the same as for avp]. Can be estimated using svp_from_t().

Returns:

Relative humidity [%].

Return type:

float

Pyschrometric constant

pyeto.psy_const(atmos_pres)

Calculate the psychrometric constant.

This method assumes that the air is saturated with water vapour at the minimum daily temperature. This assumption may not hold in arid areas.

Based on equation 8, page 95 in Allen et al (1998).

Parameters:atmos_pres – Atmospheric pressure [kPa]. Can be estimated using atm_pressure(). Returns:Psychrometric constant [kPa degC-1]. Return type:float

pyeto.psy_const_of_psychrometer(psychrometer, atmos_pres)

Calculate the psychrometric constant for different types of psychrometer at a given atmospheric pressure.

Based on FAO equation 16 in Allen et al (1998).

Parameters:

• psychrometer –

  Integer between 1 and 3 which denotes type of psychrometer: 1. ventilated (Asmann or aspirated type) psychrometer with

  an air movement of approximately 5 m/s

  2. natural ventilated psychrometer with an air movement of approximately 1 m/s
  3. non ventilated psychrometer installed indoors
• atmos_pres – Atmospheric pressure [kPa]. Can be estimated using atm_pressure().

Returns:

Psychrometric constant [kPa degC-1].

Return type:

float

Radiation

pyeto.cs_rad(altitude, et_rad)

Estimate clear sky radiation from altitude and extraterrestrial radiation.

Based on equation 37 in Allen et al (1998) which is recommended when calibrated Angstrom values are not available.

Parameters:

• altitude – Elevation above sea level [m]
• et_rad – Extraterrestrial radiation [MJ m-2 day-1]. Can be estimated using et_rad().

Returns:

Clear sky radiation [MJ m-2 day-1]

Return type:

float

pyeto.et_rad(latitude, sol_dec, sha, ird)

Estimate daily extraterrestrial radiation (Ra, ‘top of the atmosphere radiation’).

Based on equation 21 in Allen et al (1998). If monthly mean radiation is required make sure sol_dec. sha and irl have been calculated using the day of the year that corresponds to the middle of the month.

Note: From Allen et al (1998): “For the winter months in latitudes greater than 55 degrees (N or S), the equations have limited validity. Reference should be made to the Smithsonian Tables to assess possible deviations.”

Parameters:

• latitude – Latitude [radians]
• sol_dec – Solar declination [radians]. Can be calculated using sol_dec().
• sha – Sunset hour angle [radians]. Can be calculated using sunset_hour_angle().
• ird – Inverse relative distance earth-sun [dimensionless]. Can be calculated using inv_rel_dist_earth_sun().

Returns:

Daily extraterrestrial radiation [MJ m-2 day-1]

Return type:

float

pyeto.net_in_sol_rad(sol_rad, albedo=0.23)

Calculate net incoming solar (or shortwave) radiation from gross incoming solar radiation, assuming a grass reference crop.

Net incoming solar radiation is the net shortwave radiation resulting from the balance between incoming and reflected solar radiation. The output can be converted to equivalent evaporation [mm day-1] using energy2evap().

Based on FAO equation 38 in Allen et al (1998).

Parameters:

• sol_rad – Gross incoming solar radiation [MJ m-2 day-1]. If necessary this can be estimated using functions whose name begins with ‘sol_rad_from’.
• albedo – Albedo of the crop as the proportion of gross incoming solar radiation that is reflected by the surface. Default value is 0.23, which is the value used by the FAO for a short grass reference crop. Albedo can be as high as 0.95 for freshly fallen snow and as low as 0.05 for wet bare soil. A green vegetation over has an albedo of about 0.20-0.25 (Allen et al, 1998).

Returns:

Net incoming solar (or shortwave) radiation [MJ m-2 day-1].

Return type:

float

pyeto.net_out_lw_rad(tmin, tmax, sol_rad, cs_rad, avp)

Estimate net outgoing longwave radiation.

This is the net longwave energy (net energy flux) leaving the earth’s surface. It is proportional to the absolute temperature of the surface raised to the fourth power according to the Stefan-Boltzmann law. However, water vapour, clouds, carbon dioxide and dust are absorbers and emitters of longwave radiation. This function corrects the Stefan- Boltzmann law for humidity (using actual vapor pressure) and cloudiness (using solar radiation and clear sky radiation). The concentrations of all other absorbers are assumed to be constant.

The output can be converted to equivalent evaporation [mm day-1] using energy2evap().

Based on FAO equation 39 in Allen et al (1998).

Parameters:

• tmin – Absolute daily minimum temperature [degrees Kelvin]
• tmax – Absolute daily maximum temperature [degrees Kelvin]
• sol_rad – Solar radiation [MJ m-2 day-1]. If necessary this can be estimated using sol+rad().
• cs_rad – Clear sky radiation [MJ m-2 day-1]. Can be estimated using cs_rad().
• avp – Actual vapour pressure [kPa]. Can be estimated using functions with names beginning with ‘avp_from’.

Returns:

Net outgoing longwave radiation [MJ m-2 day-1]

Return type:

float

pyeto.net_rad(ni_sw_rad, no_lw_rad)

Calculate daily net radiation at the crop surface, assuming a grass reference crop.

Net radiation is the difference between the incoming net shortwave (or solar) radiation and the outgoing net longwave radiation. Output can be converted to equivalent evaporation [mm day-1] using energy2evap().

Based on equation 40 in Allen et al (1998).

Parameters:

• ni_sw_rad – Net incoming shortwave radiation [MJ m-2 day-1]. Can be estimated using net_in_sol_rad().
• no_lw_rad – Net outgoing longwave radiation [MJ m-2 day-1]. Can be estimated using net_out_lw_rad().

Returns:

Daily net radiation [MJ m-2 day-1].

Return type:

float

pyeto.sol_rad_from_sun_hours(daylight_hours, sunshine_hours, et_rad)

Calculate incoming solar (or shortwave) radiation, Rs (radiation hitting a horizontal plane after scattering by the atmosphere) from relative sunshine duration.

If measured radiation data are not available this method is preferable to calculating solar radiation from temperature. If a monthly mean is required then divide the monthly number of sunshine hours by number of days in the month and ensure that et_rad and daylight_hours was calculated using the day of the year that corresponds to the middle of the month.

Based on equations 34 and 35 in Allen et al (1998).

Parameters:

• dl_hours – Number of daylight hours [hours]. Can be calculated using daylight_hours().
• sunshine_hours – Sunshine duration [hours].
• et_rad – Extraterrestrial radiation [MJ m-2 day-1]. Can be estimated using et_rad().

Returns:

Incoming solar (or shortwave) radiation [MJ m-2 day-1]

Return type:

float

pyeto.sol_rad_from_t(et_rad, cs_rad, tmin, tmax, coastal)

Estimate incoming solar (or shortwave) radiation, Rs, (radiation hitting a horizontal plane after scattering by the atmosphere) from min and max temperature together with an empirical adjustment coefficient for ‘interior’ and ‘coastal’ regions.

The formula is based on equation 50 in Allen et al (1998) which is the Hargreaves radiation formula (Hargreaves and Samani, 1982, 1985). This method should be used only when solar radiation or sunshine hours data are not available. It is only recommended for locations where it is not possible to use radiation data from a regional station (either because climate conditions are heterogeneous or data are lacking).

NOTE: this method is not suitable for island locations due to the moderating effects of the surrounding water.

Parameters:

• et_rad – Extraterrestrial radiation [MJ m-2 day-1]. Can be estimated using et_rad().
• cs_rad – Clear sky radiation [MJ m-2 day-1]. Can be estimated using cs_rad().
• tmin – Daily minimum temperature [deg C].
• tmax – Daily maximum temperature [deg C].
• coastal – True if site is a coastal location, situated on or adjacent to coast of a large land mass and where air masses are influenced by a nearby water body, False if interior location where land mass dominates and air masses are not strongly influenced by a large water body.

Returns:

Incoming solar (or shortwave) radiation (Rs) [MJ m-2 day-1].

Return type:

float

pyeto.sol_rad_island(et_rad)

Estimate incoming solar (or shortwave) radiation, Rs (radiation hitting a horizontal plane after scattering by the atmosphere) for an island location.

An island is defined as a land mass with width perpendicular to the coastline <= 20 km. Use this method only if radiation data from elsewhere on the island is not available.

NOTE: This method is only applicable for low altitudes (0-100 m) and monthly calculations.

Based on FAO equation 51 in Allen et al (1998).

Parameters:et_rad – Extraterrestrial radiation [MJ m-2 day-1]. Can be estimated using et_rad(). Returns:Incoming solar (or shortwave) radiation [MJ m-2 day-1]. Return type:float

Soil heat flux

pyeto.monthly_soil_heat_flux(t_month_prev, t_month_next)

Estimate monthly soil heat flux (Gmonth) from the mean air temperature of the previous and next month, assuming a grass crop.

Based on equation 43 in Allen et al (1998). If the air temperature of the next month is not known use monthly_soil_heat_flux2() instead. The resulting heat flux can be converted to equivalent evaporation [mm day-1] using energy2evap().

Parameters:

• t_month_prev – Mean air temperature of the previous month [deg Celsius]
• t_month2_next – Mean air temperature of the next month [deg Celsius]

Returns:

Monthly soil heat flux (Gmonth) [MJ m-2 day-1]

Return type:

float

pyeto.monthly_soil_heat_flux2(t_month_prev, t_month_cur)

Estimate monthly soil heat flux (Gmonth) [MJ m-2 day-1] from the mean air temperature of the previous and current month, assuming a grass crop.

Based on equation 44 in Allen et al (1998). If the air temperature of the next month is available, use monthly_soil_heat_flux() instead. The resulting heat flux can be converted to equivalent evaporation [mm day-1] using energy2evap().

Arguments: :param t_month_prev: Mean air temperature of the previous month

[deg Celsius]

Parameters:t_month_cur – Mean air temperature of the current month [deg Celsius] Returns:Monthly soil heat flux (Gmonth) [MJ m-2 day-1] Return type:float

Solar angles etc.

pyeto.inv_rel_dist_earth_sun(day_of_year)

Calculate the inverse relative distance between earth and sun from day of the year.

Based on FAO equation 23 in Allen et al (1998).

Parameters:day_of_year – Day of the year [1 to 366] Returns:Inverse relative distance between earth and the sun Return type:float

pyeto.sol_dec(day_of_year)

Calculate solar declination from day of the year.

Based on FAO equation 24 in Allen et al (1998).

Parameters:day_of_year – Day of year integer between 1 and 365 or 366). Returns:solar declination [radians] Return type:float

pyeto.sunset_hour_angle(latitude, sol_dec)

Calculate sunset hour angle (Ws) from latitude and solar declination.

Based on FAO equation 25 in Allen et al (1998).

Parameters:

• latitude – Latitude [radians]. Note: latitude should be negative if it in the southern hemisphere, positive if in the northern hemisphere.
• sol_dec – Solar declination [radians]. Can be calculated using sol_dec().

Returns:

Sunset hour angle [radians].

Return type:

float

Temperature

pyeto.daily_mean_t(tmin, tmax)

Estimate mean daily temperature from the daily minimum and maximum temperatures.

Parameters:

• tmin – Minimum daily temperature [deg C]
• tmax – Maximum daily temperature [deg C]

Returns:

Mean daily temperature [deg C]

Return type:

float

Wind speed

pyeto.wind_speed_2m(ws, z)

Convert wind speed measured at different heights above the soil surface to wind speed at 2 m above the surface, assuming a short grass surface.

Based on FAO equation 47 in Allen et al (1998).

Parameters:

• ws – Measured wind speed [m s-1]
• z – Height of wind measurement above ground surface [m]

Returns:

Wind speed at 2 m above the surface [m s-1]

Return type:

float

Constants

pyeto.fao.SOLAR_CONSTANT = 0.082

Solar constant [ MJ m-2 min-1]

pyeto.fao.STEFAN_BOLTZMANN_CONSTANT = 4.903e-09

Stefan Boltzmann constant [MJ K-4 m-2 day-1]

Unit conversion

pyeto.celsius2kelvin(celsius)

Convert temperature in degrees Celsius to degrees Kelvin.

Parameters:celsius – Degrees Celsius Returns:Degrees Kelvin Return type:float

pyeto.deg2rad(degrees)

Convert angular degrees to radians

Parameters:degrees – Value in degrees to be converted. Returns:Value in radians Return type:float

pyeto.energy2evap(energy)

Convert energy (e.g. radiation energy) in MJ m-2 day-1 to the equivalent evaporation, assuming a grass reference crop.

Energy is converted to equivalent evaporation using a conversion factor equal to the inverse of the latent heat of vapourisation (1 / lambda = 0.408).

Based on FAO equation 20 in Allen et al (1998).

Parameters:energy – Energy e.g. radiation or heat flux [MJ m-2 day-1]. Returns:Equivalent evaporation [mm day-1]. Return type:float

pyeto.kelvin2celsius(kelvin)

Convert temperature in degrees Kelvin to degrees Celsius.

Parameters:kelvin – Degrees Kelvin Returns:Degrees Celsius Return type:float

pyeto.rad2deg(radians)

Convert radians to angular degrees

Parameters:radians – Value in radians to be converted. Returns:Value in angular degrees Return type:float