.. _release_v1_2_0:

----------------
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 <https://k-diagram.readthedocs.io/en/latest/user_guide/errors.html>`_ 
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.

  - :func:`~kdiagram.plot.errors.plot_error_bands`: Aggregates errors
    into angular bins to plot mean error (bias) and a standard
    deviation band (variance).
  - :func:`~kdiagram.plot.errors.plot_error_violins`: Creates polar
    violin plots to compare the shape, bias, and variance of multiple
    error distributions simultaneously.
  - :func:`~kdiagram.plot.errors.plot_error_ellipses`: Visualizes
    2D uncertainty by drawing confidence ellipses based on radial and
    angular standard deviations.

* |Feature| **Advanced Uncertainty Plots** (``kdiagram.plot.uncertainty``):

  - :func:`~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.
  - :func:`~kdiagram.plot.uncertainty.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``):

  - :func:`~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``):

  - :func:`~kdiagram.utils.plot_hist_kde`: A robust, standalone
    function for plotting histograms with optional KDE overlays,
    supporting pandas DataFrames, Series, and NumPy arrays.
  - :func:`~kdiagram.plot.uncertainty.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 :func:`~kdiagram.plot.errors.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 :func:`~kdiagram.plot.relationship.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 
  :ref:`installation guide <lab_installation>` 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.