Release Notes

This document tracks the changes, new features, and bug fixes for each release of the k-diagram package.

Version 1.0.3

(Released: 2025-04-15)

This release focuses on improving documentation robustness, fixing bugs identified during documentation generation and testing, refining the dataset API, and enhancing visual styling.

✨ Enhancements

• Added new synthetic dataset generators for specific use cases:

  • make_taylor_data()

  • make_multi_model_quantile_data()

  • make_cyclical_data()

  • make_fingerprint_data()

• Added load_zhongshan_subsidence()

  function to load packaged sample data, including logic for caching and optional downloading.

• Refined dataset API: Introduced as_frame parameter to

  dataset loading/generation functions (like load_uncertainty_data()) to return either a structured Bunch object (with metadata and DESCR) or a plain pandas.DataFrame.

• Refactored model comparison plotting into

  kdiagram.plot.comparison with the function plot_model_comparison().

• Added utility module kdiagram.utils.metric_utils

  including a get_scorer() function.

• Added utility module kdiagram.utils.io and dataset

  property helpers in kdiagram.datasets._property (adapted from gofast).

• Improved CLI implementation (kdiagram.cli) with argument

  parsing for all core plotting functions and better help messages.

• Enhanced documentation theme (custom.css) with a refined

  color palette derived from the package logo, improved table styling, clearer admonitions, and smoother hover effects.

• Added CODE_OF_CONDUCT.md to the project.

🐛 Bug Fixes

• Fixed numerous ReStructuredText formatting errors in function

  docstrings across multiple modules (e.g., evaluation.py, uncertainty.py, feature_based.py), resolving critical errors and warnings during strict Sphinx builds (-W). This includes corrections to section headers, underlines, indentation, blank lines, list formatting, and footnote references. (#nnn)

• Fixed ValueError in

  plot_feature_fingerprint() during normalization (normalize=True) caused by incorrect NumPy broadcasting. (#nnn)

• Fixed logic in dataset loading functions (e.g.,

  load_uncertainty_data, load_zhongshan_subsidence) to correctly populate q10_cols, q50_cols, q90_cols attributes in the returned Bunch object by using consistent dictionary keys. (#nnn)

• Fixed Matplotlib warning in

  plot_relationship() by using color= instead of c= for scatter plots with single color specifications. (#nnn)

• Fixed potential division-by-zero errors in normalization steps

  within dataset generators and plotting functions when input data has zero range.

• Corrected logic in internal dataset download helper

  (download_file_if_missing) to prioritize package resources, then cache, then download (to cache), resolving issues with file location and potentially incorrect download paths. (#nnn)

• (Potentially Fixed) Addressed underlying configuration issues

  in setup.py (e.g., removed internal dependency installs, hardcoded version temporarily) that likely caused twine check errors due to missing Name/Version metadata in wheel files. (#nnn)

📝 Documentation

• Fixed errors in index.rst related to incorrect usage of

  sphinx-design directives (container :margin:, panels, button-ref :text:). Replaced include directive with direct RST content where myst-parser failed. (#nnn)

• Fixed numerous minor RST warnings (e.g., title underlines,

  toctree entries, broken links) across documentation files.

• Restructured Gallery into sub-directories (gallery/index.rst

  linking to plots/, utils/, etc. - Self-correction based on user actions: now links to uncertainty.rst, evaluation.rst, etc.)

• Added detailed “Analysis and Interpretation” sections to all

  examples in the Plot Gallery (gallery/*.rst) using topic directives.

• Added User Guide pages for Datasets, Model Comparison,

  and Motivation. Updated User Guide index. (#nnn)

• Added CODE_OF_CONDUCT.md and linked from CONTRIBUTING.rst.

• Added CITING.rst with instructions for citing software and

  related papers.

• Added GLOSSARY.rst.

• Added new badges (Build Status, Python Versions, etc.) to

  README.md. Corrected Markdown comment syntax. Added HTML image tags to control image size in README.

• Updated docs/requirements.txt and .readthedocs.yml for

  correct documentation builds, including setting fail_on_warning: false temporarily.

• Cleaned up docstrings for utility and compatibility modules

  with proper attribution.

Version 1.0.0

(Released: 2025-04-10)

Initial Release

This is the first public release of the k-diagram package.

Key Features Included:

• Uncertainty Visualization Suite (`kdiagram.plot.uncertainty`):

  • plot_actual_vs_predicted():

    Compare actual vs. point predictions.

  • plot_anomaly_magnitude():

    Visualize magnitude and type of prediction interval failures.

  • plot_coverage(): Calculate

    and plot overall coverage scores (bar, line, pie, radar).

  • plot_coverage_diagnostic():

    Diagnose point-wise interval coverage on a polar plot.

  • plot_interval_consistency():

    Assess stability of interval width over time (Std Dev / CV).

  • plot_interval_width():

    Visualize prediction interval width magnitude across samples.

  • plot_model_drift(): Track

    average interval width drift across forecast horizons (polar bars).

  • plot_temporal_uncertainty():

    General polar scatter for comparing multiple series (e.g., quantiles).

  • plot_uncertainty_drift():

    Visualize drift of uncertainty patterns using concentric rings.

  • plot_velocity(): Visualize

    rate of change (velocity) of median predictions.

• Model Evaluation (`kdiagram.plot.evaluation`):

  • Taylor Diagram functions (taylor_diagram(),

    plot_taylor_diagram_in(), plot_taylor_diagram()) for summarizing model skill (correlation, standard deviation, RMSD).

• Feature Importance (`kdiagram.plot.feature_based`):

  • plot_feature_fingerprint():

    Radar charts for comparing feature importance profiles.

• Relationship Visualization (`kdiagram.plot.relationship`):

  • plot_relationship(): Polar

    scatter mapping true values to angle and predictions to radius.

• Utility Functions (`kdiagram.utils`):

  • Helpers for detecting, building names for, and reshaping quantile

    data in DataFrames (detect_quantiles_in(), build_q_column_names(), reshape_quantile_data(), melt_q_data(), pivot_q_data()).

• Command-Line Interface (CLI):

  • k-diagram command for generating core plots directly from CSV

    files via the terminal.

• Documentation:

  • Initial version including Installation Guide, Quick Start, User

    Guide (concepts & interpretation), Plot Gallery, Utility Examples, API Reference, Contribution Guidelines, and License.