Improve pair_plot's reference_values compatibility, flexibility, and documentation

[tvwenger]

Description

This PR addresses #2437 by refactoring the reference_values handling in pair_plot. reference_values is much more flexible, as demonstrated below, and now properly works when combined with labeller and combine_dims. It also adds new reference_values documentation and examples.

Checklist

• Follows official PR format
• Includes a sample plot to visually illustrate the changes (only for plot-related functions)
• New features are properly documented (with an example if appropriate)?
• Includes new or updated tests to cover the new feature
• Code style correct (follows pylint and black guidelines)
• Changes are listed in changelog

---

📚 Documentation preview 📚: https://arviz--2438.org.readthedocs.build/en/2438/

[codecov]

Codecov Report

Attention: Patch coverage is 90.47619% with 2 lines in your changes missing coverage. Please review.

Project coverage is 86.78%. Comparing base (6fabf27) to head (bb47e9f).

Files with missing lines	Patch %	Lines
arviz/plots/backends/bokeh/pairplot.py	77.77%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2438      +/-   ##
==========================================
+ Coverage   86.75%   86.78%   +0.02%     
==========================================
  Files         124      124              
  Lines       12941    12915      -26     
==========================================
- Hits        11227    11208      -19     
+ Misses       1714     1707       -7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tvwenger]

I have further refactored and simplified the logic, especially for some of the consistency checks. Now, this is much more flexible. Consider the following example, where we use a mix of reference_value data types (all of which can be cast to np.array), label transformations, and combine_dims. None of these work in the current implementation.

import arviz as az
import numpy as np
from arviz.labels import MapLabeller

print(az.__version__)

datadict = {
    "a": np.random.randn(1, 100),
    "b": np.random.randn(1, 100),
    "c": np.random.randn(1, 100, 2),
    "d": np.random.randn(1, 100, 2),
    "x": np.random.randn(1, 100, 2, 1),
    "y": np.random.randn(1, 100, 2, 1),
}
trace = az.convert_to_inference_data(datadict)

reference_values = {
    "a": 0.0,
    "b": 0.0,
    "c": [-0.5, 0.5],
    "d": [-0.5, 0.5],
    "x": np.array([[-0.5], [0.5]]),
    "y": np.array([[-0.5], [0.5]]),
}

var_name_map = {
    "a": r"$\alpha$ ($\mu$m)",
    "b": r"$\beta$ ($\mu$m)",
    "x": "x (cm)",
    "y": "y (cm)",
}
labeller = MapLabeller(var_name_map)

az.plot_pair(
    trace,
    var_names=["a", "b"],
    reference_values=reference_values,
    labeller=labeller,
    show=True,
)
az.plot_pair(
    trace,
    var_names=["c", "d"],
    reference_values=reference_values,
    labeller=labeller,
    show=True,
)
az.plot_pair(
    trace,
    var_names=["x", "y"],
    reference_values=reference_values,
    labeller=labeller,
    combine_dims={"x_dim_0", "y_dim_0"},
    show=True,
)

[tvwenger]

I have updated the tests and documentation, as well as provided an example in the gallery. This should be ready to review once the checks have completed! @aloctavodia @amaloney

[OriolAbril]

Thanks for the PR and clear description! I'll try and take a look soonish, sorry about the slow responses.