Skip to content

README.md

Latest commit

 

History

History
187 lines (122 loc) · 5.35 KB

README.md

File metadata and controls

187 lines (122 loc) · 5.35 KB

CubeDynamics

Install: pip install cubedynamics → import cubedynamics

Migration note: this project was renamed from climate_cube_math to cubedynamics. Legacy imports will keep working for now but emit a DeprecationWarning; please update your code to use the new package name.

CubeDynamics

Tests Docs

CubeDynamics: a grammar of streaming environmental computation.

CubeDynamics is a Python framework for computing on environmental data streams through spatiotemporal cubes, rather than treating storage, retrieval, and visualization as the main product.

It is designed for scientists and data practitioners who want to reason explicitly about space, time, scale, and events—and to do so reproducibly and efficiently, even for large datasets.

Scientists and AI agents use the same streaming interface, so workflows can be explored interactively, scripted, or orchestrated programmatically without switching mental models.

Why this project exists

Most environmental datasets already form data cubes:

  • climate grids evolving through time
  • vegetation indices measured repeatedly over landscapes
  • disturbance events unfolding in space and time

Yet most workflows break these dimensions apart:

  • spatial analysis in GIS
  • temporal analysis in tables
  • statistics elsewhere
  • visualization last

CubeDynamics keeps space and time together, making spatiotemporal structure a first-class part of the analysis.

Most neighboring tools answer:

How do I store, query, or retrieve a cube?

CubeDynamics answers:

How do I compute on a stream of environmental data?

What CubeDynamics enables

  • Spatiotemporal cube operations (means, variance, anomalies, synchrony)
  • Grammar-based pipelines using pipe | verb | verb
  • Streaming-first analysis via VirtualCubes for large datasets
  • Event- and hull-based workflows (fires, droughts, phenology)
  • Integrated visualization of space–time structure

Fire events now follow a clearer object model built around:

  • FireEventDaily for canonical FIRED-like daily event geometry
  • FireHull for the derived fire-time hull / VASE geometry

The intent is to keep FIRED ingestion, hull geometry, environmental attribution, cube conversion, and visualization separable so fire workflows remain part of the same composable cube grammar as the rest of CubeDynamics.

Minimal example

from cubedynamics import pipe, verbs as v
import cubedynamics as cd

cube = cd.ndvi(
    lat=40.0,
    lon=-105.25,
    start="2022-01-01",
    end="2023-01-01",
)

pipe(cube) | v.anomaly() | v.variance() | v.plot()

This pipeline:

  • loads a spatiotemporal cube
  • computes anomalies through time
  • measures variability at each spatial location
  • visualizes the result

Documentation

📘 Full documentation website 👉 https://cu-esiil.github.io/cubedynamics/

Key entry points:

  • Concepts – cube abstraction, pipes & verbs, streaming
  • Getting Started – first success in minutes
  • Capabilities & Verbs – complete textbook-style reference
  • Datasets – supported data sources, fields, citations
  • Recipes – end-to-end scientific workflows

Installation

Stable release from PyPI

pip install cubedynamics

Install from a tagged release

For reproducible reviews, install directly from a Git tag:

pip install "git+https://github.com/CU-ESIIL/cubedynamics.git@v0.1.0"

Replace v0.1.0 with the release tag you want to test.

Developer install

git clone https://github.com/CU-ESIIL/cubedynamics.git
cd cubedynamics
python -m pip install -e ".[dev]"
pytest -m "not integration" -q

See the documentation for optional extras, large-data workflows, and examples.

Useful extras:

  • pip install -e ".[test]" for tests and packaging checks
  • pip install -e ".[docs]" for MkDocs builds
  • pip install -e ".[viz]" for Lexcube-backed visualization helpers

Project status & scope

  • Active development
  • APIs are stabilizing; deprecations follow a warn-first policy
  • Focused on spatiotemporal environmental analysis
  • Built on top of xarray and related ecosystem tools

See the documentation for the public API and stability guarantees.

Cite CubeDynamics

Please cite the project using the guidance in CITATION.cff. A Zenodo DOI will be added to the citation metadata after the first tagged release is archived.

(See the documentation for dataset-specific citations.)

Contributing

Contributions are welcome.

  • See CONTRIBUTING.md for development guidelines
  • Open issues for bugs, questions, or feature discussions

Release (for JOSS)

  • Create a Git tag (e.g., v0.1.0) and push it to GitHub.
  • Draft a GitHub Release from the tag; Zenodo will archive the release and mint a DOI once connected.
  • Update CITATION.cff, .zenodo.json, and paper/paper.md with the minted DOI after the archive appears.
  • Ensure tests pass and documentation builds for the tagged version.
  • Submit to JOSS with the tag, Zenodo DOI, and paper/ directory included.

License

MIT License (see LICENSE).