eexarray
A Python interface between Earth Engine and xarray
Description
eexarray was built to make processing gridded, mesoscale time series data quick and easy by integrating the data catalog and processing power of Google Earth Engine with the n-dimensional array functionality of xarray, with no complicated setup required.
Features
- Time series image collections to xarray in one line of code
- Images and image collections to GeoTIFF
- Support for masked nodata values
- Parallel processing for fast downloads
Features Coming Soon
- Temporal resampling in EE (hourly to daily, daily to monthly, etc.)
- Basic weather and climate processing implemented in EE
- Automated splitting of download requests that exceed size limits (no promises here...)
Installation
Pip and Conda coming soon...
From source
git clone https://github.com/aazuspan/eexarray
cd eexarray
make install
Quickstart
Check out the full documentation here.
Using the eex Accessor
eexarray uses the eex
accessor to extend Earth Engine classes. Just import eexarray and use .eex
to access eexarray methods.
import ee, eexarray
ee.Initialize()
ee.Image( ... ).eex
ee.ImageCollection( ... ).eex
Converting an Image Collection xarray
import ee, eexarray
ee.Initialize()
col = ee.ImageCollection("IDAHO_EPSCOR/GRIDMET").filterDate("2020-09-08", "2020-09-15")
arr = col.eex.to_xarray(scale=40_000, crs="EPSG:5070")
Downloading Images to GeoTIFF
import ee, eexarray
ee.Initialize()
img = ee.Image("COPERNICUS/S2_SR/20200803T181931_20200803T182946_T11SPA")
img.eex.to_tif(out_dir="data", scale=200, crs="EPSG:5070")
Limitations
eexarray avoids the hassle of Google Drive, Google Cloud, and service accounts by using Earth Engine's URL download system. The upside is one-liner downloads with no setup required. The downside is strict size limits for image requests. If you run into download issues, try using a larger scale or splitting images into smaller regions.
If eexarray is too limiting (i.e. high-volume users or embedded web apps), check out restee.
Aside from download limits, eexarray is in early, active development. There may be bugs or code-breaking changes (but I'll try to keep them to a minimum).
Known Bugs
Downloading imagery from Earth Engine can fail due to communication issues with Google's servers. eexarray will automatically retry failed downloads, but if downloads continue to fail you can try 1) setting the max_attempts
argument to a higher value or 2) waiting a few minutes and re-running your download.
Contributing
Bugs or feature requests are always appreciated! They can be submitted here.
Code contributions are also welcome! Please open an issue to discuss implementation, then follow the steps below.
Developer Setup
-
Create a fork of eexarray.
-
Download and install the package and developer dependencies from your fork.
git clone https://github.com/{username}/eexarray
cd eexarray
make install-dev
- Install pre-commit hooks to automate formatting and type-checking.
make install-hooks
- Create a new feature branch.
git checkout -b {feature-name}
- Write features and tests and commit them (all pre-commit checks must pass). Add NumPy-style docstrings and type hints for any new functions, methods, or classes.
git add {modified file(s)}
git commit -m "{commit message}"
- Rebuild documentation when docstrings are added or changed.
make docs
make view-docs