Skip to content

quickstart.md

Latest commit

 

History

History
128 lines (92 loc) · 3.44 KB

quickstart.md

File metadata and controls

128 lines (92 loc) · 3.44 KB
title Quickstart

Quickstart

Get up and running with Xee in a few minutes.

1. Install

pip install --upgrade xee

Optional (plotting): pip install matplotlib. For full installation options, see Installation.

2. Earth Engine access

You need an Earth Engine–enabled Google Cloud project. If you haven't done this yet, follow the Earth Engine Access guide.

Authenticate once on a persistent machine:

earthengine authenticate

Or inside ephemeral environments (e.g. Colab):

import ee
ee.Authenticate()

Initialize (high-volume endpoint recommended for reading stored collections):

import ee
ee.Initialize(
    project='YOUR-PROJECT-ID',
    opt_url='https://earthengine-highvolume.googleapis.com'
)

For computed collections (server-side expressions), omit opt_url to use the standard endpoint, which benefits from caching during iterative development.

3. Open your first dataset

import ee, xarray as xr
from xee import helpers

ic = ee.ImageCollection('ECMWF/ERA5_LAND/MONTHLY_AGGR')
grid = helpers.extract_grid_params(ic)  # match source projection & resolution
ds = xr.open_dataset(ic, engine='ee', **grid)
print(ds)
:class: tip

- Exploratory analysis: use `helpers.extract_grid_params(...)`.
- Fixed output shape (for model inputs): use `helpers.fit_geometry(..., grid_shape=...)`.
- Fixed physical resolution: use `helpers.fit_geometry(..., grid_scale=...)`.
- Manual `crs` / `crs_transform` / `shape_2d`: advanced alignment workflows only.

:class: note

Xee accepts both plain Earth Engine asset IDs (for example,
`ECMWF/ERA5_LAND/MONTHLY_AGGR`) and URI forms (for example,
`ee://ECMWF/ERA5_LAND/MONTHLY_AGGR`).

:class: tip

`xr.open_dataset(..., engine='ee')` is the primary user entrypoint for Xee.
For the complete, canonical parameter reference (including defaults and backend
behavior), see [Open Dataset Reference](open_dataset.md).

Plot the first time slice (matplotlib required):

ds['temperature_2m'].isel(time=0).plot()

4. Next steps

Goal Where to go
Learn grid parameter patterns Concepts
Fit a custom area or scale User Guide
API signatures API Reference
Migrate 0.0.x code Migration Guide
Performance tips Performance & Limits
Troubleshooting common issues FAQ

5. Minimal workflow recap

  1. Install Xee & authenticate EE
  2. Initialize EE client
  3. Derive grid parameters (match source or fit a geometry)
  4. Call xr.open_dataset(..., engine='ee', **grid)
  5. Use Xarray normally (select, compute, visualize, export)

6. Example: custom AOI at fixed size

AOI means area of interest.

import shapely
from xee import helpers

aoi = shapely.geometry.box(113.33, -43.63, 153.56, -10.66)  # Australia
grid = helpers.fit_geometry(
    geometry=aoi,
    grid_crs='EPSG:4326',   # degrees
    grid_shape=(256, 256)   # (width, height) pixels
)

ds = xr.open_dataset('ee://ECMWF/ERA5_LAND/MONTHLY_AGGR', engine='ee', **grid)

7. Having trouble?

See the FAQ and open a discussion if needed.