Developer Guide

This guide describes the architecture, coding standards, and development workflow for the UFS DA Diagnostics Toolkit. It is intended for developers extending the toolkit with new diagnostics, plotting utilities, CLI tools, or API modules.

Architecture

The package is organized into four primary subsystems:

  • spectra — spectral diagnostics (power spectra, spectral ratios)

  • increment — increment maps, stitched global maps, zonal means

  • obs — observation‑space diagnostics (bias, RMS, NRMS, QC, ATMS)

  • logs — JEDI log parsing and chi‑squared consistency checks

Each subsystem contains:

  • a core engine (computations and data processing)

  • plotting utilities (figures used by CLI tools and user scripts)

  • CLI entry points (YAML‑driven workflows)

  • API modules (importable functions for custom workflows)

All subsystems follow the same design pattern: YAML in → core engine → plotting → structured outputs.

Coding Standards

  • Use Google‑style docstrings for all public functions and classes.

  • Type hints are required for all function arguments and return types.

  • Keep module paths short and avoid deep nesting.

  • All workflows must be YAML‑driven for reproducibility.

  • CLI tools must be registered in pyproject.toml under [project.scripts].

  • Plotting functions must be isolated in ufs_da_diagnostics.plots.

  • Use NumPy‑style naming for arrays (e.g., k, E, d_b, d_a).

  • Keep functions small and modular; avoid monolithic scripts.

Adding a New Diagnostic Subsystem

To add a new diagnostic subsystem:

  1. Create a new package under ufs_da_diagnostics/ Example: ufs_da_diagnostics/newdiag/

  2. Add core engine modules Implement data loading, computation, and aggregation.

  3. Add plotting utilities Place all figures under ufs_da_diagnostics.plots.

  4. Add a CLI entry point Register in pyproject.toml:

    [project.scripts]
ufsda-newdiag = "ufs_da_diagnostics.newdiag.cli:main"

  5. Add API documentation Create docs/api/newdiag.rst with autodoc and autosummary.

  6. Add usage documentation Create docs/usage_newdiag.rst with YAML examples and CLI usage.

  7. Add example figures Place PNGs under:

    docs/_static/images/newdiag/

  8. Update the index Add the new page to docs/index.rst.

Image and Documentation Standards

  • All images must be placed under:

    docs/_static/images/<subsystem>/

    Example:

    • _static/images/spectra/

    • _static/images/obs/

    • _static/images/increment/

  • Filenames must be lowercase, descriptive, and underscore‑separated.

  • Use .. figure:: directives with captions that explain the scientific meaning of the figure.

  • Use Mermaid diagrams where helpful for architecture or workflow visualization.

  • Keep documentation pages short, modular, and cross‑referenced using :ref:.

Testing and Validation

  • All new diagnostics must be tested with at least one real FV3‑JEDI experiment.

  • Validate spectra, RMS statistics, and log‑derived metrics against known results.

  • Ensure CLI tools run end‑to‑end using only the YAML file.

  • Confirm that all plots render correctly in Sphinx and on ReadTheDocs.

Contributing

Contributions should follow the modular design of the existing subsystems. New diagnostics should integrate cleanly with the YAML‑driven workflow, plotting utilities, and documentation structure described above.