cedar-graph

cedar-graph is a high-level plotting library for CEMC numerical weather prediction products, including CMA-GFS, CMA-MESO, CMA-TYM, and CMA-GEPS. Built on reki, cedarkit-comp, and cedarkit-plots, it packages data lookup, field loading, processing, and plotting into reusable product definitions.

This project is at the Sandbox maturity level. Its public API, recipes, and supported products may still evolve.

Features

• Define most products declaratively with YAML recipes, covering data fields, transformations, layers, styles, titles, and colorbars.
• Support complex diagnostic products through Python plot modules with the same public interface as recipe-backed products.
• Run products from a compact quick_plot interface against a CMADaaS-mounted data directory, or invoke the loading and plotting stages directly in applications and notebooks.
• Keep operational styles in a reusable CEMC style library.
• Switch between GRIB2 data in a CMADaaS-mounted directory and deterministic synthetic data for tests and documentation.

Installation

Install from PyPI:

pip install cedar-graph

For development in this workspace, install dependencies and run the mock test suite:

cd repo/cedar-graph
uv sync --extra test
pytest

cedar-graph uses reki and ecCodes to read GRIB2 data from a CMADaaS-mounted directory. The mock examples and tests do not require either. See the installation guide for details.

Quick plot from a CMADaaS-mounted directory

quick_plot is the shortest path from a product name to a figure. It uses LocalDataSource and reki's cmadaas local-path configuration. Set storage_base to the mount point; the default below is /CMADAAS.

from cedar_graph.quickplot import quick_plot

quick_plot(
    plot_type="cn.t2m",
    system_name="CMA-GFS",
    start_time="2024073000",
    forecast_time="48h",
    data_class="cmadaas",
    storage_base="/CMADAAS",
)

For a custom region, pass product-specific settings such as area_name and area_range:

from cedar_graph.quickplot import quick_plot
from cedarkit.plots.types import AreaRange

quick_plot(
    plot_type="cn.wind_10m",
    system_name="CMA-MESO",
    start_time="2024073000",
    forecast_time="48h",
    data_class="cmadaas",
    storage_base="/CMADAAS",
    area_name="NorthEast",
    area_range=AreaRange.from_tuple((108, 137, 37, 55)),
)

The mounted-directory workflow is local file access; it does not use the CMADaaS remote service or require CMADaaS credentials. The directory layout must match the reki templates for the selected system.

For portable scripts, notebooks, and debugging, use a product definition with an explicit data source instead. The manual plotting tutorial shows the same workflow using MockDataSource, which works without access to operational data. To read mounted data in that workflow, create LocalDataSource(system_name="CMA-GFS", data_class="cmadaas", storage_base="/CMADAAS").

Product model

Each product is provided by either a YAML recipe under cedar_graph/recipes/ or a Python module under cedar_graph/plots/. Both expose the same three-part interface:

PlotMetadata                 # Product metadata and product-specific options
load_data(data_loader, ...)  # Source data to fields ready for plotting
plot(plot_data, metadata)    # Fields to a cedarkit.plots Panel

The loader searches YAML recipes first, then Python modules. This makes product type names such as cn.t2m, cn.h_500_psl, and cn.shr.default consistent across quick plots, applications, tests, and documentation.

Available products include surface fields, upper-air analyses, precipitation, convection diagnostics, wind shear, and moisture diagnostics. Browse the gallery for the complete, rendered catalogue.

Documentation

• Installation: runtime dependencies and source-based development.
• Core concepts: data sources, loaders, product definitions, and quick_plot.
• Quick plotting: CMADaaS-mounted-directory usage and product-specific arguments.
• Manual plotting: explicitly load data and render a product, including a portable mock-data example.
• Mock data: deterministic synthetic data used by tests and documentation.
• Recipes and plugins: write and extend YAML product definitions.
• Style library: manage CEMC plotting styles.
• Gallery: rendered examples of all supported products.
• API reference: generated Python API documentation.
• Changelog: release history.

Documentation structure

Keep this README as the project entry point. Detailed user and maintainer documentation belongs under docs/:

README.md                         Project overview, installation, mounted-directory quick plot, documentation links
docs/
├── getting_started/              Installation and shared concepts
├── tutorials/                    Quick plotting, manual workflow, mock data, recipes, and styles
├── gallery/                      Runnable product examples, organized by final figure
├── api/                          Code-synchronized module and object reference
└── changelog.md                  Release history

When adding a product, include a recipe or plot module, tests using mock data, and a gallery entry. Add API documentation for stable public interfaces rather than duplicating tutorial content.

License

Copyright © 2024-2026, developers at cemc-oper.

cedar-graph is licensed under the Apache License 2.0.