Major Refactor - Explicit Pixel Grids & CF Dimensions - v0.1.0

.github/workflows/ci-build.yml

@@ -31,7 +31,6 @@ jobs:
       fail-fast: false
       matrix:
         python-version: [
-          "3.10",
           "3.11",
           "3.12",
           "3.13",

.github/workflows/publish.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.10'
+          python-version: "3.11"
 
       - name: Install dependencies
         run: |
@@ -53,7 +53,7 @@ jobs:
       - uses: actions/setup-python@v5
         name: Install Python
         with:
-          python-version: '3.10'
+          python-version: "3.11"
       - uses: actions/download-artifact@v4
         with:
           name: releases

.gitignore

@@ -130,4 +130,4 @@ cython_debug/
 .DS_Store
 
 # pixi environments
-.pixi
+.pixi

.readthedocs.yaml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.11"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

README.md

@@ -1,165 +1,82 @@
+> **⚠️ Breaking Change in v0.1.0**
+>
+> 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.
+>
+> - See the [Migration Guide](docs/migration-guide-v0.1.0.md) for details on updating your code.
+> - If you need more time to migrate, you can pin your environment to the latest pre-v0.1.0 release.
+
 # Xee: Xarray + Google Earth Engine
 
 ![Xee Logo](https://raw.githubusercontent.com/google/Xee/main/docs/xee-logo.png)
 
-_An Xarray extension for Google Earth Engine._
+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.
 
 [![image](https://img.shields.io/pypi/v/xee.svg)](https://pypi.python.org/pypi/xee)
 [![image](https://static.pepy.tech/badge/xee)](https://pepy.tech/project/xee)
-[![Conda
-Recipe](https://img.shields.io/badge/recipe-xee-green.svg)](https://github.com/conda-forge/xee-feedstock)
+[![Conda Recipe](https://img.shields.io/badge/recipe-xee-green.svg)](https://github.com/conda-forge/xee-feedstock)
 [![image](https://img.shields.io/conda/vn/conda-forge/xee.svg)](https://anaconda.org/conda-forge/xee)
-[![Conda
-Downloads](https://img.shields.io/conda/dn/conda-forge/xee.svg)](https://anaconda.org/conda-forge/xee)
-
-## How to use
+[![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/xee.svg)](https://anaconda.org/conda-forge/xee)
 
-Install with pip:
+## Install
 
-```shell
+```bash
 pip install --upgrade xee
 ```
 
-Install with conda:
+or
 
-```shell
+```bash
 conda install -c conda-forge xee
 ```
 
-Then, authenticate Earth Engine:
-
-```shell
-earthengine authenticate --quiet
-```
-
-Now, in your Python environment, make the following imports:
+## Minimal example
 
 ```python
 import ee
-import xarray
-```
-
-Next, specify your EE-registered cloud project ID and initialize the EE client
-with the high volume API:
-
-```python
-ee.Initialize(
-    project='my-project-id'
-    opt_url='https://earthengine-highvolume.googleapis.com')
-```
-
-Open any Earth Engine ImageCollection by specifying the Xarray engine as `'ee'`:
-
-```python
-ds = xarray.open_dataset('ee://ECMWF/ERA5_LAND/HOURLY', engine='ee')
-```
-
-Open all bands in a specific projection (not the Xee default):
-
-```python
-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):
-
-```python
-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:
-
-```python
-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:
+import xarray as xr
+from xee import helpers
 
-```python
-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:
-
-```python
-i = ee.ImageCollection(ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318'))
-ds = xarray.open_dataset(i, engine='ee')
-```
+# Authenticate once (on a persistent machine):
+#   earthengine authenticate
 
-Open any Earth Engine ImageCollection to match an existing transform:
+project = 'PROJECT-ID'  # Set your Earth Engine registered Google Cloud project ID
+# Initialize (high‑volume endpoint recommended for reading stored collections)
+ee.Initialize(project=project, opt_url='https://earthengine-highvolume.googleapis.com')
 
-```python
-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]
-    ),
-)
+# Open a dataset by matching its native grid
+ic = ee.ImageCollection('ECMWF/ERA5_LAND/MONTHLY_AGGR')
+grid = helpers.extract_grid_params(ic)
+ds = xr.open_dataset(ic, engine='ee', **grid)
+print(ds)
 ```
 
-See [examples](https://github.com/google/Xee/tree/main/examples) or
-[docs](https://github.com/google/Xee/tree/main/docs) for more uses and
-integrations.
-
-## Getting help
+Next steps:
 
-If you encounter issues using Xee, you can:
+- Quickstart: docs/quickstart.md
+- Concepts (grid params, CRS, orientation): docs/concepts.md
+- User Guide (workflows): docs/user-guide.md
 
-1. Open a new or add to an existing [Xee discussion
-   topic](https://github.com/google/Xee/discussions)
-2. Open an [Xee issue](https://github.com/google/Xee/issues). To increase the
-   likelihood of the issue being resolved, use this [template Colab
-   notebook](https://colab.research.google.com/drive/1vAgfAPhKGJd4G9ZUOzciqZ7MbqJjlMLR)
-   to create a reproducible script.
+## Features
 
-## How to run integration tests
+- Lazy, parallel pixel retrieval through Earth Engine
+- Flexible output grid definition (fixed resolution or fixed shape)
+- CF-friendly dimension order: `[time, y, x]`
+- Plays nicely with Xarray, Dask, and friends
 
-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:
+## Community & Support
 
-```bash
-python -m unittest xee/ext_integration_test.py
-```
+- Discussions: https://github.com/google/Xee/discussions
+- Issues: https://github.com/google/Xee/issues
 
-or
+## Contributing
 
-```bash
-python -m pytest xee/ext_integration_test.py
-```
+See docs/contributing.md and sign the required CLA.
 
 ## License
 
-This is not an official Google product.
-
-```
-Copyright 2023 Google LLC
+[Apache 2.0](LICENSE)
 
-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
+`SPDX-License-Identifier: Apache-2.0`
 
-    https://www.apache.org/licenses/LICENSE-2.0
+This is not an official Google product.
 
-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.
-```

docs/README.md

@@ -0,0 +1,32 @@
+# Xee Documentation (source files)
+
+> **⚠️ Breaking Change in v0.1.0**
+>
+> 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.
+>
+> - See the [Migration Guide](migration-guide-v0.1.0.md) for details on updating your code.
+> - If you need more time to migrate, you can pin your environment to the latest pre-v0.1.0 release.
+
+## For nicely rendered documentation
+
+Visit **Read the Docs**: https://xee.readthedocs.io/en/latest/
+
+## About this folder
+
+This `docs/` folder contains the source files used to build the documentation site with Sphinx and MyST. 
+
+If you're browsing on GitHub:
+- Start from [`index.md`](index.md) for the documentation landing page
+- Or build the docs locally (see below)
+
+## Build locally (optional)
+
+```bash
+cd docs
+make html
+open _build/html/index.html  # or xdg-open on Linux
+```
+
+## Project information
+
+For project overview and repository information, see the root [`README.md`](../README.md).

docs/_autosummary/xee.EarthEngineBackendArray.rst

@@ -0,0 +1,32 @@
+xee.EarthEngineBackendArray
+===========================
+
+.. currentmodule:: xee
+
+.. autoclass:: EarthEngineBackendArray
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~EarthEngineBackendArray.__init__
+      ~EarthEngineBackendArray.async_get_duck_array
+      ~EarthEngineBackendArray.async_getitem
+      ~EarthEngineBackendArray.get_duck_array
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~EarthEngineBackendArray.ndim
+      ~EarthEngineBackendArray.size
+
+

docs/_autosummary/xee.EarthEngineBackendEntrypoint.rst

@@ -0,0 +1,35 @@
+xee.EarthEngineBackendEntrypoint
+================================
+
+.. currentmodule:: xee
+
+.. autoclass:: EarthEngineBackendEntrypoint
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~EarthEngineBackendEntrypoint.__init__
+      ~EarthEngineBackendEntrypoint.guess_can_open
+      ~EarthEngineBackendEntrypoint.open_dataset
+      ~EarthEngineBackendEntrypoint.open_datatree
+      ~EarthEngineBackendEntrypoint.open_groups_as_dict
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~EarthEngineBackendEntrypoint.description
+      ~EarthEngineBackendEntrypoint.open_dataset_parameters
+      ~EarthEngineBackendEntrypoint.supports_groups
+      ~EarthEngineBackendEntrypoint.url
+
+