Skip to content

Commit 56c7923

Browse files
jdbcodejdbcode
authored
Merge PR #275: v0.1.0 explicit grid + CF dims
2 parents 19c1284 + bebe2f8 commit 56c7923

34 files changed

Lines changed: 2541 additions & 852 deletions

‎.github/workflows/publish.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ jobs:
2525
- name: Set up Python
2626
uses: actions/setup-python@v6
2727
with:
28-
python-version: '3.10'
28+
python-version: "3.13"
2929

3030
- name: Install dependencies
3131
run: |
@@ -53,7 +53,7 @@ jobs:
5353
- uses: actions/setup-python@v6
5454
name: Install Python
5555
with:
56-
python-version: '3.10'
56+
python-version: '3.13'
5757
- uses: actions/download-artifact@v6
5858
with:
5959
name: releases

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,4 +130,4 @@ cython_debug/
130130
.DS_Store
131131

132132
# pixi environments
133-
.pixi
133+
.pixi

‎.readthedocs.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ version: 2
88
build:
99
os: ubuntu-22.04
1010
tools:
11-
python: "3.10"
11+
python: "3.11"
1212

1313
# Build documentation in the docs/ directory with Sphinx
1414
sphinx:

‎README.md‎

Lines changed: 44 additions & 127 deletions
Original file line numberDiff line numberDiff line change
@@ -1,165 +1,82 @@
1+
> **⚠️ Breaking Change in v0.1.0**
2+
>
3+
> A major refactor was released in v0.1.0, introducing breaking changes to the Xee API. In most cases, existing code written for pre-v0.1.0 versions will require updates to remain compatible.
4+
>
5+
> - See the [Migration Guide](docs/migration-guide-v0.1.0.md) for details on updating your code.
6+
> - If you need more time to migrate, you can pin your environment to the latest pre-v0.1.0 release.
7+
18
# Xee: Xarray + Google Earth Engine
29

310
![Xee Logo](https://raw.githubusercontent.com/google/Xee/main/docs/xee-logo.png)
411

5-
_An Xarray extension for Google Earth Engine._
12+
Xee is an Xarray backend for Google Earth Engine. Open `ee.Image` / `ee.ImageCollection` objects as lazy `xarray.Dataset`s and analyze petabyte‑scale Earth data with the scientific Python stack.
613

714
[![image](https://img.shields.io/pypi/v/xee.svg)](https://pypi.python.org/pypi/xee)
815
[![image](https://static.pepy.tech/badge/xee)](https://pepy.tech/project/xee)
9-
[![Conda
10-
Recipe](https://img.shields.io/badge/recipe-xee-green.svg)](https://github.com/conda-forge/xee-feedstock)
16+
[![Conda Recipe](https://img.shields.io/badge/recipe-xee-green.svg)](https://github.com/conda-forge/xee-feedstock)
1117
[![image](https://img.shields.io/conda/vn/conda-forge/xee.svg)](https://anaconda.org/conda-forge/xee)
12-
[![Conda
13-
Downloads](https://img.shields.io/conda/dn/conda-forge/xee.svg)](https://anaconda.org/conda-forge/xee)
14-
15-
## How to use
18+
[![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/xee.svg)](https://anaconda.org/conda-forge/xee)
1619

17-
Install with pip:
20+
## Install
1821

19-
```shell
22+
```bash
2023
pip install --upgrade xee
2124
```
2225

23-
Install with conda:
26+
or
2427

25-
```shell
28+
```bash
2629
conda install -c conda-forge xee
2730
```
2831

29-
Then, authenticate Earth Engine:
30-
31-
```shell
32-
earthengine authenticate --quiet
33-
```
34-
35-
Now, in your Python environment, make the following imports:
32+
## Minimal example
3633

3734
```python
3835
import ee
39-
import xarray
40-
```
41-
42-
Next, specify your EE-registered cloud project ID and initialize the EE client
43-
with the high volume API:
44-
45-
```python
46-
ee.Initialize(
47-
project='my-project-id',
48-
opt_url='https://earthengine-highvolume.googleapis.com')
49-
```
50-
51-
Open any Earth Engine ImageCollection by specifying the Xarray engine as `'ee'`:
52-
53-
```python
54-
ds = xarray.open_dataset('ee://ECMWF/ERA5_LAND/HOURLY', engine='ee')
55-
```
56-
57-
Open all bands in a specific projection (not the Xee default):
58-
59-
```python
60-
ds = xarray.open_dataset('ee://ECMWF/ERA5_LAND/HOURLY', engine='ee',
61-
crs='EPSG:4326', scale=0.25)
62-
```
63-
64-
Open an ImageCollection (maybe, with EE-side filtering or processing):
65-
66-
```python
67-
ic = ee.ImageCollection('ECMWF/ERA5_LAND/HOURLY').filterDate(
68-
'1992-10-05', '1993-03-31')
69-
ds = xarray.open_dataset(ic, engine='ee', crs='EPSG:4326', scale=0.25)
70-
```
71-
72-
Open an ImageCollection with a specific EE projection or geometry:
73-
74-
```python
75-
ic = ee.ImageCollection('ECMWF/ERA5_LAND/HOURLY').filterDate(
76-
'1992-10-05', '1993-03-31')
77-
leg1 = ee.Geometry.Rectangle(113.33, -43.63, 153.56, -10.66)
78-
ds = xarray.open_dataset(
79-
ic,
80-
engine='ee',
81-
projection=ic.first().select(0).projection(),
82-
geometry=leg1
83-
)
84-
```
85-
86-
Open multiple ImageCollections into one `xarray.Dataset`, all with the same
87-
projection:
36+
import xarray as xr
37+
from xee import helpers
8838

89-
```python
90-
ds = xarray.open_mfdataset(
91-
['ee://ECMWF/ERA5_LAND/HOURLY', 'ee://NASA/GDDP-CMIP6'],
92-
engine='ee', crs='EPSG:4326', scale=0.25)
93-
```
94-
95-
Open a single Image by passing it to an ImageCollection:
96-
97-
```python
98-
i = ee.ImageCollection(ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318'))
99-
ds = xarray.open_dataset(i, engine='ee')
100-
```
39+
# Authenticate once (on a persistent machine):
40+
# earthengine authenticate
10141

102-
Open any Earth Engine ImageCollection to match an existing transform:
42+
project = 'PROJECT-ID' # Set your Earth Engine registered Google Cloud project ID
43+
# Initialize (high‑volume endpoint recommended for reading stored collections)
44+
ee.Initialize(project=project, opt_url='https://earthengine-highvolume.googleapis.com')
10345

104-
```python
105-
raster = rioxarray.open_rasterio(...) # assume crs + transform is set
106-
ds = xr.open_dataset(
107-
'ee://ECMWF/ERA5_LAND/HOURLY',
108-
engine='ee',
109-
geometry=tuple(raster.rio.bounds()), # must be in EPSG:4326
110-
projection=ee.Projection(
111-
crs=str(raster.rio.crs), transform=raster.rio.transform()[:6]
112-
),
113-
)
46+
# Open a dataset by matching its native grid
47+
ic = ee.ImageCollection('ECMWF/ERA5_LAND/MONTHLY_AGGR')
48+
grid = helpers.extract_grid_params(ic)
49+
ds = xr.open_dataset(ic, engine='ee', **grid)
50+
print(ds)
11451
```
11552

116-
See [examples](https://github.com/google/Xee/tree/main/examples) or
117-
[docs](https://github.com/google/Xee/tree/main/docs) for more uses and
118-
integrations.
119-
120-
## Getting help
53+
Next steps:
12154

122-
If you encounter issues using Xee, you can:
55+
- Quickstart: docs/quickstart.md
56+
- Concepts (grid params, CRS, orientation): docs/concepts.md
57+
- User Guide (workflows): docs/guide.md
12358

124-
1. Open a new or add to an existing [Xee discussion
125-
topic](https://github.com/google/Xee/discussions)
126-
2. Open an [Xee issue](https://github.com/google/Xee/issues). To increase the
127-
likelihood of the issue being resolved, use this [template Colab
128-
notebook](https://colab.research.google.com/drive/1vAgfAPhKGJd4G9ZUOzciqZ7MbqJjlMLR)
129-
to create a reproducible script.
59+
## Features
13060

131-
## How to run integration tests
61+
- Lazy, parallel pixel retrieval through Earth Engine
62+
- Flexible output grid definition (fixed resolution or fixed shape)
63+
- CF-friendly dimension order: `[time, y, x]`
64+
- Plays nicely with Xarray, Dask, and friends
13265

133-
The Xee integration tests only pass on Xee branches (no forks). Please run the
134-
integration tests locally before sending a PR. To run the tests locally,
135-
authenticate using `earthengine authenticate` and run the following:
66+
## Community & Support
13667

137-
```bash
138-
python -m unittest xee/ext_integration_test.py
139-
```
68+
- Discussions: https://github.com/google/Xee/discussions
69+
- Issues: https://github.com/google/Xee/issues
14070

141-
or
71+
## Contributing
14272

143-
```bash
144-
python -m pytest xee/ext_integration_test.py
145-
```
73+
See docs/contributing.md and sign the required CLA.
14674

14775
## License
14876

149-
This is not an official Google product.
150-
151-
```
152-
Copyright 2023 Google LLC
77+
[Apache 2.0](LICENSE)
15378

154-
Licensed under the Apache License, Version 2.0 (the "License");
155-
you may not use this file except in compliance with the License.
156-
You may obtain a copy of the License at
79+
`SPDX-License-Identifier: Apache-2.0`
15780

158-
https://www.apache.org/licenses/LICENSE-2.0
81+
This is not an official Google product.
15982

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

‎docs/README.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎docs/README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Xee Documentation (source files)
2+
3+
> **⚠️ Breaking Change in v0.1.0**
4+
>
5+
> A major refactor was released in v0.1.0, introducing breaking changes to the Xee API. In most cases, existing code written for pre-v0.1.0 versions will require updates to remain compatible.
6+
>
7+
> - See the [Migration Guide](migration-guide-v0.1.0.md) for details on updating your code.
8+
> - If you need more time to migrate, you can pin your environment to the latest pre-v0.1.0 release.
9+
10+
## For nicely rendered documentation
11+
12+
Visit **Read the Docs**: https://xee.readthedocs.io/en/latest/
13+
14+
## About this folder
15+
16+
This `docs/` folder contains the source files used to build the documentation site with Sphinx and MyST.
17+
18+
If you're browsing on GitHub:
19+
- Start from [`index.md`](index.md) for the documentation landing page
20+
- Or build the docs locally (see below)
21+
22+
## Build locally (optional)
23+
24+
```bash
25+
cd docs
26+
make html
27+
open _build/html/index.html # or xdg-open on Linux
28+
```
29+
30+
## Project information
31+
32+
For project overview and repository information, see the root [`README.md`](../README.md).

‎docs/_autosummary/xee.EarthEngineBackendArray.rst‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
xee.EarthEngineBackendArray
2+
===========================
3+
4+
.. currentmodule:: xee
5+
6+
.. autoclass:: EarthEngineBackendArray
7+
8+
9+
.. automethod:: __init__
10+
11+
12+
.. rubric:: Methods
13+
14+
.. autosummary::
15+
16+
~EarthEngineBackendArray.__init__
17+
~EarthEngineBackendArray.async_get_duck_array
18+
~EarthEngineBackendArray.async_getitem
19+
~EarthEngineBackendArray.get_duck_array
20+
21+
22+
23+
24+
25+
.. rubric:: Attributes
26+
27+
.. autosummary::
28+
29+
~EarthEngineBackendArray.ndim
30+
~EarthEngineBackendArray.size

‎docs/_autosummary/xee.EarthEngineBackendEntrypoint.rst‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
xee.EarthEngineBackendEntrypoint
2+
================================
3+
4+
.. currentmodule:: xee
5+
6+
.. autoclass:: EarthEngineBackendEntrypoint
7+
8+
9+
.. automethod:: __init__
10+
11+
12+
.. rubric:: Methods
13+
14+
.. autosummary::
15+
16+
~EarthEngineBackendEntrypoint.__init__
17+
~EarthEngineBackendEntrypoint.guess_can_open
18+
~EarthEngineBackendEntrypoint.open_dataset
19+
~EarthEngineBackendEntrypoint.open_datatree
20+
~EarthEngineBackendEntrypoint.open_groups_as_dict
21+
22+
23+
24+
25+
26+
.. rubric:: Attributes
27+
28+
.. autosummary::
29+
30+
~EarthEngineBackendEntrypoint.description
31+
~EarthEngineBackendEntrypoint.open_dataset_parameters
32+
~EarthEngineBackendEntrypoint.supports_groups
33+
~EarthEngineBackendEntrypoint.url

‎docs/_autosummary/xee.EarthEngineStore.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
xee.EarthEngineStore
2+
====================
3+
4+
.. currentmodule:: xee
5+
6+
.. autoclass:: EarthEngineStore
7+
8+
9+
.. automethod:: __init__
10+
11+
12+
.. rubric:: Methods
13+
14+
.. autosummary::
15+
16+
~EarthEngineStore.__init__
17+
~EarthEngineStore.close
18+
~EarthEngineStore.get_attrs
19+
~EarthEngineStore.get_child_store
20+
~EarthEngineStore.get_dimensions
21+
~EarthEngineStore.get_encoding
22+
~EarthEngineStore.get_parent_dimensions
23+
~EarthEngineStore.get_variables
24+
~EarthEngineStore.image_to_array
25+
~EarthEngineStore.load
26+
~EarthEngineStore.open
27+
~EarthEngineStore.open_store_variable
28+
~EarthEngineStore.project
29+
30+
31+
32+
33+
34+
.. rubric:: Attributes
35+
36+
.. autosummary::
37+
38+
~EarthEngineStore.ATTRS_VALID_TYPES
39+
~EarthEngineStore.DEFAULT_MASK_VALUE
40+
~EarthEngineStore.GETITEM_KWARGS
41+
~EarthEngineStore.PREFERRED_CHUNKS
42+
~EarthEngineStore.SCALE_UNITS
43+
~EarthEngineStore.get_info
44+
~EarthEngineStore.image_collection_properties
45+
~EarthEngineStore.image_ids

0 commit comments

Comments
 (0)