Merge pull request #31 from CU-ESIIL/codex/redesign-and-expand-climate_cube_math-website

Revamp docs navigation and design

Author: ttuff

docs/assets/img/cube_axes.png

@@ -0,0 +1,42 @@
+# What is a cube?
+
+A **cube** is an `xarray.DataArray` or `xarray.Dataset` whose values are organized along shared space-time axes such as `(time, y, x)` for single-band cubes or `(time, y, x, band)` for multispectral collections. Every pixel stores the value of an environmental variable (e.g., NDVI, temperature, precipitation) measured at `(y, x)` and instant `time`.
+
+![Cube axes diagram](../assets/img/cube_axes.png){ .cube-image }
+
+## Loading a PRISM cube
+
+```python
+import cubedynamics as cd
+
+cube = cd.load_prism_cube(
+    lat=40.0,
+    lon=-105.25,
+    start="2000-01-01",
+    end="2020-12-31",
+    variable="ppt",
+)
+
+cube
+```
+
+`load_prism_cube` streams the requested area/time window from PRISM into memory as a cube so you can immediately apply verbs. Swap in `load_gridmet_cube`, `load_sentinel2_ndvi_cube`, or any custom loader that returns an `xarray` object with the standard axes.
+
+## Why cubes?
+
+Satellite constellations (Sentinel-2, Landsat), gridded climate products (gridMET, PRISM), and model reanalyses naturally produce cube-shaped data because measurements are already tied to regular spatiotemporal coordinates. By sticking with `xarray`, CubeDynamics benefits from labeled dimensions, lazy loading (`dask`), and metadata-aware computations.
+
+CubeDynamics focuses on **streaming cubes** instead of requiring large local downloads. Utilities such as `cubedynamics.data.sentinel2.load_s2_cube` wrap remote APIs (e.g., Cubo) so you can request an area/time window and immediately operate on the returned cube in notebooks or scripts.
+
+## Cube processing layers
+
+The original documentation described four conceptual layers that remain relevant today:
+
+1. **Data layer** – load space-time cubes (`load_s2_cube`, `load_prism_cube`, `load_gridmet_cube`).
+2. **Indices & anomalies layer** – derive vegetation indices and z-scores (`from cubedynamics import verbs as v`; `v.ndvi_from_s2`, `v.zscore`, `v.anomaly`).
+3. **Synchrony layer** – measure rolling correlation and tail dependence versus a reference pixel (`v.correlation_cube`, `rolling_corr_vs_center`, `rolling_tail_dep_vs_center`).
+4. **Visualization layer** – explore cubes interactively with the Lexcube widget (`v.show_cube_lexcube`) and QA plots (`plot_median_over_space`).
+
+## Earth System Data Cube context
+
+CubeDynamics builds on the Earth System Data Cube (ESDC) paradigm: treat spatiotemporal grids as analysis-ready cubes that can flow into machine learning or statistical analyses. Unlike infrastructure-focused systems (Open Data Cube, Earth System Data Lab), CubeDynamics emphasizes a **grammar of analysis**. Any cube—PRISM, gridMET, Sentinel-2 NDVI via Cubo, Lexcube outputs, or DeepESDL—becomes a first-class citizen in the same `pipe(cube) | verbs` interface.

docs/assets/img/lexcube_hero.png

@@ -0,0 +1,67 @@
+# Pipe syntax & verbs
+
+CubeDynamics exposes a lightweight `Pipe` object so `xarray` workflows read like recipes. Each verb is a factory that returns a callable, letting you configure parameters upfront and apply them later with the `|` operator.
+
+## The Pipe object
+
+```python
+from cubedynamics import pipe
+
+pipe_obj = pipe(cube)
+```
+
+`pipe(value)` wraps any `xarray.DataArray` or `xarray.Dataset` without altering it. Use the `|` operator to apply verbs. In notebooks the last `Pipe` expression in a cell auto-displays the wrapped object, so calling `.unwrap()` is optional unless you immediately need the `xarray` object.
+
+## Chaining verbs
+
+```python
+from cubedynamics import pipe, verbs as v
+
+out = (
+    pipe(cube)
+    | v.anomaly(dim="time")
+    | v.variance(dim="time")
+).unwrap()
+```
+
+Each verb receives the previous output. Pipes simply pass the cube along, so as long as the object behaves like an `xarray` structure the chain continues. The pattern mirrors tidyverse pipes, but in Python.
+
+## Core verb categories
+
+Verbs are grouped into focused namespaces:
+
+- **Transform verbs** – reshape, filter, or derive indices (`v.anomaly`, `v.month_filter`, `v.ndvi_from_s2`).
+- **Stats verbs** – compute variance, z-scores, correlations, or rolling metrics (`v.variance`, `v.zscore`, `v.correlation_cube`).
+- **IO verbs** – persist results without breaking the chain (`v.to_netcdf`).
+- **Visualization verbs** – preview cubes inline (`v.show_cube_lexcube`, QA plots) before exporting.
+- **Models (coming soon)** – wrappers around ML/statistical models that accept cubes as inputs.
+
+See the [Verbs Reference](../reference/verbs_transforms.md) section for detailed signatures and examples.
+
+## Lexcube integration
+
+Lexcube visualizations follow the same pattern:
+
+```python
+pipe(cube) | v.show_cube_lexcube(title="NDVI anomalies")
+```
+
+The verb renders the widget as a side effect and returns the original cube. Helpers such as `cd.show_cube_lexcube` are available when you are not inside a pipe chain.
+
+## Define your own verbs
+
+Verbs follow a simple factory pattern—accept configuration parameters now, return a callable that receives the cube later:
+
+```python
+def my_custom_op(param):
+    def _inner(da):
+        # operate on da (xarray DataArray/Dataset)
+        return da
+    return _inner
+
+from cubedynamics import pipe
+
+result = pipe(cube) | my_custom_op(param=42)
+```
+
+Register your verb in your own module or import it into notebooks, then use it alongside the built-in operations. Tests under `tests/` cover both direct invocation and pipe usage, so mirror that pattern when adding new verbs.

docs/concepts/cubes.md

@@ -0,0 +1,66 @@
+/* Extra styling for CubeDynamics site */
+
+:root {
+  --cube-accent: #1f3b74;
+}
+
+body {
+  background-color: #f5f5f7;
+}
+
+/* Buttons */
+.md-button {
+  transition: transform 0.1s ease, box-shadow 0.1s ease, background-color 0.1s ease;
+}
+
+.md-button--primary {
+  font-weight: 600;
+  background-color: #1f3b74;
+  color: #ffffff;
+}
+
+/* Hover effects for buttons */
+.md-button:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 4px 10px rgba(0, 0, 0, 0.12);
+}
+
+/* Cards / callout boxes */
+.cube-card {
+  border-radius: 0.75rem;
+  padding: 1.25rem 1.5rem;
+  margin: 1.5rem 0;
+  background-color: #f5f5f7;
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.04);
+  border: 1px solid rgba(31, 59, 116, 0.08);
+}
+
+.cube-card h3 {
+  margin-top: 0;
+  color: #1f3b74;
+}
+
+/* Make images look nicer */
+.cube-image {
+  border-radius: 0.5rem;
+  box-shadow: 0 3px 12px rgba(0, 0, 0, 0.16);
+  margin: 1rem 0;
+}
+
+/* Slightly larger code blocks */
+.md-typeset code {
+  font-size: 0.92em;
+  background-color: rgba(31, 59, 116, 0.05);
+  border-radius: 4px;
+  padding: 0.05rem 0.35rem;
+}
+
+/* Carry over legacy heading & image styles */
+.md-typeset h1 {
+  color: var(--cube-accent);
+}
+
+.md-content img {
+  border-radius: 6px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
+}

docs/concepts/pipe_and_verbs.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## Unreleased
+
+- Rebranded the project as CubeDynamics with a pipe-first API.
+- Added docs for `pipe`, `anomaly`, `month_filter`, `variance`, `correlation_cube`, and `to_netcdf` verbs.
+- Documented the `Pipe` helper and new operations reference structure.
+- Update (2025): reorganized the MkDocs navigation into Concepts, Getting Started, Examples, Verbs Reference, Related Work, and Development sections.
+- Added new CSS, hero buttons, and cards to align with the refreshed color palette.
+
+## Earlier work
+
+See the Git history for previous releases and prototype implementations while we stabilize the streaming adapters.

docs/css/extra.css

@@ -0,0 +1,60 @@
+# Contributing
+
+Thank you for helping build CubeDynamics! This project keeps climate cube math lightweight, streaming-first, and well documented.
+
+## Repository layout
+
+```text
+src/
+  cubedynamics/
+    __init__.py           # re-exports verbs and pipe helpers
+    piping.py             # Pipe class + helpers
+    ops/
+      __init__.py
+      transforms.py       # anomaly, month_filter, NDVI helpers
+      stats.py            # variance, correlation_cube, rolling metrics
+      io.py               # to_netcdf and future exporters
+docs/                  # MkDocs + Material site
+```
+
+Tests live under `tests/` and rely on `pytest`. Documentation is built with MkDocs (Material theme); run `mkdocs serve` while editing docs.
+
+## Local setup
+
+1. Fork or branch from `main` and create feature branches for your work.
+2. Install dependencies in editable mode (e.g., `python -m pip install -e .[dev]` once extras are defined).
+3. Run `pytest` plus any relevant notebooks/scripts before opening a pull request.
+
+## Adding a new verb
+
+1. Create the implementation in `cubedynamics/ops/`.
+2. Follow the factory pattern:
+
+   ```python
+   def verb_name(...):
+       def _inner(cube):
+           ...
+       return _inner
+   ```
+
+3. Re-export the verb in `cubedynamics/verbs/__init__.py` (and optionally `cubedynamics/__init__.py`) so users can `from cubedynamics import verbs as v` and call `v.verb_name` directly.
+4. Document the new function under `docs/reference/verbs_*.md` and add examples using the pipe syntax.
+5. Write tests that cover direct invocation and pipe usage.
+
+## Streaming philosophy
+
+- **Streaming-first** – functions should operate on iterables, chunked dask arrays, or lazy `xarray` objects whenever possible.
+- **Side-effect aware** – avoid downloading entire archives; expose hooks for caching and resuming streams.
+- **Composable** – keep verbs pure (no global state) so they chain cleanly in the pipe system.
+
+## Docs + website
+
+- Keep the navigation structure in `mkdocs.yml` aligned with the docs files.
+- Use the new section layout (Concepts, Getting Started, Examples, Verbs Reference, Related Work, Development) when adding content.
+- Remember that Lexcube widgets do not render on the static site; include screenshots or Binder links where appropriate.
+
+## Opening a pull request
+
+- Describe the change, test coverage, and any data access requirements.
+- Update the [Roadmap](roadmap.md) or [Changelog](changelog.md) when user-facing features ship.
+- Issues and discussions are welcome for roadmap ideas, new data sources, or Lexcube visualizations.

docs/dev/changelog.md

@@ -0,0 +1,22 @@
+# Roadmap
+
+This roadmap reflects near-term development priorities plus longer-term ambitions for CubeDynamics.
+
+## Near term
+
+- **Stabilize loaders** – polish `load_prism_cube`, `load_gridmet_cube`, and `load_sentinel2_ndvi_cube` with clearer AOI validation and chunk hints.
+- **Reference verbs** – fill out stats/transform IO docs and ensure every helper has an example in the new `reference/` section.
+- **Sentinel-2 notebooks** – keep the NDVI z-score tutorial in sync with the docs, including Lexcube screenshots and Binder links.
+- **Correlation cubes** – graduate `v.correlation_cube` and rolling correlation verbs from stubs to tested implementations.
+
+## Mid term
+
+- **IO expansion** – add `v.to_zarr`/`v.to_geotiff` exporters plus metadata helpers for catalog integration.
+- **Visualization palette** – expose more QA plot verbs (`quick_map`, `hist_over_time`) using the new color scheme.
+- **Model verbs** – prototype cube-aware regression/classification verbs that emit predictions in cube form.
+
+## Long term
+
+- **Catalog integration** – connect to ESDC, Open Data Cube, and DeepESDL catalogs so users can pull remote cubes via a unified interface.
+- **Storage backends** – optional local stores (Zarr + Parquet metadata) for caching repeated AOI requests.
+- **Community examples** – curated gallery of climate–vegetation analyses contributed by the community.

docs/dev/contributing.md

@@ -0,0 +1,62 @@
+# Climate–NDVI correlation cube
+
+Correlation cubes capture how vegetation anomalies co-vary with climate drivers. This example merges the earlier correlation notes with the new pipe-first grammar.
+
+## Load climate and NDVI cubes
+
+```python
+import cubedynamics as cd
+from cubedynamics import pipe, verbs as v
+
+prism_cube = cd.load_prism_cube(
+    lat=40.0,
+    lon=-105.25,
+    start="2000-01-01",
+    end="2020-12-31",
+    variable="ppt",
+)
+
+ndvi_z = cd.load_sentinel2_ndvi_cube(
+    lat=40.0,
+    lon=-105.25,
+    start="2018-01-01",
+    end="2020-12-31",
+)
+```
+
+## Prepare anomalies
+
+```python
+climate_anom = (
+    pipe(prism_cube)
+    | v.anomaly(dim="time")
+).unwrap()
+```
+
+## Compute correlation cube
+
+```python
+corr = (
+    pipe(ndvi_z)
+    | v.correlation_cube(climate_anom, dim="time")
+).unwrap()
+```
+
+The output stores correlation coefficients per pixel, aligned along the `time` coordinate (full-period or rolling depending on the configuration). Use it to spot areas where vegetation responds strongly to precipitation anomalies.
+
+## Rolling correlation vs anchor pixels
+
+`v.rolling_corr_vs_center` and `v.rolling_tail_dep_vs_center` extend the idea to within-cube synchrony (e.g., NDVI vs center pixel). They inherit the same pipe syntax:
+
+```python
+rolling = (
+    pipe(ndvi_z)
+    | v.rolling_corr_vs_center(window_days=90, min_t=5)
+)
+```
+
+## Related documentation
+
+- [Correlation & synchrony cubes](../correlation_cubes.md)
+- [Sentinel-2 NDVI z-score cube](s2_ndvi_zscore.md)
+- [Verbs – Stats](../reference/verbs_stats.md)