Adds Pair plot #287

The-Broken-Keyboard · 2025-06-13T10:45:06Z

Adds Pair Plot

Key Change required in PlotMatrix:
When we send mask through map_triangle ( for divergence ), then it doesn't perform subsetting on mask data. Which causes dimension conflict. It was directly adding **kwargs to fun_kwargs. Now it performs subsetting before adding few keys ( dataArrays or datasets ) of kwargs into fun_kwargs.

for the following code:

from arviz_base import load_arviz_data

import arviz_plots as azp

azp.style.use("arviz-variat")

data = load_arviz_data("centered_eight")
visuals = {"divergence": True}
pc = azp.plot_pair(
    data,
    backend="bokeh" , 
    var_names=["mu","tau", "theta"],
    coords={"school": ["Choate", "Deerfield"]},
    visuals=visuals,
)
pc.show()

we get the following plot:

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

codecov-commenter · 2025-06-13T10:54:27Z

Codecov Report

Attention: Patch coverage is 90.94828% with 21 lines in your changes missing coverage. Please review.

Project coverage is 88.02%. Comparing base (734c61b) to head (127c32b).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/arviz_plots/plots/pair_plot.py	88.73%	16 Missing ⚠️
src/arviz_plots/visuals/__init__.py	90.00%	2 Missing ⚠️
src/arviz_plots/backend/bokeh/__init__.py	90.90%	1 Missing ⚠️
src/arviz_plots/backend/none/__init__.py	83.33%	1 Missing ⚠️
src/arviz_plots/plot_matrix.py	97.14%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #287      +/-   ##
==========================================
+ Coverage   87.82%   88.02%   +0.19%     
==========================================
  Files          44       45       +1     
  Lines        5102     5303     +201     
==========================================
+ Hits         4481     4668     +187     
- Misses        621      635      +14

☔ 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.

The-Broken-Keyboard · 2025-06-13T10:57:27Z

@aloctavodia @OriolAbril please review this. I will add documentation and tests once we are done with final version of function

aloctavodia

LGTM

src/arviz_plots/plot_matrix.py

OriolAbril · 2025-06-18T08:36:23Z

src/arviz_plots/plots/pair_plot.py

+    sample_dims=None,
+    plot_matrix=None,


Not sure if we want that as arguments or if we want multiple plot_pair variants (or maybe a bit of both). Here are some things that could be arguments specific to the plot:

which triangle to populate plots into. Legacy arviz defaults to lower triangle only. We can change the default but we should definitely allow control over that.

Adding marginals to the diagonal. Similar to legacy version (I think it was also the default). This one would also need combining with x/y labels on the bottom/leftmost plots

To keep consistency with the other functions, marginal, marginal_kind and triangle should go between sample_dims and plot_matrix (as it is the equivalent to plot_collection: https://arviz-plots.readthedocs.io/en/latest/contributing/new_plot.html

src/arviz_plots/plots/pair_plot.py

OriolAbril · 2025-06-18T08:40:34Z

src/arviz_plots/plots/pair_plot.py

+        pairs = tuple(
+            xarray_sel_iter(
+                distribution, skip_dims={dim for dim in distribution.dims if dim in sample_dims}
+            )
+        )
+        n_pairs = len(pairs)
+        pc_kwargs = set_grid_layout(
+            pc_kwargs, plot_bknd, distribution, num_rows=n_pairs, num_cols=n_pairs
+        )


This makes me more convinced we should do #284

src/arviz_plots/plots/pair_plot.py

src/arviz_plots/visuals/__init__.py

… versions

The-Broken-Keyboard · 2025-06-20T06:09:05Z

@OriolAbril @aloctavodia

I have incorporated all the changes suggested above

MAJOR CHANGES

Added a map_row_col method which takes a variable, selection dict and orientation (row or col) and then maps the given function to whole row or col of matrix. Since we have this method in PlotMatrix, so we can also include similar kind of method in PlotCollection and the work around implemented in fixes shared x property for appropriate plots ( like rank plot, trace plot etc ) #208 will not be needed now, because we can use this function in plotcollection to handle conflicting xlabels issue too. So, i removed the work around of fixes shared x property for appropriate plots ( like rank plot, trace plot etc ) #208 for now ( to incorporate this new function ).
Added parameters triangle and remove_axis ( in visuals ) .
Added marginals ( supports kind="kde","hist" and "ecdf") on diagonal.
Also added diagonal xlabels if triangle="upper" is given
Diagonal labels will be used automatically if marginal=False
x labels for bottom plots and y labels for left plots will be used only if marginal=True, because otherwise diagonal labels will be there to label the rows and cols(automatically, as mentioned above).
**Enforcing remove_axis=False if marginal=True. Because if we have marginals we definitely need xlabels and ylabels to label rows and cols ( since diagonal labels won't be there and removing axis will remove axis labels too).
sharex and sharey is set to True. If marginal=True then we can't have sharey=True, so that is forced to be False.
added a new remove_matrix_axis function, which is same as remove_axis in visuals, but since remove_axis wasn't compatible with map_triangle of PlotMatrix, so I needed one which is compatible to map_triangle.

We are getting warning in Bokeh whenever we use upper or lower triangle, it says renderer wasn't found for some plots

Examples:

Code 1

from arviz_base import load_arviz_data

import arviz_plots as azp

azp.style.use("arviz-variat")

data = load_arviz_data("centered_eight")
pc = azp.plot_pair(
    data,
    backend="bokeh" , 
    var_names=["mu","tau","theta"],
    coords={"school": ["Choate", "Deerfield"]},
    marginal=True,
    marginal_kind="kde",
    triangle="both",
    visuals={"divergence": True},
)
pc.show()

result 1

code 2

from arviz_base import load_arviz_data

import arviz_plots as azp

azp.style.use("arviz-variat")

data = load_arviz_data("centered_eight")
pc = azp.plot_pair(
    data,
    backend="bokeh" , 
    var_names=["mu","tau","theta"],
    coords={"school": ["Choate", "Deerfield"]},
    marginal=True,
    marginal_kind="hist",
    triangle="both",
    visuals={"divergence": True},
)
pc.show()

result 2

code 3

from arviz_base import load_arviz_data

import arviz_plots as azp

azp.style.use("arviz-variat")

data = load_arviz_data("centered_eight")
pc = azp.plot_pair(
    data,
    backend="bokeh" , 
    var_names=["mu","tau","theta"],
    coords={"school": ["Choate", "Deerfield"]},
    marginal=True,
    marginal_kind="ecdf",
    triangle="both",
    visuals={"divergence": True},
)
pc.show()

result 3

code 4

from arviz_base import load_arviz_data

import arviz_plots as azp

azp.style.use("arviz-variat")

data = load_arviz_data("centered_eight")
pc = azp.plot_pair(
    data,
    backend="bokeh" , 
    var_names=["mu","tau","theta"],
    coords={"school": ["Choate", "Deerfield"]},
    marginal=True,
    marginal_kind="kde",
    triangle="upper",
    visuals={"divergence": True},
)
pc.show()

code 5

from arviz_base import load_arviz_data

import arviz_plots as azp

azp.style.use("arviz-variat")

data = load_arviz_data("centered_eight")
pc = azp.plot_pair(
    data,
    backend="bokeh" , 
    var_names=["mu","tau","theta"],
    coords={"school": ["Choate", "Deerfield"]},
    marginal=True,
    marginal_kind="kde",
    triangle="lower",
    visuals={"divergence": True},
)
pc.show()

result 5

code 6

from arviz_base import load_arviz_data

import arviz_plots as azp

azp.style.use("arviz-variat")

data = load_arviz_data("centered_eight")
pc = azp.plot_pair(
    data,
    backend="bokeh" , 
    var_names=["mu","tau","theta"],
    coords={"school": ["Choate", "Deerfield"]},
    marginal=False,
    triangle="both",
    visuals={"divergence": True, "remove_axis":{"axis": "both"}},
)
pc.show()

result 6

OriolAbril · 2025-06-21T20:52:39Z

src/arviz_plots/plots/pair_plot.py

+        pc_kwargs["figure_kwargs"].setdefault("sharey", True)
+        pc_kwargs["figure_kwargs"].setdefault("sharex", True)
+        if marginal:
+            pc_kwargs["figure_kwargs"]["sharey"] = False


I just realized we don't want True, I complained about the axis limits for tau and then said to use True which is the reason the axis for tau include negative values. We want sharex="col" and sharey="row" (when present).

Re the if marginal case, I think it is OK but I hesitate a bit between having this hardcoded or still as setdefault (that is, only call setdefault for sharey when "not marginal"). It is a design question about whether we want to allow users to make terrible dataviz choices when they change defaults vs enforcing all kwargs the users provide.

This required a little bit logic change in bokeh backend's create_plotting_grid function. Before the logic was such that we couldn't have sharex="col" and sharey="row" simultaneously. Since they were mutually exclusive so it was throwing error . Fixed that in backend.

Also since having just text on diagonal plots when marginal is False was little bit weird because we required to give x and y location of text which varied for different variables ( in case if we want them to be at centre). So now I added scatter plot for diagonal plots as well when marginal is False. Otherwise we will have marginals

This required a little bit logic change in bokeh backend's create_plotting_grid function

Thanks! Bokeh has always been the one to generate more trouble for us so it ends up being less used and worked on. The refactor is making things much better on this end but still not fully there.

Also since having just text on diagonal plots when marginal is False was little bit weird because we required to give x and y location of text which varied for different variables ( in case if we want them to be at centre). So now I added scatter plot for diagonal plots as well when marginal is False. Otherwise we will have marginals

I don't think there is any case where we want the scatter against itself. It is ok as a subproduct in plot_pair_focus when removing it grealy increases complexity of the code, but I would not add it explicitly.

I see two options on this. One is doing some updates to the initialization of PlotMatrix in order to request a grid with one less column but same number of rows, and storing it like so in the "plot" dataarray (which would still have the same shape and coordinates) with None on the diagonal. Example for 3 variables, we generate a 3x2 grid:

None | 0, 0 | 0, 1 1, 0 | None | 1, 1 2, 0 | 2, 1 | None

This means there are no diagonal elements to be filled at all.

Alternatively, adapt the code for the labels along the diagonal. The backend text function takes vertical and horizontal alignment which we can set to center the text around the provided x and y. And as that would be for the case without marginals with axis sharing, the x and y would actually be the same value, and we can compute it as:

text_center = (distribution.max(dim=sample_dims) + distribution.min(dim=sample_dims)) / 2

which should get something that looks centered

src/arviz_plots/plot_matrix.py

OriolAbril · 2025-06-21T21:17:55Z

src/arviz_plots/plots/pair_plot.py

+    sample_dims=None,
+    plot_matrix=None,


To keep consistency with the other functions, marginal, marginal_kind and triangle should go between sample_dims and plot_matrix (as it is the equivalent to plot_collection: https://arviz-plots.readthedocs.io/en/latest/contributing/new_plot.html

src/arviz_plots/plots/pair_plot.py

OriolAbril

next round of review. I think it is shaping up very well

OriolAbril · 2025-06-23T15:49:22Z

src/arviz_plots/plots/pair_plot.py

+        marginal_kwargs = copy(visuals.get("marginal", {}))
+        dist_plot_visuals = {}
+        dist_plot_aes_by_visuals = {}
+        dist_plot_stats = {}
+        dist_plot_visuals["dist"] = marginal_kwargs
+        dist_plot_visuals["title"] = False
+        dist_plot_visuals["point_estimate"] = False
+        dist_plot_visuals["point_estimate_text"] = False
+        dist_plot_visuals["credible_interval"] = False
+        if remove_axis_bool is False:
+            dist_plot_visuals["remove_axis"] = False
+        dist_plot_visuals["rug"] = False
+        dist_plot_aes_by_visuals["dist"] = aes_by_visuals.get("marginal", {})
+        dist_plot_stats["dist"] = stats.get("marginal", {})


maybe we should allow users to customize plot_dist on the diagonals to add the credible interval too or the point estimate.

OriolAbril · 2025-06-23T15:57:40Z

src/arviz_plots/plots/pair_plot.py

+
+    # scatter
+
+    aes_by_visuals["scatter"] = {"overlay"}.union(aes_by_visuals.get("scatter", {}))


I would recommend defining all aes_by_visuals defaults in a block here, right after defining plot_collection. This makes it much easier to know what mappings are active by default in general. We need to properly think about these defaults too.

For scatter for example I think we want all defined aesthetic mappings by default, with the provided ones+overlay otherwise. That is. like trace in plot_trace_dist (not like divergence in plot_trace_dist). We also want the default to disable overlay for the marginal element.

OriolAbril · 2025-06-23T16:01:20Z

src/arviz_plots/plot_matrix.py

+        else:
+            var_name_x = var_name
+            selection_x = selection


Given the behaviour of subset_matrix_da I think this means that the simple fact of var_name_y and selection_y being None will already behave like "diagonal" even if the orientation attribute is not None. I think it is actually fine and we only need to check orientation row or col, with no orientation meaning "diagonal" which I think is a good default.

OriolAbril · 2025-06-23T16:02:08Z

src/arviz_plots/plot_matrix.py

@@ -355,6 +418,9 @@ def map_triangle(
                artist_dims=artist_dims,
                ignore_aes=ignore_aes,
            )
+
+        self.orientation = None


I would actually raise if orientation is set here (see other comments too).

OriolAbril · 2025-06-23T16:03:58Z

src/arviz_plots/plot_matrix.py

+    @property
+    def orientation(self):
+        """Orientation of targets we want to fetch through :meth:`~PlotMatrix.get_target`.
+
+        Orientation is always taken into account when using
+        :meth:`~PlotMatrix.get_target` to fetch target for plotting.
+        """
+        return self._orientation
+
+    @orientation.setter
+    def orientation(self, value):
+        self._orientation = value
+
+    @property
+    def fixed_var_name(self):
+        """Fixed variable's name of targets we fetch through :meth:`~PlotMatrix.get_target`.
+
+        fixed_var_name is taken into account when using :meth:`~PlotMatrix.get_target`
+        to fetch target for plotting and :attr:`~PlotMatrix.orientation` is
+        set to either `row` or `col`.
+
+        It tells the fixed variable name in a `row` or `col`
+        """
+        return self._fixed_var_name
+
+    @fixed_var_name.setter
+    def fixed_var_name(self, value):
+        self._fixed_var_name = value
+
+    @property
+    def fixed_selection(self):
+        """Fixed dictionary for subsetting of targets."""
+        return self._fixed_selection
+
+    @fixed_selection.setter
+    def fixed_selection(self, value):
+        self._fixed_selection = value
+
+    @fixed_var_name.setter
+    def fixed_var_name(self, value):
+        self._fixed_var_name = value


I think we could have them as "simple" attributes set to None in __init__. Moreover, I don't think we expect/want users to interact with them directly but more so as an internal thing to reduce duplication between map and map_row_col

src/arviz_plots/plot_matrix.py

OriolAbril · 2025-06-23T16:05:09Z

src/arviz_plots/plot_matrix.py

@@ -473,11 +632,11 @@ def map(
        --------
        arviz_plots.PlotMatrix.map_triangle
        """
+        self.set_fixed_var_attributes(index, orientation)


Here also revert the 3 attributes to None before returning.

… except text

OriolAbril · 2025-06-25T08:10:06Z

src/arviz_plots/plots/pair_plot.py

+    coords=None,
+    sample_dims=None,
+    marginal=True,
+    marginal_kind="kde",


default to rcparam or even none and pass to plot_dist so plot_dist changes none to the rcparam

OriolAbril

mostly test and doc polishing left and we can merge

OriolAbril · 2025-06-29T14:26:37Z

docs/source/gallery/distribution/08_plot_pair_distribution.py

+    marginal=True,
+    marginal_kind="kde",


I would remove these two arguments given they are the defaults

OriolAbril · 2025-06-29T14:27:30Z

docs/source/gallery/inference_diagnostics/10_plot_pair.py

+dt = load_arviz_data("centered_eight")
+pc = azp.plot_pair(
+    dt,
+    var_names=["theta", "mu"],


Suggested change

var_names=["theta", "mu"],

var_names=["theta", "tau"],

Tau is the interesting one to vizualize with divergences

OriolAbril · 2025-06-29T14:28:27Z

docs/source/gallery/inference_diagnostics/10_plot_pair.py

+    marginal=True,
+    marginal_kind="kde",


maybe change this so the plot looks more different than the one in the distributions section

Suggested change

marginal=True,

marginal_kind="kde",

marginal=False,

OriolAbril · 2025-06-29T14:31:17Z

src/arviz_plots/backend/bokeh/__init__.py

@@ -317,31 +317,33 @@ def create_plotting_grid(
                subplot_kws_i["y_range"] = shared_yrange[col]
            if width_ratios is not None:
                subplot_kws["width"] = plot_widths[col]
+
+            if row * cols + (col + 1) > number:


we should add tests for this, but we don't yet have the setup for backend specific tests. I will ping you once I start working on this issue so we can both add tests for backend functions

OriolAbril · 2025-06-29T14:36:38Z

src/arviz_plots/plot_matrix.py

+            Dictionary of {coordinate names : coordinate values} that should
+            be used to subset the aes, data and viz objects before any faceting
+            or aesthetics mapping is applied.
+        ignore_aes : set, optional


Suggested change

ignore_aes : set, optional

ignore_aes : str or set of str, default "all"

OriolAbril · 2025-06-29T14:37:05Z

src/arviz_plots/plot_matrix.py

+        artist_dims : mapping of {hashable : int}, optional
+            Dictionary of sizes for proper allocation and storage when using
+            ``map`` with functions that return an array of :term:`visual`.
+        **kwargs : mapping, optional


Suggested change

**kwargs : mapping, optional

**kwargs

OriolAbril · 2025-06-29T14:38:36Z

src/arviz_plots/plot_matrix.py

+
+        See Also
+        --------
+        arviz_plots.PlotMatrix.map_triangle


I think all 4: map, map_triangle, map_row and map_col should reference the other three in their see also sections, with the first one being the most relevant one, map_row<->map_col and map<->map_triangle.

OriolAbril · 2025-06-29T14:44:01Z

tests/test_plots.py

@@ -332,6 +333,59 @@ def test_plot_mcse_models(self, datatree, datatree2, backend):
        assert "model" in pc.aes["color"].dims
        assert "/x" in pc.aes.groups

+    def test_plot_pair(self, datatree, backend):


either here or in follow up tests we should make sure that triangle argument is taken into account. That is, with triangle both scatter only has None on the diagonal, with lower on the diagonal and above... Same thing for marginal=False

OriolAbril · 2025-06-29T14:44:40Z

docs/source/gallery/distribution/08_plot_pair_distribution.py

@@ -0,0 +1,27 @@
+"""
+# Scatterplot all variable against each other


Suggested change

# Scatterplot all variable against each other

# Scatterplot all variables against each other

The-Broken-Keyboard marked this pull request as draft June 13, 2025 10:45

aloctavodia reviewed Jun 16, 2025

View reviewed changes

The-Broken-Keyboard force-pushed the pair_plot branch from 9c7ab36 to 4361a25 Compare June 18, 2025 06:50

OriolAbril reviewed Jun 18, 2025

View reviewed changes

The-Broken-Keyboard added 5 commits June 20, 2025 11:02

pair plot initial commit

637a03d

minor change

41527fc

added documentation

506f2a8

added marginals, last row & col labels, map_to_row_col func, triangle…

4bc058a

… versions

added pair_plot to plots.rst

ca67395

The-Broken-Keyboard force-pushed the pair_plot branch from 98c176c to ca67395 Compare June 20, 2025 05:41

The-Broken-Keyboard added 3 commits June 20, 2025 12:49

changed logic of remove_axis a bit

8af1452

minore fix

1aada47

fixed docstring

123fd11

OriolAbril reviewed Jun 21, 2025

View reviewed changes

The-Broken-Keyboard added 2 commits June 23, 2025 16:02

more corrections

9aeb5f3

added tests in test_plots and test_hypothesis_plots

90911e2

The-Broken-Keyboard marked this pull request as ready for review June 23, 2025 12:17

OriolAbril reviewed Jun 23, 2025

View reviewed changes

The-Broken-Keyboard added 4 commits June 23, 2025 23:35

more fixes

b5aee90

fixed axis collapsing issue when nothing is present on diagonal plots…

7a69074

… except text

minor fix

72da9f9

separated map_row and map_col

03d22d0

OriolAbril reviewed Jun 25, 2025

View reviewed changes

The-Broken-Keyboard added 2 commits June 25, 2025 20:56

modified default values

2ef8903

fixed key in aes_by_visuals of dist_plot and others

c46f6d4

OriolAbril reviewed Jun 29, 2025

View reviewed changes

polished docs and tests

af3c340

minor change

127c32b


		# scatter

		aes_by_visuals["scatter"] = {"overlay"}.union(aes_by_visuals.get("scatter", {}))

	ignore_aes : set, optional
	ignore_aes : str or set of str, default "all"

		@@ -0,0 +1,27 @@
		"""
		# Scatterplot all variable against each other

	# Scatterplot all variable against each other
	# Scatterplot all variables against each other

Uh oh!

Adds Pair plot #287

Are you sure you want to change the base?

Adds Pair plot #287

Uh oh!

Conversation

The-Broken-Keyboard commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

The-Broken-Keyboard commented Jun 13, 2025

Uh oh!

aloctavodia left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

The-Broken-Keyboard commented Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

We are getting warning in Bokeh whenever we use upper or lower triangle, it says renderer wasn't found for some plots

Code 1

result 1

code 2

result 2

code 3

result 3

code 4

code 5

result 5

code 6

result 6

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

OriolAbril left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

OriolAbril left a comment

Choose a reason for hiding this comment

The-Broken-Keyboard commented Jun 13, 2025 •

edited

Loading

codecov-commenter commented Jun 13, 2025 •

edited

Loading

The-Broken-Keyboard commented Jun 20, 2025 •

edited

Loading