geeet 0.3.0

Evapotranspiration (ET) models for use in python and with integration into Google Earth Engine.

geeet

Evapotranspiration (ET) models for use in python and with integration into Google Earth Engine.

geeet provides hybrid evapotranspiration (ET) models that work with numerical values and with Google Earth Engine images.

• GitHub repo: https://github.com/kaust-halo/geeet
• PyPI: https://pypi.org/project/geeet/
• Conda-forge: https://anaconda.org/conda-forge/geeet
• Free software: MIT license

Inputs to geeet models can be given as numpy arrays, an xarray.Dataset, or a ee.Image.

Introduction

geeet is a Python package providing a common set of building blocks for estimating evapotranspiration (ET) from remote sensing observations. It also features complete ET models such as PT-JPL and TSEB. All modules in geeet are designed to work with input data provided in two formats: (1) as numpy ndarrays and (2) as Google Earth Engine (GEE) images. GEE is a cloud-based platform dedicated to Earth observation research that offers a multi-petabyte catalogue of geospatial data. Importantly, GEE offers cloud computing capabilities, which means that a user can interact with this geospatial data directly without having to download or process any data on premises. Access to these cloud-based services requires signing up for a GEE account. The geeet Python package was created to offer ET modeling tools that work for any user, whether they have a GEE account or not. For this reason, numpy is the only requirement for geeet.

Integration of geeet with xarray and especially lazy evaluation using dask is currently under development, with the goal of estimating ET using cloud-based assets (e.g., Cloud Optimized Geotiffs through a Spatio Temporal Asset Catalog (STAC)).

Installation

geeet is available on the Python Package Index (pip). To install geeet using pip, run this command:

pip install geeet

If you want to install the latest development version hosted on github, run this command:

pip install git+https://github.com/kaust-halo/geeet

geeet is also available on conda-forge. To install geeet using conda, run this command:

conda install -c conda-forge geeet

The only requirement is a modern python installation (e.g. >3.7) and numpy. However, to test any of the GEE capabilities of geeet you will need to install the Python earthengine API (available through pip and conda), and have a GEE account.

Quick start

If you have a GEE account and the earthengine API installed, we recommend first taking a look at this notebook demonstrating the basic use of the hybrid ET models with a simple toy example. In a nutshell, running one of the pre-built models can be done in two lines of code, e.g.:

from geeet.tseb import import tseb_series
et_tseb = tseb_series(img = sample_tseb_inputs) 

where sample_tseb_inputs is either a ee.Image or xarray.Dataset containing all the necessary inputs for the TSEB model.

geeet models can also be mapped to an ee.ImageCollection, e.g.:

from geeet.ptjpl import ptjpl_arid
et_outputs = et_inputs.map(ptjpl_arid)

where et_inputs is an ee.ImageCollection with the required inputs.

PT-JPL model for arid environments (as described in Aragon et al., 2018)

This notebook is a self-contained example that demonstrates the use of real GEE datasets with this PT-JPL model.

You can preview a pre-processed output of this example here (requires a GEE account).

Two-source Energy Balance model (TSEB)

geeet includes a two-source energy balance model mostly based on the original parameterizations of Norman et al., 1995. Specifically, it initializes the estimates of the temperatures of the soil and the canopy layers using a Priestley-Taylor equation. It then iteratively updates the temperatures, energy fluxes, and resistance values using the in-series resistance network parameterization.

A pre-defined TSEB model with Landsat images and ERA5 climate reanalysis data is also available. Learn how to use this model here, specifically:

1. Prepare a merged Landsat collection (Landsat 7, 8, and 9)
2. Prepare a joint Landsat + ERA5 image collection
3. Map TSEB onto the Landsat+ERA5 collection (see also this example)

Xarray and COG support

This example demonstrates reading a Cloud-Optimized Geotiff (COG) using rioxarray and running the same TSEB model with this image.

References

References for each model are found in REFERENCES.txt. The source code for each module contains references for each function as well. Finally, each model contains two functions to display the references: cite() shows the main citation for the model, while cite_all() shows all the references for that model.

If you use this package for research, please cite the relevant model references.

Contributions

Contributions are welcome. Please open an issue to:

• suggest a relevant ET model
• report a bug
• report an issue

Feel free to submit a pull request for suggesting code improvements.

Credits

This package was created with Cookiecutter and the giswqs/pypackage project template.