Google Earth Engine

Google Earth Engine

Purpose: use GEE's server-side model correctly. The recurring failure modes are client/server confusion (calling .getInfo() in loops, Python if on server objects), unbounded computation (timeouts from unscaled reductions), and silent default scales (statistics computed at the wrong resolution).

Should this run here at all? — Earth Engine versus local

Answer this before writing any ee. code. The decision turns on six things, and you cannot make it without them, so establish them first — asking alongside a provisional recommendation, never instead of one:

1. Archive extent and duration — area, and how many years at what revisit. This is what makes server-side worth its constraints; a single scene does not.
2. Algorithm expressibility — can the work be written as masks, reducers and band math? Anything needing arbitrary per-pixel iteration, a custom solver, or a Python library GEE does not host belongs local.
3. Data locality and sensitivity — restricted or offline data cannot be uploaded, and that ends the discussion regardless of scale.
4. Interactive limits versus batch — see Quotas and etiquette. Anything beyond a ~5 minute interactive request has to be designed as a batch export from the start, not retrofitted when getInfo times out.
5. Export volume — what actually comes back: a few reduced statistics, or full-resolution per-pixel stacks you will store and reprocess locally.
6. Reproducibility cost — the real price of moving server-side. The catalog version can shift under you and the computation leaves no local trace, so choosing GEE obliges you to ship the provenance record. State this cost when you recommend GEE; a recommendation that omits it is incomplete.

Recommend Earth Engine only when 1 and 2 favour it and 3 permits it. When the answer is genuinely balanced, say so and name the deciding question rather than defaulting to the platform this skill is about. xee and STAC + stackstac / odc-stac are the middle paths worth naming: catalog access with local compute.

Mental model — everything is deferred

ee.Image, ee.ImageCollection, ee.FeatureCollection are server-side descriptions, not data. Nothing computes until an output is requested (getInfo, export, map tile). Consequences:

• Never use Python if/for on server values — use ee.Algorithms.If sparingly, prefer .map() + filters. A Python loop that calls .getInfo() per element is the #1 GEE performance bug.
• .getInfo() blocks and transfers; use it for tiny scalars only. Anything sized → Export (to Drive/GCS/Asset).
• Debug with .aggregate_array(), .first(), .limit(3) probes — not by printing whole collections.

Canonical pipeline (Sentinel-2 cloud-free composite)

import ee
ee.Initialize(project="my-project")

aoi = ee.Geometry.Rectangle([27.0, 38.3, 27.4, 38.6])

def mask_s2(img):
    # Cloud Score+ is the current best practice (threshold ~0.5-0.65)
    cs = img.linkCollection(csplus, ["cs_cdf"]).select("cs_cdf")
    return img.updateMask(cs.gte(0.6))

csplus = ee.ImageCollection("GOOGLE/CLOUD_SCORE_PLUS/V1/S2_HARMONIZED")
s2 = (ee.ImageCollection("COPERNICUS/S2_SR_HARMONIZED")
      .filterBounds(aoi)
      .filterDate("2025-05-01", "2025-09-30")
      .map(mask_s2))
composite = s2.median().clip(aoi)
ndvi = composite.normalizedDifference(["B8", "B4"]).rename("ndvi")

Collection choices: S2_SR_HARMONIZED (post-2022 offset harmonized), LANDSAT/LC08/C02/T1_L2 + friends (apply scale factors: optical *0.0000275 - 0.2), MODIS/061/... for daily/coarse, ERA5-Land for climate. Record collection IDs + date filters in the deliverable.

Reducers and zonal statistics — scale is not optional

stats = ndvi.reduceRegions(
    collection=districts,
    reducer=ee.Reducer.mean().combine(ee.Reducer.stdDev(), sharedInputs=True),
    scale=10,                    # ALWAYS explicit — native resolution
    tileScale=4,                 # raise when "computation timed out"
)

• scale defaults to the map zoom level in some paths — silently coarse statistics. Always set it to the data's native resolution (or state the deliberate coarsening).
• bestEffort=True silently degrades scale to fit limits — avoid in analysis; prefer tileScale + exports.
• Large reductions → Export.table.toDrive, not .getInfo().
• Weighted vs unweighted reducers differ at polygon edges (.unweighted() for counts of whole pixels); state which you used.

Time series

• Build per-period composites with a mapped function over ee.List.sequence of dates (monthly/seasonal medians), then reduce — don't export daily stacks you'll aggregate anyway.
• For per-pixel trends: ee.Reducer.sensSlope() (robust) or linearFit; harmonic regression (.addBands of sin/cos terms) for phenology. Mask by count of valid observations — trends from 4 pixels of 200 possible are noise; report the count band.
• For break detection at archive scale (LandTrendr/CCDC available in GEE), method selection follows change-detection.

Classification in GEE

ee.Classifier.smileRandomForest covers most cases. Training samples via image.sampleRegions; split train/test spatially (add a grid-cell attribute and filter — random randomColumn splits leak; see ml-experiment-standards → references/spatial-cv-protocol.md). Report per-class accuracy from errorMatrix; area estimates from a classified map still need design-based adjustment (change-detection / Olofsson).

Exports and hand-off

• Export.image.toDrive/toCloudStorage with explicit region, scale, crs, maxPixels; use crsTransform when pixel alignment with an existing raster matters.
• Export > ~10⁸ pixels: shard by tiles or use toAsset intermediate.
• Hand off to the local Python stack (rasterio/xarray) via COG exports, or xee for xarray-native access; visualize interactively with geemap.

Quotas and etiquette

Batch tasks queue (check task status; don't fire hundreds blindly). Interactive requests time out at ~5 min — long jobs go to batch export. Cache intermediate products as assets when a pipeline reuses them.

Provenance record

Server-side computation is invisible after the fact: the catalog moves under you, a reducer default changes the number, and nothing in the exported file says which archive produced it. Every Earth Engine deliverable ships with a provenance record, emitted as a sidecar JSON next to the export — not left in the notebook:

• Catalog asset IDs with their version suffix (COPERNICUS/S2_SR_HARMONIZED and the specific collection version), plus the date range and filters applied.
• Mask method and thresholds — cloud probability source, threshold value, and any morphological buffer.
• Reducers and their arguments, including tileScale, bestEffort, and any crsTransform.
• Export parameters: region, scale, crs, maxPixels, and the task ID.
• Run date and the ee.__version__ / API client version, because server-side defaults change without notice.

Recommending Earth Engine over a local workflow is incomplete without this: the reproducibility cost is the main thing the user trades away by moving server-side, so state how it is recovered.

Verification protocol

1. Probe: composite.select("B4").projection().nominalScale().getInfo() and band names — confirms scale/CRS assumptions before reductions.
2. Visual check in geemap at 2 zoom levels vs a basemap.
3. Cross-check one zonal statistic against a local computation on an exported clip (catches scale/masking discrepancies).
4. Report: collection IDs, date ranges, mask method + threshold, scale, reducer types.

Pitfalls checklist

• .getInfo() inside a loop (move logic server-side).
• Missing scale in reduceRegion(s) → zoom-dependent statistics.
• Landsat C2 used without scale factors → reflectance > 1.
• bestEffort=True hiding resolution degradation.
• Median composite including cloudy pixels (mask BEFORE reduce).
• Python conditionals on server-side objects (always false-y).
• Trend maps without valid-observation-count masking.

Execution contract

• Workflow: define collection and period; build a server-side mask and transform pipeline; test on a small region; compute; verify scale and projection; export reproducibly.
• Decision rules: use Earth Engine for planetary archives and scalable aggregation, local tools for sensitive or offline data, and batch exports for work beyond interactive limits.
• Verification protocol: probe bands, projection, scale, masks, and observation counts; inspect spatial samples; cross-check one exported statistic locally; record collection versions and parameters.
• Failure modes: stop for client-side loops, implicit scale, masked-pixel bias, quota-driven silent degradation, expired assets, or unbounded region operations.
• Deliverables: runnable script, collection and date manifest, mask and reducer parameters, task/export settings, verification evidence, and exported asset inventory.
• Source freshness: consult the authoritative source registry at execution time for catalog, API, quota, and policy changes.