Docs: write for the library's reader, not the review thread

Revise the prose across the suite for the future reader/user — someone from the
SQL or Xarray world — rather than for the PR conversation:

- Frame features by what that audience values (lazy, idiomatic) instead of the
  mechanics that justified review decisions ("nothing loaded or column-selected
  up front", "bounds passed as query parameters, not formatted into the SQL",
  "no table name formatted into the SQL").
- Fix stale claims: the suite compares with xarray (not `numpy.assert_allclose`),
  Earth Engine uses your `gcloud` login (not `earthengine authenticate`), and the
  run instructions cover `run_all.sh` and the in-repo build.
- Trim jargon from runtime labels and tighten a couple of code comments.

Touches README ("Does it work?"), docs/geospatial.md, the suite README, and the
02–06 docstrings/labels. No code behavior changes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AWvrZYAT2NbuETBqNAN3o9

Author: alxmrs

README.md

@@ -152,8 +152,8 @@ against an xarray/array reference** to floating-point tolerance:
 
 * **Spectral indices** (NDVI) — column arithmetic over a real Sentinel-2 scene.
 * **Climatology, anomalies, zonal means** — `GROUP BY` and self-`JOIN` over the
-  full 0.25° **ARCO-ERA5** archive (≈1.3M hourly steps), read lazily with
-  partition pruning and column pushdown.
+  full 0.25° **ARCO-ERA5** archive (≈1.3M hourly steps), read lazily so each
+  query touches only the data it needs.
 * **Forecast skill** — scoring the **Pangu-Weather** and **GraphCast** ML models
   against ERA5 (WeatherBench 2) as a `JOIN` on `valid_time = init + lead`; it
   reproduces the published result that GraphCast beats Pangu at every lead.

benchmarks/geospatial/02_climatology.py

@@ -28,11 +28,9 @@
 ``da.groupby("time.hour").mean()``. ERA5 is hourly, so grouping by hour of day
 gives a clean 24-bin **diurnal cycle**, one sample per day in the window.
 
-The table is the *whole* lazily-opened ARCO-ERA5 archive — nothing is loaded or
-pre-selected up front. The query reads only the ``2m_temperature`` column
-(projection pushdown) for only the window the parameterized ``WHERE`` asks for
-(partition pruning). The bounds are passed as **query parameters**, not
-formatted into the SQL string.
+The table is the *whole* ARCO-ERA5 archive, opened lazily: the query reads only
+``2m_temperature``, and only over the window its ``WHERE`` asks for — the rest of
+the archive is never touched.
 """
 
 from __future__ import annotations
@@ -68,10 +66,10 @@
 
 
 def main() -> None:
-    # Open the full ARCO-ERA5 archive lazily — dask off, nothing loaded or
-    # column-selected here. ERA5 mixes surface (time, lat, lon) and atmospheric
-    # (… level …) variables, so register it as two tables under an ``era5``
-    # schema; the query below touches only the surface table's 2m_temperature.
+    # Open the full ARCO-ERA5 archive lazily — no data is read here. ERA5 mixes
+    # surface (time, lat, lon) and atmospheric (… level …) variables, so register
+    # it as two tables under an ``era5`` schema; the query below touches only the
+    # surface table's 2m_temperature.
     try:
         import gcsfs  # noqa: F401 — required by the gs:// protocol
 
@@ -107,7 +105,7 @@ def main() -> None:
 
     # A climatology is a gridded product: round-trip the result back to an
     # xarray Dataset keyed by (latitude, longitude, hour) — how it is used.
-    with timed("SQL diurnal climatology (lazy read, pushdown + pruning)"):
+    with timed("SQL diurnal climatology (lazy read)"):
         got = ctx.sql(sql, param_values=_PARAMS).to_dataset(
             dims=["latitude", "longitude", "hour"]
         )

benchmarks/geospatial/03_zonal_mean.py

@@ -86,8 +86,8 @@ def main() -> None:
             },
         )
 
-    # The window bounds are passed as query parameters, not formatted into the
-    # SQL string; pruning still kicks in, so only one day is read.
+    # Pass the day's bounds as query parameters; the query still reads only that
+    # one day out of the whole archive.
     sql = """
         SELECT latitude,
                AVG("2m_temperature") - 273.15 AS air_mean_c
@@ -99,7 +99,7 @@ def main() -> None:
     show_sql(sql)
 
     # Round-trip the profile back to an xarray Dataset keyed by latitude.
-    with timed("SQL zonal mean (WHERE-pruned to one day)"):
+    with timed("SQL zonal mean (reads one day)"):
         got = ctx.sql(
             sql, param_values={"start": _START, "end": _END}
         ).to_dataset(dims=["latitude"])

benchmarks/geospatial/04_anomaly.py

@@ -27,11 +27,9 @@
     FROM era5 a JOIN clim c
       ON (a.latitude, a.longitude, hour(a.time)) = (c.latitude, c.longitude, c.hour)
 
-The table is the *whole* lazily-opened ARCO-ERA5 archive — nothing loaded or
-column-selected up front. Both the climatology CTE and the outer scan read only
-``2m_temperature`` (projection pushdown) over only the window the parameterized
-``WHERE`` asks for (partition pruning). Bounds are query parameters, not
-string-formatted into the SQL.
+The table is the *whole* ARCO-ERA5 archive, opened lazily: both the climatology
+CTE and the outer scan read only ``2m_temperature``, and only over the window the
+``WHERE`` asks for.
 """
 
 from __future__ import annotations

benchmarks/geospatial/05_forecast_skill.py

@@ -35,9 +35,8 @@
     GROUP BY f.model, f.prediction_timedelta
 
 We stack the two models along a ``model`` dimension into a single forecast
-table, so the query groups by a ``model`` *column* — no table name is formatted
-into the SQL. Nothing is loaded up front either: the forecasts and ERA5 are
-registered lazily, and the JOIN reads only what it needs at query time.
+table, so one query scores them together, grouped by the ``model`` column. The
+forecasts and ERA5 are opened lazily, and the JOIN reads only what it needs.
 
 Datasets: WeatherBench 2 **Pangu**, **GraphCast**, and **ERA5** at a coarse
 64×32 grid (so the demo is small and fast), read from the public ``gs://
@@ -116,8 +115,8 @@ def main() -> None:
     # The two models store different pressure-level sets (Pangu 13, GraphCast
     # 37), so we keep the common surface field 2m_temperature and stack the
     # models along a `model` dimension into one forecast table. Snap the grid
-    # onto ERA5's exact coordinates (same 64×32 grid) so the equality JOIN is
-    # bit-safe across the Zarr stores.
+    # onto ERA5's exact coordinates (same 64×32 grid) so the join on latitude and
+    # longitude lines up exactly across the two Zarr stores.
     pangu = _open(_PANGU)[[_VAR]].sel(time=_INIT)
     graphcast = _open(_GRAPHCAST)[[_VAR]].sel(time=_INIT)
     forecasts = xr.concat([pangu, graphcast], dim="model").assign_coords(

benchmarks/geospatial/06_zonal_vector.py

@@ -127,7 +127,7 @@ def main() -> None:
     """
     show_sql(sql)
 
-    with timed("SQL zonal stats (raster × vector range JOIN, WHERE-pruned)"):
+    with timed("SQL zonal stats (raster × vector range JOIN)"):
         got = ctx.sql(
             sql, param_values={"start": _START, "end": _END}
         ).to_dataset(dims=["region_id"])

benchmarks/geospatial/README.md

@@ -4,9 +4,9 @@
 are, underneath, **relational** operations — `GROUP BY`, `JOIN`, window
 functions, and `CASE`. Each script here takes one such operation, expresses it
 in SQL against [`xarray-sql`](../../README.md), and **proves the SQL answer
-matches an xarray/array reference implementation** (`numpy.assert_allclose`).
-Wall-clock and peak memory are reported too, but the headline is correctness +
-clarity of the SQL.
+matches a plain-xarray reference** to floating-point tolerance. Wall-clock and
+peak memory are reported too, but the headline is correctness + clarity of the
+SQL.
 
 This suite is *expressibility-first*: the point is that the SQL reads like the
 plain-English definition of the operation, and computes the same numbers.
@@ -39,13 +39,10 @@ interpolation weights — the geometry — which SQL applies but does not comput
   (bands B04/B08). Requires network; skips cleanly if offline.
 - **02–06** — the full **[ARCO-ERA5](https://github.com/google-research/arco-era5)**
   archive (0.25° global, ~1.3M hourly timesteps, 273 variables) read anonymously
-  from a public GCS bucket. Every case registers the *whole* archive **lazily**
-  (nothing loaded or column-selected up front) and filters it with a
-  **parameterized** `WHERE` (bounds bound as query parameters, not formatted into
-  the SQL); projection pushdown reads only `2m_temperature` and partition pruning
-  reads only the window asked for. All require network (`gcsfs`); skip cleanly
-  offline. ERA5 cases take roughly one to a few minutes, dominated by the GCS
-  read (the lazy reference re-reads the same window).
+  from a public GCS bucket. Each case opens the *whole* archive lazily, so a query
+  reads only the variable and the window it asks for — never the other 272
+  variables or the rest of the timesteps. All require network (`gcsfs`) and skip
+  cleanly offline; each takes roughly one to a few minutes, dominated by the read.
 - **05 forecast skill** — the **[WeatherBench 2](https://weatherbench2.readthedocs.io/)**
   Pangu-Weather, GraphCast, and ERA5 datasets at a coarse 64×32 grid, scoring
   both ML models against ERA5 ground truth. Network-backed; runs in seconds
@@ -54,29 +51,24 @@ interpolation weights — the geometry — which SQL applies but does not comput
   07 reprojects a UTM grid and validates the SQL transform against Earth Engine's
   *own* per-pixel lon/lat (`ee.Image.pixelLonLat()`) — an independent reprojection
   reference, not PROJ-vs-PROJ. 08 regrids real **SRTM elevation** (Sierra Nevada)
-  and validates against xarray's bilinear `.interp()`. Both need EE access
-  (`earthengine authenticate` + an initialized project via `EARTHENGINE_PROJECT`)
-  and skip cleanly without it.
+  and validates against xarray's bilinear `.interp()`. Both run against Earth
+  Engine using your existing `gcloud` login, and skip cleanly without it.
 
 ## Running
 
-Inside the repo, use the project environment (so `import xarray_sql` resolves to
-the locally built native extension):
+Run a single case, or the whole suite, from any directory:
 
 ```shell
-python benchmarks/geospatial/03_zonal_mean.py
+uv run benchmarks/geospatial/03_zonal_mean.py   # one case
+benchmarks/geospatial/run_all.sh                # all of them
 ```
 
-Each script also carries [PEP 723 / `uv` inline metadata](https://docs.astral.sh/uv/guides/scripts/),
-so it can be run standalone against the published `xarray-sql` wheel:
+Each script carries [PEP 723 / `uv` inline metadata](https://docs.astral.sh/uv/guides/scripts/)
+and runs against the `xarray-sql` in this checkout.
 
-```shell
-uv run benchmarks/geospatial/03_zonal_mean.py
-```
-
-A passing case prints a `✅ … SQL matches array reference` line; a mismatch
-raises `AssertionError` and exits non-zero. Cases that need an unavailable
-dataset/dependency print `⏭ SKIPPED` and exit 0.
+A passing case prints a `✅ … SQL matches xarray reference` line and the result
+as an xarray repr; a mismatch raises `AssertionError` and exits non-zero. Cases
+that need data or credentials you don't have print `⏭ SKIPPED` and exit 0.
 
-Shared helpers (timing, peak memory, the `assert_allclose` wrapper, SQL echo)
-live in [`_harness.py`](_harness.py).
+Shared helpers — timing, peak memory, the result check and its printout, SQL
+echo — live in [`_harness.py`](_harness.py).

docs/geospatial.md

@@ -11,14 +11,11 @@ The array paradigm (NumPy, Xarray, Dask) is a wonderful *interface* for these
 operations. But it is not the only one, and for a large and growing audience —
 the people fluent in SQL rather than in `apply_ufunc` and rechunking — it is not
 the most accessible one. [`xarray-sql`](../README.md) lets you pose these
-questions in SQL and answers them with a real query engine (DataFusion),
-complete with partition pruning and projection pushdown. The datasets are
-registered *lazily* — nothing is read or column-selected up front; each query
-pulls only the variable and the partitions it needs, and value filters are
-passed as bound **query parameters** rather than formatted into the SQL string.
-And because a gridded result is still gridded data, every query here round-trips
-its answer straight back to an `xarray.Dataset` (via `to_dataset`) — SQL in, an
-array out, ready to plot or save.
+questions in SQL and answers them with a real query engine (DataFusion). The
+datasets are opened *lazily*, so a query against the whole archive reads only the
+variable and the slice it actually needs. And because a gridded result is still
+gridded data, every query here round-trips its answer straight back to an
+`xarray.Dataset` — SQL in, an array out, ready to plot or save.
 
 This page makes the argument case by case. Every claim below is backed by a
 runnable script in [`benchmarks/geospatial/`](../benchmarks/geospatial/) that
@@ -131,10 +128,10 @@ JOIN era5 e
 GROUP BY f.model, f.prediction_timedelta
 ```
 
-Both models are stacked along a `model` dimension into one forecast table, so
-the query scores them together by grouping on a `model` *column* — no table name
-formatted into the SQL. The entire evaluation — temporal alignment across three
-time axes, spatial matching, and the score — is one JOIN and one aggregate.
+Both models are stacked along a `model` dimension into one forecast table, so a
+single query scores them together, grouped by the `model` column. The entire
+evaluation — temporal alignment across three time axes, spatial matching, and the
+score — is one JOIN and one aggregate.
 [`05_forecast_skill.py`](../benchmarks/geospatial/05_forecast_skill.py) runs it
 for both models, matches an xarray reference, and reproduces the published result
 that GraphCast edges out Pangu at every lead — the classic "error grows with
@@ -168,8 +165,8 @@ literal: the raster is the full ERA5 archive (the `WHERE` prunes it to a day),
 the regions are a second SQL table, and the spatial relationship is an ordinary
 `BETWEEN`. See [`06_zonal_vector.py`](../benchmarks/geospatial/06_zonal_vector.py)
 — it reports e.g. Sahara 33 °C vs Greenland −8 °C for a June day. (Rectangular
-regions keep the demo dependency-free; arbitrary polygons are the natural next
-step, via a point-in-polygon UDF — see below.)
+regions keep this simple; arbitrary polygons would follow the same shape, with a
+point-in-polygon test in the join.)
 
 ## 6. The hard cases: where a UDF fits, and where it doesn't
 
@@ -192,10 +189,10 @@ this against **Earth Engine itself**: it opens a UTM grid through
 [Xee](https://github.com/google/Xee) carrying `ee.Image.pixelLonLat()`, so EE's
 own geodesy engine reports the true lon/lat of every pixel — an *independent*
 reprojection reference, not PROJ-vs-PROJ. The SQL UDF and EE agree to sub-metre
-precision. Two caveats, both documented in the script: PROJ's context is not
-thread-safe (so the UDF returns both coordinates from *one* call and runs on a
-single partition), and reprojection moves coordinates without resampling onto a
-grid — which is the next operation.
+precision. The script flags one practical gotcha (PROJ is not thread-safe, so the
+UDF runs serially), but the caveat that matters here is conceptual: reprojection
+moves the coordinates without resampling the data onto a new grid — and *that* is
+the next operation.
 
 **Regridding is not** row-independent: each output cell is a weighted blend of
 several input cells. That is a *many-to-many* relationship — and a many-to-many