Add proximity_heatmap plot function

[ptajvar]

Adding a proximity heatmap function that is similar to the ColocalizationHeatmap in pixelatorR. The main additions from the previous heatmap is that it supports bubble plots as well as the functionality of highlighting a given set of marker-pairs.

Fixes: PNA-3268

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce it when relevant.

PR checklist:

• This comment contains a description of changes (with reason).
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• If a new tool or package is included, I have updated dependencies in pyproject.toml and cited it properly
• I have checked my code and documentation and corrected any misspellings
• I have documented any significant changes to the code in CHANGELOG.md

---

Note

Low Risk
New visualization helper only; no pipeline, data, or auth changes. Risk is limited to plot correctness and layout.

Overview
Adds pixelator.pna.plot.proximity_heatmap to visualize one-row-per-pair proximity summaries (e.g. from summarize_proximity_scores or calculate_differential_proximity) as a clustered tile heatmap or a dot plot.

Color maps to a value column (default estimate) on a zero-centered divergent scale. The dot mode can size points by a second column (default p_adj), optionally transformed. Marker pairs can be outlined, including per-group colors. Input is optionally symmetrised so only one direction per pair is required.

The function is exported from pixelator.pna.plot, listed in the API overview, and covered by unit tests plus matplotlib image snapshots.

^{Reviewed by Cursor Bugbot for commit 2e5f48e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2e5f48e. Configure here.}

[cursor]

Transform crashes on tiles plots

Medium Severity

size_col_transform runs for every kind, but size_col is only kept in required_columns when kind="dots". After the column subset, kind="tiles" with a transform (and the default size_col="p_adj") looks up a column that was already dropped and raises KeyError, even though size mapping is unused for tiles.

Additional Locations (1)

• src/pixelator/pna/plot/proximity.py#L272-L282

 

^{Reviewed by Cursor Bugbot for commit 2e5f48e. Configure here.}

[cursor]

Tiles clustering fails for one marker

Low Severity

_plot_tiles always forwards cluster_rows / cluster_cols into seaborn.clustermap, while _cluster_order (used for dots) skips clustering when there are fewer than three markers. A one-marker matrix with the default cluster_rows=True makes scipy linkage raise, so tiles can crash on input that dots already handle.

Additional Locations (1)

• src/pixelator/pna/plot/proximity.py#L63-L68

 

^{Reviewed by Cursor Bugbot for commit 2e5f48e. Configure here.}