Merge pull request #10 from CU-ESIIL/codex/rewrite-all-docs-for-cubedynamics

docs: rewrite site for CubeDynamics

Author: ttuff

CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+title: "CubeDynamics: Streaming Climate Cube Math for Environmental Data Science"
+message: "If you use CubeDynamics, please cite it as described here."
+type: software
+authors:
+  - family-names: Tuff
+    given-names: Ty
+version: 0.1.0
+repository-code: "https://github.com/CU-ESIIL/climate_cube_math"
+keywords:
+  - climate
+  - streaming
+  - data cubes
+  - xarray
+  - dask
+abstract: |
+  CubeDynamics (`cubedynamics`) is a streaming-first Python library for
+  constructing multi-source climate data cubes, computing variance and
+  correlation diagnostics, and exporting derived "lexcubes" for dashboards and
+  climate resilience workflows.

README.md

@@ -1,110 +1,78 @@
-# Climate Cube Math
+# CubeDynamics (`cubedynamics`)
 
-`cubedynamics` provides streaming access to climate data cubes plus reusable
-statistics, vegetation-index helpers, and QA visualizations for understanding
-Sentinel-2, GRIDMET, PRISM, and related datasets.  This repository also
-includes a MkDocs site and reproducible vignette that document the package.
+CubeDynamics is a streaming-first climate cube math library for building
+multi-source climate data cubes (PRISM, gridMET, NDVI/Sentinel, etc.) and
+computing correlations, variance, and trends without downloading entire
+collections.
+
+## Features
+
+- **Streaming and chunked access** to climate datasets so analyses can begin
+  before downloads finish.
+- **Climate lexcubes** – multi-dimensional cubes of climate statistics for
+  comparing vegetation, weather, and derived metrics over shared axes.
+- **Correlation, synchrony, and variance cubes** that summarize temporal
+  patterns such as drought stress, phenology shifts, and teleconnections.
+- **Notebook-friendly helpers** for Jupyter, VS Code, and workflow runners.
+- **Cloud and big-data ready** primitives that lean on `xarray`, `dask`, and
+  lazy execution.
 
 ## Installation
 
-You can install the latest library directly from the repository:
+Once the package is published on PyPI you will be able to install it with:
+
+```bash
+pip install cubedynamics
+```
+
+Until then install directly from GitHub:
 
 ```bash
-pip install git+https://github.com/CU-ESIIL/climate_cube_math.git
+pip install "git+https://github.com/CU-ESIIL/climate_cube_math.git@main"
 ```
 
-During development use an editable install from the repo root:
+Developers can work against the repo in editable mode:
 
 ```bash
 python -m pip install -e .
 ```
 
-## Quick start
+## Quickstart
 
 ```python
 import cubedynamics as cd
 
-s2 = cd.load_s2_cube(
-    lat=43.89,
-    lon=-102.18,
-    start="2023-06-01",
-    end="2023-09-30",
-    edge_size=512,
+# Example: stream a gridMET cube for a region and compute a variance cube
+cube = cd.stream_gridmet_to_cube(
+    aoi_geojson,
+    variable="pr",
+    dates=("2000-01", "2020-12"),
 )
-
-ndvi = cd.compute_ndvi_from_s2(s2)
-ndvi_z = cd.zscore_over_time(ndvi)
-```
-
-The same package still ships the ruled time hull helpers used in the training
-materials:
-
-* `cubedynamics.demo.make_demo_event()` builds a small GeoDataFrame that mimics
-  how a fire perimeter evolves through time.
-* `cubedynamics.hulls.plot_ruled_time_hull()` converts that data into a 3D ruled
-  surface so the temporal pattern can be inspected visually.
-
-## Documentation and vignette
-
-The public website is generated from the `docs/` folder using MkDocs Material
-and includes:
-
-1. A concise landing page that explains the project goals.
-2. A rendered copy of `docs/vignette.ipynb` so visitors can step through the
-   example without leaving the site.
-3. An API reference driven by `mkdocstrings` that documents the core
-   `cubedynamics` modules.
-
-To preview the site locally run:
-
-```bash
-mkdocs serve
+var_cube = cd.variance_cube(cube)
+var_cube.to_netcdf("gridmet_variance.nc")
 ```
 
-## Repository layout
-
-```
-code/cubedynamics/   # installable Python package
-  data/              # Sentinel-2, GRIDMET, PRISM loaders
-  indices/           # vegetation index helpers
-  stats/             # anomaly, rolling, correlation utilities
-  viz/               # QA and lexcube visualization helpers
-  utils/             # chunking, reference pixel helpers
-  demo.py            # demo GeoDataFrame generator
-  hulls.py           # ruled time hull plotting helper
-  __init__.py
-
-docs/
-  index.md           # landing page
-  api.md             # mkdocstrings API reference
-  vignette.ipynb     # notebook rendered on the site
-  stylesheets/
-    extra.css        # small cosmetic tweaks for MkDocs Material
-
-.github/workflows/pages.yml  # deploys the docs site to GitHub Pages
-mkdocs.yml                   # MkDocs configuration
-pyproject.toml               # package metadata
-```
+Additional helpers can build NDVI z-score cubes, compute rolling correlation vs
+an anchor pixel, or export “lexcubes” for downstream dashboards. Follow the docs
+for more end-to-end examples while the streaming implementations are finalized.
 
-With this layout you only need to touch two places when extending the project:
-add or update Python modules inside `code/cubedynamics/` and describe those
-changes through Markdown or notebooks in `docs/`.
+## Documentation
 
-## Installation
+Full documentation: https://cu-esiil.github.io/climate_cube_math/
 
-For the streaming-first package preview install directly from GitHub:
+The GitHub Pages site hosts the narrative docs, quickstart, concepts, and API
+notes for CubeDynamics. Use `mkdocs serve` to preview changes locally.
 
-```bash
-pip install "git+https://github.com/CU-ESIIL/climate_cube_math.git@main"
-```
+## Contributing
 
-Once published to PyPI the goal is to allow a simple install:
+Contributions are welcome! Open an issue or pull request if you would like to
+add new data sources, improve the streaming primitives, or expand the
+statistical recipes. Please keep tests streaming-first (favor chunked I/O and
+mocked responses when possible) and include documentation updates alongside code
+changes.
 
-```bash
-pip install cubedynamics
-```
+## Citation
 
-`cubedynamics` follows a streaming-first philosophy that prefers chunked IO over
-full downloads.  The accompanying pytest suite encodes this expectation by
-running streaming markers by default and skipping download-marked tests unless
-explicitly requested.
+If you use CubeDynamics in academic work, cite the project using the metadata in
+[`CITATION.cff`](CITATION.cff). A formal publication is planned; until then
+please cite the software release and repository.

docs/climate_cubes.md

@@ -0,0 +1,44 @@
+# Climate cubes
+
+Climate cubes are the core abstraction in CubeDynamics. They are `xarray`
+objects with shared `(time, y, x)` axes (and optional `band` or `variable`
+dimensions) produced by the streaming loaders.
+
+## Creating cubes
+
+```python
+from cubedynamics import stream_gridmet_to_cube
+
+cube = stream_gridmet_to_cube(
+    aoi_geojson,
+    variable="tmmx",
+    dates=("2010-01-01", "2020-12-31"),
+)
+print(cube.dims)
+```
+
+The loader harmonizes CRS, attaches metadata, and returns a lazily-evaluated
+`xarray.Dataset`. Other loaders follow the same interface (`stream_prism_to_cube`,
+`stream_sentinel2_to_cube`).
+
+## Derived diagnostics
+
+Once a cube exists, run statistics directly on the labeled dimensions:
+
+```python
+from cubedynamics.stats.anomalies import zscore_over_time
+from cubedynamics.lexcubes.variance import variance_cube
+
+ndvi_z = zscore_over_time(ndvi_cube, dim="time")
+var_cube = variance_cube(cube, dim="time")
+```
+
+Every helper keeps the input axes intact so that downstream visualizations and
+exports can consume the resulting lexcube without regridding.
+
+## Exporting cubes
+
+`cubedynamics` exposes helpers like `cube.to_netcdf(...)`, `cube.to_zarr(...)`,
+or `lexcube_to_dataset(...)` to persist results and integrate with dashboards.
+Large analyses rely on chunked writes through `dask` so the same scripts run in
+cloud environments.

docs/concepts.md

@@ -0,0 +1,35 @@
+# Concepts Overview
+
+CubeDynamics is organized into three conceptual layers that compose to produce
+climate lexcubes:
+
+1. **Sources** – streaming adapters for Sentinel-2, PRISM, gridMET, and other
+   gridded datasets. Each returns `xarray.Dataset` objects with shared
+   `(time, y, x)` axes.
+2. **Cube math primitives** – functions inside `cubedynamics.stats`,
+   `cubedynamics.indices`, and `cubedynamics.lexcubes` that compute anomalies,
+   correlations, and derived indicators.
+3. **Pipelines & exports** – recipes that connect cubes to dashboards or models
+   (NetCDF/Zarr writers, QA plots, and asynchronous workflows).
+
+The sections below summarize how these layers interact.
+
+## Source adapters
+
+Every loader enforces consistent naming (time, y, x, band) and metadata (CRS,
+units, history). Streaming-first behavior is preferred: data arrive chunked via
+HTTP range requests, STAC assets, or cloud object storage signed URLs. Offline
+fallbacks download only the required slices.
+
+## Lexcube builders
+
+Lexcubes are multi-dimensional cubes that store derived metrics such as
+variance, synchrony, or NDVI anomalies along the same axes as the source data.
+They can be nested (e.g., a `dataset` containing multiple diagnostics) and are
+ready for export.
+
+## Analysis & visualization
+
+Downstream helpers provide rolling correlation, tail dependence, QA plots, and
+hooks for interactive dashboards. See [Climate cubes](climate_cubes.md) and
+[Correlation cubes](correlation_cubes.md) for example notebooks and API usage.

docs/concepts/backends.md

@@ -1,28 +1,28 @@
 # Climate data backends
 
 `cubedynamics` treats "climate cube" sources as interchangeable once they
-provide the standard `(time, y, x)` layout.  The data loaders expose
+provide the standard `(time, y, x)` layout. The data loaders expose
 consistent knobs and return dask-backed `xarray.Dataset` objects so the rest
 of the math stack can focus on statistics instead of I/O details.
 
 ## Sentinel-2
 
-* Loader: `climate_cube_math.data.sentinel2.load_s2_cube`
+* Loader: `cubedynamics.stream_sentinel2_to_cube`
 * Purpose: multispectral reflectance for vegetation index and QA work.
 * Typical recipe: compute NDVI with
-  `climate_cube_math.indices.vegetation.compute_ndvi_from_s2` and then derive
-  z-scores or temporal anomalies with `climate_cube_math.stats.anomalies`.
+  `cubedynamics.indices.vegetation.compute_ndvi_from_s2` and then derive
+  z-scores or temporal anomalies with `cubedynamics.stats.anomalies`.
 
 ## GRIDMET
 
-* Loader: `climate_cube_math.data.gridmet.load_gridmet_cube`
+* Loader: `cubedynamics.stream_gridmet_to_cube`
 * Purpose: daily meteorological drivers (temperature, precipitation, etc.).
 * Streaming-first design: attempts to return a lazily-evaluated cube, falling
   back to an in-memory download only when streaming is not available.
 
 ```python
-from climate_cube_math.data.gridmet import load_gridmet_cube
-from climate_cube_math.stats.anomalies import zscore_over_time
+from cubedynamics import stream_gridmet_to_cube
+from cubedynamics.stats.anomalies import zscore_over_time
 
 aoi = {
     "min_lon": -105.4,
@@ -31,7 +31,7 @@ aoi = {
     "max_lat": 40.1,
 }
 
-gridmet = load_gridmet_cube(
+gridmet = stream_gridmet_to_cube(
     variables=["tmax"],
     start="2000-01-01",
     end="2000-12-31",
@@ -44,13 +44,13 @@ tmax_z = zscore_over_time(gridmet["tmax"])
 
 ## PRISM
 
-* Loader: `climate_cube_math.data.prism.load_prism_cube`
+* Loader: `cubedynamics.stream_prism_to_cube`
 * Purpose: high-resolution precipitation and temperature summaries.
 * Uses the same streaming-first contract as GRIDMET.
 
 ```python
-from climate_cube_math.data.prism import load_prism_cube
-from climate_cube_math.stats.anomalies import zscore_over_time
+from cubedynamics import stream_prism_to_cube
+from cubedynamics.stats.anomalies import zscore_over_time
 
 aoi = {
     "min_lon": -105.4,
@@ -59,7 +59,7 @@ aoi = {
     "max_lat": 40.1,
 }
 
-prism = load_prism_cube(
+prism = stream_prism_to_cube(
     variables=["ppt"],
     start="2000-01-01",
     end="2000-12-31",

docs/contributing.md

@@ -0,0 +1,16 @@
+# Contributing
+
+Thank you for helping build CubeDynamics! This project aims to keep climate cube
+math lightweight, streaming-first, and well documented. To contribute:
+
+1. Fork or branch from `main` and create feature branches for your work.
+2. Install dependencies in editable mode (`python -m pip install -e .[dev]` once
+   extras are defined) and run the test suite via `pytest`.
+3. Add or update documentation in `docs/` for every new feature or API change.
+4. Prefer streaming and chunked operations. If you add a function that downloads
+   data, ensure it can operate lazily with `dask` when possible.
+5. Open a pull request describing the change, test coverage, and any data access
+   requirements.
+
+Issues and discussions are also welcome for roadmap ideas, new data sources, or
+lexcube visualizations.