Add concepts, recipes, and API docs structure

Author: ttuff

docs/api.md

@@ -1,13 +1,12 @@
-# API reference
+# API reference (legacy)
 
-The functions below are rendered directly from the source code using
-`mkdocstrings`, so the documentation always matches the currently released
-version of the package.
+This project originally exposed a small demo API for ruled time hull
+visualizations. Those helpers now live alongside the broader
+`climate_cube_math` package inside `code/`. For the comprehensive module-level
+reference, see the [`climate_cube_math` API page](api/climate_cube_math.md).
 
-## Demo helpers
+The older demo utilities remain available for anyone still exploring the ruled
+hull prototype:
 
-::: climate_cube_math.demo.make_demo_event
-
-## Visualization
-
-::: climate_cube_math.hulls.plot_ruled_time_hull
+- `climate_cube_math.demo.make_demo_event`
+- `climate_cube_math.hulls.plot_ruled_time_hull`

docs/api/climate_cube_math.md

@@ -0,0 +1,30 @@
+# `climate_cube_math` API Reference
+
+This page documents the main public modules and functions of the
+`climate_cube_math` package. The API is auto-generated from the docstrings using
+`mkdocstrings`.
+
+## Data loading
+
+::: climate_cube_math.data.sentinel2
+
+## Vegetation indices
+
+::: climate_cube_math.indices.vegetation
+
+## Statistics: anomalies and rolling windows
+
+::: climate_cube_math.stats.anomalies
+::: climate_cube_math.stats.rolling
+::: climate_cube_math.stats.correlation
+::: climate_cube_math.stats.tails
+
+## Visualization helpers
+
+::: climate_cube_math.viz.lexcube_viz
+::: climate_cube_math.viz.qa_plots
+
+## Utilities
+
+::: climate_cube_math.utils.chunking
+::: climate_cube_math.utils.reference

docs/concepts/climate_cubes.md

@@ -0,0 +1,52 @@
+# What is a climate cube?
+
+A **climate cube** is an `xarray.DataArray` or `xarray.Dataset` whose data are
+organized along shared space-time axes. The most common arrangement in this
+project is `(time, y, x)` for single-band cubes or `(time, y, x, band)` for
+multi-band collections. Each pixel stores the value of an environmental
+variable (e.g., reflectance, temperature, precipitation) measured at a given
+location `(y, x)` and instant `time`.
+
+## Why cubes?
+
+Satellite constellations (Sentinel-2, Landsat), gridded climate products
+(GRIDMET, PRISM), and model reanalyses are all naturally expressed as climate
+cubes because their data are already gridded over regular spatio-temporal
+coordinates. By sticking with `xarray`, we get labeled dimensions, lazy loading
+(with `dask`), and robust metadata handling.
+
+This package focuses on *streaming* cubes rather than requiring local
+downloads. Utilities such as `climate_cube_math.data.sentinel2.load_s2_cube`
+wrap remote APIs (e.g., Cubo) so that users can request an area/time window and
+immediately operate on the returned `xarray` cube inside notebooks or scripts.
+
+## Cube processing layers
+
+The rest of the documentation walks through the primary layers of the
+`climate_cube_math` workflow:
+
+1. **Data layer** – load space-time cubes (`load_s2_cube`).
+2. **Indices & anomalies layer** – derive vegetation indices and z-scores
+   (`compute_ndvi_from_s2`, `zscore_over_time`).
+3. **Synchrony layer** – measure rolling correlation and tail dependence versus
+   a reference pixel (`rolling_corr_vs_center`, `rolling_tail_dep_vs_center`).
+4. **Visualization layer** – explore cubes interactively with the Lexcube
+   widget (`show_cube_lexcube`) and QA plots (`plot_median_over_space`).
+
+## Conceptual cube example
+
+```python
+import xarray as xr
+
+# Generic climate cube shape
+# time: T time steps, y: rows, x: columns
+cube = xr.DataArray(
+    data,  # shape (T, Y, X)
+    coords={"time": time_coords, "y": y_coords, "x": x_coords},
+    dims=("time", "y", "x"),
+    name="my_variable",
+)
+```
+
+Once data are in this form, every operation in `climate_cube_math` simply
+composes transformations on the cube without ever breaking the labeled axes.

docs/concepts/cube_math.md

@@ -0,0 +1,44 @@
+# Climate cube math primitives
+
+The `climate_cube_math` package collects reusable *cube math* primitives that
+operate directly on `xarray` objects without breaking their labeled dimensions.
+These primitives fall into three categories.
+
+## Temporal operations
+
+- **Z-scores & anomalies** – `stats.anomalies.zscore_over_time` and related
+  helpers standardize or demean each pixel.
+- **Rolling reductions** – `stats.rolling` defines moving-window statistics that
+  are later specialized by the correlation/tail modules.
+- **Lag/lead transforms** – differencing, smoothing, and other future helpers can
+  be layered on time-centered cubes to highlight rate-of-change or persistence.
+
+## Spatial operations
+
+- **Coarsening & striding** – `utils.chunking.coarsen_and_stride` reduces spatial
+  resolution and sub-samples time for performance.
+- **Masks & neighborhoods** – boolean masks (e.g., from QA bands or external
+  polygons) can gate where calculations run. Neighborhood operations such as
+  smoothing or gradients preserve the `y`/`x` axes while aggregating across
+  nearby pixels.
+
+## Metadata conventions
+
+All primitives expect the standard `(time, y, x)` dimension order (with optional
+band/variable axis). Coordinates should be named `time`, `y`, `x`, and any extra
+bands should be labeled via the `band` or `variable` dimension. Attributes are
+carried through operations so that downstream plots know the data source,
+projection, or scaling applied.
+
+## Putting it together
+
+By composing these primitives we can:
+
+1. Load a cube.
+2. Apply temporal standardization (z-scores).
+3. Reduce spatial resolution or mask invalid data.
+4. Derive rolling synchrony metrics.
+5. Visualize the resulting cubes via Lexcube and QA plots.
+
+The abstraction lets you swap in other backends (e.g., GRIDMET temperature
+cubes) while keeping the same math pipeline.

docs/concepts/ndvi_zscore.md

@@ -0,0 +1,59 @@
+# NDVI z-scores
+
+## What is NDVI?
+
+The **Normalized Difference Vegetation Index (NDVI)** measures vegetation
+vigour by contrasting the high reflectance of healthy plants in the near
+infrared (NIR) with their low reflectance in the red band:
+
+\[
+NDVI = \frac{\text{NIR} - \text{Red}}{\text{NIR} + \text{Red}}
+\]
+
+Values range from -1 to 1. Dense, photosynthetically active vegetation
+produces high NDVI, while bare soil, snow, or water produce lower values.
+
+## Why standardize NDVI?
+
+Each pixel experiences its own seasonal cycle and lighting geometry. To detect
+unusual conditions (drought, disturbance, phenology shifts) we standardize each
+pixel relative to its own history. This is done with a **z-score** over time:
+
+\[
+z = \frac{x_t - \mu_{pixel}}{\sigma_{pixel}}
+\]
+
+where \(\mu_{pixel}\) and \(\sigma_{pixel}\) are the pixel's mean and
+standard deviation across the available time series. The resulting NDVI
+z-score cube highlights anomalies rather than absolute greenness.
+
+## Mapping to `climate_cube_math`
+
+The package provides two key helpers:
+
+- `climate_cube_math.indices.vegetation.compute_ndvi_from_s2` turns Sentinel-2
+  Level-2A surface reflectance cubes into NDVI cubes.
+- `climate_cube_math.stats.anomalies.zscore_over_time` standardizes each pixel
+  along the time dimension.
+
+Together they produce the NDVI z-score cubes that downstream statistics and
+visualizations consume.
+
+## End-to-end example
+
+```python
+from climate_cube_math.data.sentinel2 import load_s2_cube
+from climate_cube_math.indices.vegetation import compute_ndvi_from_s2
+from climate_cube_math.stats.anomalies import zscore_over_time
+
+s2 = load_s2_cube(
+    lat=43.89,
+    lon=-102.18,
+    start="2023-06-01",
+    end="2023-06-30",
+    edge_size=256,
+)
+
+ndvi = compute_ndvi_from_s2(s2)
+ndvi_z = zscore_over_time(ndvi)
+```

docs/concepts/rolling_stats.md

@@ -0,0 +1,45 @@
+# Rolling correlation & tail dependence
+
+## Rolling windows in time
+
+Rolling statistics look at a fixed-width window (e.g., 90 days) that slides
+through time. At each step we compute a summary from only the values inside the
+window, producing a new cube aligned to the window center. This approach keeps
+temporal context while remaining responsive to recent dynamics.
+
+## Correlation vs a reference pixel
+
+When studying spatial synchrony we often compare every pixel to a single
+reference location. In `climate_cube_math` the default reference is the center
+pixel in the requested Sentinel-2 chip. The function
+`climate_cube_math.stats.correlation.rolling_corr_vs_center` computes the
+Pearson correlation between each pixel and the reference pixel within every
+rolling window. The resulting cube reveals how tightly each pixel's NDVI
+fluctuations track the anchor over time.
+
+## Tail dependence
+
+Mean correlation can miss asymmetric extremes. Tail dependence focuses on the
+probability that two pixels jointly experience unusually low (bottom tail) or
+high (top tail) values. The helper
+`climate_cube_math.stats.tails.rolling_tail_dep_vs_center` implements a rolling
+partial Spearman correlation restricted to the lower or upper tail of the data.
+It returns three cubes: bottom-tail, top-tail, and their difference (bottom -
+top). Large positive differences indicate areas that co-experience stress with
+the center pixel more often than they share unusually high NDVI.
+
+## Conceptual snippets
+
+```python
+from climate_cube_math.stats.correlation import rolling_corr_vs_center
+from climate_cube_math.stats.tails import rolling_tail_dep_vs_center
+
+corr_cube = rolling_corr_vs_center(ndvi_z, window_days=90, min_t=5)
+
+bottom_tail, top_tail, diff_tail = rolling_tail_dep_vs_center(
+    ndvi_z, window_days=90, min_t=5, b=0.5
+)
+```
+
+By chaining these functions onto an NDVI z-score cube we transform the original
+vegetation signal into diagnostics of synchrony and shared extremes.

docs/recipes/s2_corr_center.md

@@ -0,0 +1,68 @@
+# Rolling correlation cube vs center pixel (Sentinel-2 NDVI z-scores)
+
+This guide extends the NDVI z-score workflow by computing rolling correlation
+between every pixel and the center pixel of the cube. The output highlights
+areas that move in sync with the reference location.
+
+Steps:
+
+1. Load Sentinel-2 data and compute NDVI z-scores (same as previous recipe).
+2. Downsample for faster rolling statistics (optional but recommended).
+3. Use `rolling_corr_vs_center` to compute correlation cubes.
+4. Visualize with Lexcube and inspect QA summaries.
+
+```python
+from climate_cube_math.data.sentinel2 import load_s2_cube
+from climate_cube_math.indices.vegetation import compute_ndvi_from_s2
+from climate_cube_math.stats.anomalies import zscore_over_time
+from climate_cube_math.stats.correlation import rolling_corr_vs_center
+from climate_cube_math.utils.chunking import coarsen_and_stride
+from climate_cube_math.viz.lexcube_viz import show_cube_lexcube
+from climate_cube_math.viz.qa_plots import plot_median_over_space
+
+s2 = load_s2_cube(
+    lat=43.89,
+    lon=-102.18,
+    start="2023-06-01",
+    end="2024-09-30",
+    edge_size=1028,
+    resolution=10,
+    cloud_lt=40,
+)
+
+ndvi = compute_ndvi_from_s2(s2)
+ndvi_z = zscore_over_time(ndvi)
+
+# Downsample for performance
+ndvi_z_ds = coarsen_and_stride(ndvi_z, coarsen_factor=4, time_stride=2)
+
+# Rolling correlation vs center pixel
+corr_cube = rolling_corr_vs_center(
+    ndvi_z_ds,
+    window_days=90,
+    min_t=5,
+)
+
+# Lexcube visualization of correlation cube
+corr_widget = show_cube_lexcube(
+    corr_cube.clip(-1, 1),
+    title="Rolling correlation vs center pixel (NDVI z-scores)",
+    cmap="RdBu_r",
+    vmin=-1,
+    vmax=1,
+)
+
+# In a notebook: corr_widget.plot()
+
+# QA: median correlation over space
+ax = plot_median_over_space(
+    corr_cube,
+    ylabel="Median correlation",
+    title="Median corr vs center (rolling 90 days)",
+    ylim=(-1, 1),
+)
+```
+
+Use the resulting cube to identify coherent ecological zones, potential
+teleconnections, or areas where vegetation dynamics are decoupled from the
+reference site.