Version 1.2.0

(Released: 2025-08-20)

This is a major feature release that expands the k-diagram library’s capabilities for error analysis and distribution visualization. It introduces a new error analysis module with advanced polar plots for diagnosing systemic vs. random errors, comparing multiple models, and visualizing 2D uncertainty. Additionally, histogram and density plotting utilities have been centralized and enhanced.

New Features

• Feature Error Analysis Module (kdiagram.plot.errors): A dedicated suite of plots for deep error diagnostics.

  • plot_error_bands(): Aggregates errors into angular bins to plot mean error (bias) and a standard deviation band (variance).

  • plot_error_violins(): Creates polar violin plots to compare the shape, bias, and variance of multiple error distributions simultaneously.

  • plot_error_ellipses(): Visualizes 2D uncertainty by drawing confidence ellipses based on radial and angular standard deviations.

• Feature Advanced Uncertainty Plots (kdiagram.plot.uncertainty):

  • plot_polar_heatmap(): Creates a 2D density plot on a polar grid to identify “hot spots” where a radial metric and an angular feature concentrate.

  • plot_polar_quiver(): Draws vector arrows on a polar grid to show magnitude and direction, ideal for visualizing forecast updates or error vectors.

• Feature Model Comparison Plot (kdiagram.plot.comparison):

  • plot_horizon_metrics(): Creates a polar bar chart to compare key metrics (like interval width and median value) across different forecast horizons.

• Feature New Histogram & Density Utilities (kdiagram.utils.hist):

  • plot_hist_kde(): A robust, standalone function for plotting histograms with optional KDE overlays, supporting pandas DataFrames, Series, and NumPy arrays.

  • plot_radial_density_ring(): A novel plot for visualizing 1D distributions in a polar format.

Improvements

• Enhancement All new polar plots (heatmap, quiver, ellipses, error_bands) now include mask_angle and mask_radius parameters, giving users full control to hide meaningless axis labels for a cleaner presentation.

• Enhancement The API for new plots is designed for consistency with the existing k-diagram library, using standard parameters like df, title, cmap, show_grid, grid_props, and savefig.

• Enhancement Integrated scientific citations throughout the documentation using sphinxcontrib-bibtex to provide clear context for established and novel visualization methods.

• Enhancement The test suite is now fully compatible with Python versions 3.9 through 3.13, including environments using NumPy 2.0. Version-dependent warnings are now handled conditionally within the tests.

Bug Fixes

• Fix Resolved a TypeError in plot_polar_heatmap caused by an incorrect transpose of the counts array, ensuring compatibility with Matplotlib’s pcolormesh dimension requirements.

• Fix Resolved a TypeError in plot_polar_heatmap caused by an incorrect dimension mismatch, ensuring compatibility with Matplotlib’s pcolormesh.

• Fix Corrected various Sphinx build warnings, including ambiguous references in button-ref directives and formatting errors in numpydoc See Also sections.

• Fix Resolved all bibtex.key_not_found and bibtex.duplicate_citation warnings by correcting syntax errors in the references.bib file and adding local filters to the bibliography directive.

• Fix Corrected a FutureWarning in the test suite related to positional indexing of pandas Series by updating to the recommended .iloc accessor.

• Fix Resolved IndexError in plot_error_ellipses() that occurred when processing data with NaN values by switching to enumerate for safe iteration.

Documentation

• Docs New User Guides:

  • Added a comprehensive errors.rst user guide with detailed explanations and mathematical formulations for plot_error_bands, plot_error_violins, and plot_error_ellipses.

  • Added a new hist.rst user guide detailing the usage and concepts behind plot_hist_kde.

• Docs New Gallery Pages:

  • Created a new errors.rst gallery page with runnable examples and interpretation guides for all three new error plots.

  • Created a new hist.rst gallery page for plot_hist_kde.

  • Added new sections to the uncertainty.rst gallery for plot_polar_heatmap and plot_polar_quiver.

• Docs Scientific Context: Updated all user guides and relevant docstrings with citations to foundational scientific literature and our own research paper to clarify the origin of each method.

• Docs New API Documentation: Added comprehensive, well-structured docstrings for all new functions, including mathematical notes, parameter descriptions, and runnable examples.

• Docs Updated the documentation to remove duplicated citations and correct issues related to :footcite:.

• Docs Reworked and enhanced the documentation for various plot functions like plot_polar_heatmap, plot_polar_quiver, and plot_anomaly_magnitude.

• Docs Replaced the previous citation format with more consistent usage of :footcite: for scientific references in the documentation.

• Docs Fixed the indentation and formatting errors in the docstrings, ensuring compliance with the linting rules (max 62 characters per line).

• Docs Updated all citations in the documentation to follow the correct reStructuredText formatting with footcite for scientific accuracy.

• Docs Created a new relationship.rst gallery page with a runnable example and interpretation guide for the plot_relationship() function.

• Docs Established a single, central references.rst page with an alphabetically sorted bibliography to resolve all citation issues and improve organization.

• Docs Implemented a custom CSS theme to enhance the visual presentation and readability of the bibliography page.

• Docs Added a detailed “Building Documentation” section to the installation guide guide to assist contributors and advanced users.

Testing & QA

• Tests New test suite tests/test_plot_errors.py covering:

  • plot_error_bands: Correct aggregation of mean and std dev in bins.

  • plot_error_violins: Correct rendering for single vs. multiple models.

  • plot_error_ellipses: Correct ellipse shape and orientation.

  • Validation of masking parameters (mask_angle, mask_radius).

• Tests New test suite tests/test_plot_uncertainty_advanced.py covering:

  • plot_polar_heatmap: Correct binning and color mapping.

  • plot_polar_quiver: Correct vector placement and orientation.

  • Handling of theta_period for cyclical data.

• Tests New test suite tests/test_hist.py covering:

  • plot_hist_kde: Correct rendering from DataFrame, Series, and NumPy array.

  • Proper handling of show_kde=False.

• Tests Removed all global warning filters from pyproject.toml. All test warnings are now explicitly and correctly handled within the specific tests that produce them using pytest.warns.

• Tests Eliminated all PytestUnknownMarkWarnings by registering custom markers (e.g., network) in the pyproject.toml configuration.

• Tests Removed all @pytest.mark.skip decorators. The entire test suite now runs without skips, ensuring all functionality is actively tested.

• Tests Corrected CLI tests to properly distinguish between argparse validation errors (e.g., wrong number of arguments) and the package’s custom validation logic.