Xee: Xarray + Google Earth Engine

An Xarray extension for Google Earth Engine.

How to use

Install with pip:

pip install --upgrade xee

Install with conda:

conda install -c conda-forge xee

Then, authenticate Earth Engine:

earthengine authenticate --quiet

Now, in your Python environment, make the following imports:

import ee
import xarray

Next, initialize the EE client with the high volume API:

ee.Initialize(opt_url='https://earthengine-highvolume.googleapis.com')

Open any Earth Engine ImageCollection by specifying the Xarray engine as 'ee':

ds = xarray.open_dataset('ee://ECMWF/ERA5_LAND/HOURLY', engine='ee')

Open all bands in a specific projection (not the Xee default):

ds = xarray.open_dataset('ee://ECMWF/ERA5_LAND/HOURLY', engine='ee',
                         crs='EPSG:4326', scale=0.25)

Open an ImageCollection (maybe, with EE-side filtering or processing):

ic = ee.ImageCollection('ECMWF/ERA5_LAND/HOURLY').filterDate('1992-10-05', '1993-03-31')
ds = xarray.open_dataset(ic, engine='ee', crs='EPSG:4326', scale=0.25)

Open an ImageCollection with a specific EE projection or geometry:

ic = ee.ImageCollection('ECMWF/ERA5_LAND/HOURLY').filterDate('1992-10-05', '1993-03-31')
leg1 = ee.Geometry.Rectangle(113.33, -43.63, 153.56, -10.66)
ds = xarray.open_dataset(
    ic,
    engine='ee',
    projection=ic.first().select(0).projection(),
    geometry=leg1
)

Open multiple ImageCollections into one xarray.Dataset, all with the same projection:

ds = xarray.open_mfdataset(['ee://ECMWF/ERA5_LAND/HOURLY', 'ee://NASA/GDDP-CMIP6'],
                           engine='ee', crs='EPSG:4326', scale=0.25)

Open a single Image by passing it to an ImageCollection:

i = ee.ImageCollection(ee.Image("LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318"))
ds = xarray.open_dataset(i, engine='ee')

Open any Earth Engine ImageCollection to match an existing transform:

raster = rioxarray.open_rasterio(...) # assume crs + transform is set
ds = xr.open_dataset(
    'ee://ECMWF/ERA5_LAND/HOURLY',
    engine='ee',
    geometry=tuple(raster.rio.bounds()), # must be in EPSG:4326
    projection=ee.Projection(
        crs=str(raster.rio.crs), transform=raster.rio.transform()[:6]
    ),
)

See examples or docs for more uses and integrations.

Getting help

If you encounter issues using Xee, you can:

1. Open a new or add to an existing Xee discussion topic
2. Open a Xee issue. To increase the likelihood of the issue being resolved, use this template Colab notebook to create a reproducible script.

How to run integration tests

The Xee integration tests only pass on Xee branches (no forks). Please run the integration tests locally before sending a PR. To run the tests locally, authenticate using earthengine authenticate and run the following:

USE_ADC_CREDENTIALS=1 python -m unittest xee/ext_integration_test.py

License

This is not an official Google product.

Copyright 2023 Google LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.