# geerefet Release 0.1.13

Google Earth Engine ASCE Standardized Reference Evapotranspiration Functions

Keywords
RefET, Evapotranspiration, GEE
Apache-2.0
Install
``` pip install geerefet==0.1.13 ```

# Google Earth Engine ASCE Standardized Reference Evapotranspiration (ET)

Google Earth Engine (GEE) functions for computing daily and hourly reference ET following the ASCE Standardized Reference Evapotranspiration Equations (ASCE2005).

## Usage

### Daily

The following demonstrates how to compute a single daily ETr value using weather data for 2015-07-01 from the Fallon, NV AgriMet station. The necessary unit conversions are shown on the input values. The raw input data is available here.

```import math
import ee
import geerefet

# Unit conversions
tmin_c = (66.65 - 32) * (5.0 / 9)                          # F -> C
tmax_c = (102.80 - 32) * (5.0 / 9)                         # F -> C
tdew_c = (57.26 - 32) * (5.0 / 9)                          # F -> C
ea = 0.6108 * math.exp(17.27 * tdew_c / (tdew_c + 237.3))  # kPa
rs = (674.07 * 0.041868)                                   # Langleys -> MJ m-2 d-1
uz = 4.80 * 0.44704                                        # mpg -> m s-1
lat = 39.4575                                              # degrees

etr = geerefet.Daily(
tmin=tmin_c, tmax=tmax_c, ea=ea, rs=rs, uz=uz, zw=3, elev=1208.5,
lat=lat, doy=182).etr().getInfo()

print('ETr: {:.2f} mm'.format(float(etr)))```

### Hourly

The following demonstrates how to compute a single hourly ETr value using weather data for 18:00 UTC (11:00 AM PDT) on 2015-07-01 from the Fallon, NV AgriMet station. The necessary unit conversions are shown on the input values. The raw input data is available here

```import math
import ee
import geerefet

# Unit conversions
tmean_c = (91.80 - 32) * (5.0 / 9)           # F -> C
ea = 1.20                                    # kPa
rs = (61.16 * 0.041868)                      # Langleys -> MJ m-2 h-1
uz = 3.33 * 0.44704                          # mph -> m s-1
lat = 39.4575                                # degrees
lon = -118.77388                             # degrees

etr = geerefet.Hourly(
tmean=tmean_c, ea=ea, rs=rs, uz=uz, zw=3, elev=1208.5,
lat=lat, lon=lon, doy=182, time=18).etr().getInfo()

print('ETr: {:.2f} mm'.format(float(etr)))```

### GRIDMET

A helper function for computing daily ETo and ETr for GRIDMET images is available.

```import ee
import geerefet

gridmet_img = ee.Image(ee.ImageCollection('IDAHO_EPSCOR/GRIDMET').first())
etr = geerefet.Daily.gridmet(gridmet_img).etr()\
.reduceRegion(reducer=ee.Reducer.first(),
geometry=ee.Geometry.Point(-118.77388, 39.4575),
scale=1000)\
.getInfo()

print('ETr: {:.2f} mm'.format(float(etr['etr'])))```

### NLDAS

Helper functions for computing daily/hourly ETo/ETr for NLDAS images are available.

For the daily function, the NLDAS collection must be filtered to a single 24 hour period.

```import ee
import geerefet

nldas_coll = ee.ImageCollection('NASA/NLDAS/FORA0125_H002')\
.filterDate('2015-07-01', '2015-07-02')
etr = geerefet.Daily.nldas(nldas_coll).etr()\
.reduceRegion(reducer=ee.Reducer.first(),
geometry=ee.Geometry.Point(-118.77388, 39.4575),
scale=1000)\
.getInfo()

print('ETr: {:.2f} mm'.format(float(etr['etr'])))```
```import ee
import geerefet

nldas_img = ee.Image(ee.ImageCollection('NASA/NLDAS/FORA0125_H002').first())
etr = geerefet.Hourly.nldas(nldas_img).etr()\
.reduceRegion(reducer=ee.Reducer.first(),
geometry=ee.Geometry.Point(-118.77388, 39.4575),
scale=1000)\
.getInfo()

print('ETr: {:.2f} mm'.format(float(etr['etr'])))```

## Input Parameters

### Required Parameters (hourly & daily)

Variable Type Description [units]
ea ee.Image Actual vapor pressure [kPa]
rs ee.Image Incoming shortwave solar radiation [MJ m-2 day-1]
uz ee.Image Wind speed [m s-1]
zw ee.Number Wind speed height [m]
elev ee.Image, ee.Number Elevation [m]
lat ee.Image, ee.Number Latitude [degrees]
doy ee.Image, ee.Number Day of year

### Required Daily Parameters

Variable Type Description [units]
tmin ee.Image Minimum daily temperature [C]
tmax ee.Image Maximum daily temperature [C]

### Required Hourly Parameters

Variable Type Description [units]
tmean ee.Image Average hourly temperature [C]
lon ee.Image, ee.Number Longitude [degrees]
time ee.Number UTC hour at start of time period

### Optional Parameters

Variable Type Description [units]
method str
Calculation method
• 'asce' -- Calculations will follow ASCE-EWRI 2005 (default)
• 'refet' -- Calculations will follow RefET software
rso_type str
Override default clear sky solar radiation (Rso) calculation
Defaults to None if not set
• 'full' -- Full clear sky solar formulation (default)
• 'simple' -- Simplified clear sky solar formulation (Eq. 19)
• 'array' -- Read Rso values from "rso" function parameter
rso ee.Image, ee.Number
Clear sky solar radiation [MJ m-2 day-1]
• Only needed if rso_type is 'array'
• Defaults to None if not set

## Issues

Currently the user must handle all of the file I/O and unit conversions.

### Cloudiness Fraction (hourly)

The cloudiness fraction (fcd) is computed as the ratio of the measured solar radiation (Rs) to the theoretical clear sky solar radiation (Rso). This ratio cannot be computed directly at night since Rso is 0. ASCE-EWRI 2005 suggests computing a representative nighttime fcd based on the fcd at sunset and/or sunrise.

In the RefET module fcd is hard coded to 1 for all time steps with very low sun angles since the hourly reference ET is computed independently for each time step.

## Calculation Method - ASCE vs. RefET

The main difference between the two "methods" is that the "asce" method attempts to follow the equations in ASCE2005, whereas the "refet" method attempts to follow the calculations of the RefET Software as closely as possible. The difference in output between these methods is generally negligible (if not identical for realistic numbers of significant digits). Note that the default is set to "asce" to best match the calculations a user would expect to have happen. The "refet" method was added in order to help validate this code to the RefET Software.

## Installation

To install the RefET-GEE python module:

`pip install geerefet`

## Validation

Please see the validation document for additional details on the source of the test values and the comparison of the functions to the Ref-ET software.

## Dependencies

Modules needed to run the test suite:

## References

 [ASCE2005] ASCE-EWRI (2005). The ASCE standardized reference evapotranspiration equation. https://ascelibrary.org/doi/book/10.1061/9780784408056