Narrow marginal_x/marginal_y="heatmap" to density_heatmap only

density_contour's colorbar (discrete, labeled at contour boundaries) isn't
compatible with the continuous colorbar used by the marginal heatmap strip,
producing misleading visuals. Per maintainer feedback on #5707, drop
density_contour from the feature's scope and keep it for density_heatmap,
which has no such conflict.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: lucasjamar

CHANGELOG.md

@@ -5,7 +5,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## Unreleased
 
 ### Added
-- Support `marginal_x`/`marginal_y="heatmap"` in `density_heatmap`/`density_contour`, drawing a single-row/column heatmap strip in the margin colored by the same `z`/`histfunc` aggregate as the main plot; `text_auto` now also applies to the marginal heatmap strip [[#5706](https://github.com/plotly/plotly.py/issues/5706)]
+- Support `marginal_x`/`marginal_y="heatmap"` in `density_heatmap`, drawing a single-row/column heatmap strip in the margin colored by the same `z`/`histfunc` aggregate as the main plot and sharing its color scale; `text_auto` now also applies to the marginal heatmap strip [[#5706](https://github.com/plotly/plotly.py/issues/5706)]
 
 ### Fixed
 - Fix `hex_to_rgb` parsing of 3-digit shorthand hexadecimal colors such as `#FFF` [[#5662](https://github.com/plotly/plotly.py/pull/5662)], with thanks to @genrichez for the contribution!

doc/python/marginal-plots.md

@@ -39,7 +39,7 @@ Marginal distribution plots are small subplots above or to the right of a main p
 
 ### Scatter Plot Marginals
 
-The `marginal_x` and `marginal_y` arguments accept one of `"histogram"`, `"rug"`, `"box"`, or `"violin"` (see also how to create [histograms](/python/histograms/), [box plots](/python/box-plots/) and [violin plots](/python/violin-plots/) as the main figure), plus `"heatmap"` for `density_heatmap` and `density_contour` (see below).
+The `marginal_x` and `marginal_y` arguments accept one of `"histogram"`, `"rug"`, `"box"`, or `"violin"` (see also how to create [histograms](/python/histograms/), [box plots](/python/box-plots/) and [violin plots](/python/violin-plots/) as the main figure), plus `"heatmap"` for `density_heatmap` (see below).
 
 Marginal plots are linked to the main plot: try zooming or panning on the main plot.
 
@@ -59,9 +59,9 @@ fig = px.density_heatmap(df, x="sepal_length", y="sepal_width", marginal_x="box"
 fig.show()
 ```
 
-### Marginal Heatmaps on Density Heatmaps and Contours
+### Marginal Heatmaps on Density Heatmaps
 
-`marginal_x` and `marginal_y` also accept `"heatmap"` for [`density_heatmap`](/python/2D-Histogram/) and [`density_contour`](/python/2d-histogram-contour/). This draws a single-row or single-column heatmap strip, colored by the same aggregate (`histfunc` of `z`, or count by default) as the main plot, and sharing its color scale.
+`marginal_x` and `marginal_y` also accept `"heatmap"` for [`density_heatmap`](/python/2D-Histogram/). This draws a single-row or single-column heatmap strip, colored by the same aggregate (`histfunc` of `z`, or count by default) as the main plot, and sharing its color scale. This is not supported for `density_contour`, since a contour plot's colorbar is discrete and not compatible with the continuous colorbar used by the marginal heatmap.
 
 ```python
 import plotly.express as px

plotly/express/_chart_types.py

@@ -142,17 +142,6 @@ def density_contour(
             "For `density_heatmap` and `density_contour` these values are used as the inputs to `histfunc`.",
         ],
         histfunc=["The arguments to this function are the values of `z`."],
-        marginal_x=[
-            "Also supports `'heatmap'`, showing a single-row heatmap colored by the aggregate value. "
-            "Uses a default colorscale since `density_contour` has no `color_continuous_scale` argument.",
-        ],
-        marginal_y=[
-            "Also supports `'heatmap'`, showing a single-column heatmap colored by the aggregate value. "
-            "Uses a default colorscale since `density_contour` has no `color_continuous_scale` argument.",
-        ],
-        text_auto=[
-            "Also applies to `marginal_x`/`marginal_y='heatmap'`, in which case the z values are always displayed.",
-        ],
     ),
 )
 

plotly/express/_core.py

@@ -972,10 +972,10 @@ def make_trace_spec(args, constructor, attrs, trace_patch):
                     marginal=letter,
                 )
             elif args["marginal_" + letter] == "heatmap":
-                if constructor not in [go.Histogram2d, go.Histogram2dContour]:
+                if constructor != go.Histogram2d:
                     raise ValueError(
                         "`marginal_x`/`marginal_y` value `'heatmap'` is only supported "
-                        "for `density_heatmap` and `density_contour`."
+                        "for `density_heatmap`."
                     )
                 other_letter = "y" if letter == "x" else "x"
                 heatmap_trace_patch = dict(
@@ -2380,10 +2380,6 @@ def infer_config(args, constructor, trace_patch, layout_patch):
     if constructor in [go.Histogram2d, go.Densitymap, go.Densitymapbox]:
         show_colorbar = True
         trace_patch["coloraxis"] = "coloraxis1"
-    elif constructor == go.Histogram2dContour and (
-        args.get("marginal_x") == "heatmap" or args.get("marginal_y") == "heatmap"
-    ):
-        show_colorbar = True
 
     if "opacity" in args:
         if args["opacity"] is None:
@@ -2677,10 +2673,6 @@ def make_figure(args, constructor, trace_patch=None, layout_patch=None):
                             trace_spec.constructor in [go.Histogram]
                             and m.variable in ["symbol", "dash"]
                         )
-                        or (
-                            trace_spec.constructor == go.Histogram2d
-                            and m.variable in ["symbol", "pattern", "dash", "color"]
-                        )
                     ):
                         pass
                     elif (
@@ -2778,18 +2770,17 @@ def make_figure(args, constructor, trace_patch=None, layout_patch=None):
     if show_colorbar:
         colorvar = (
             "z"
-            if constructor
-            in [go.Histogram2d, go.Histogram2dContour, go.Densitymap, go.Densitymapbox]
+            if constructor in [go.Histogram2d, go.Densitymap, go.Densitymapbox]
             else "color"
         )
-        range_color = args.get("range_color") or [None, None]
+        range_color = args["range_color"] or [None, None]
 
         colorscale_validator = ColorscaleValidator("colorscale", "make_figure")
         coloraxis_dict = dict(
             colorscale=colorscale_validator.validate_coerce(
-                args.get("color_continuous_scale")
+                args["color_continuous_scale"]
             ),
-            cmid=args.get("color_continuous_midpoint"),
+            cmid=args["color_continuous_midpoint"],
             cmin=range_color[0],
             cmax=range_color[1],
             colorbar=dict(

tests/test_optional/test_px/test_marginals.py

@@ -26,14 +26,13 @@ def test_single_marginals(backend, px_fn, marginal, orientation):
     assert len(fig.data) == 1 + (marginal is not None)
 
 
-@pytest.mark.parametrize("px_fn", [px.density_heatmap, px.density_contour])
-def test_marginal_heatmap_uses_z_and_histfunc(backend, px_fn):
+def test_marginal_heatmap_uses_z_and_histfunc(backend):
     df = px.data.tips(return_type=backend)
     # backend-independent reference for min/max, since e.g. pyarrow columns don't
     # support .min()/.max() directly
     pdf = px.data.tips()
 
-    fig = px_fn(
+    fig = px.density_heatmap(
         df,
         x="total_bill",
         y="tip",
@@ -66,11 +65,12 @@ def test_marginal_heatmap_uses_z_and_histfunc(backend, px_fn):
     assert fig.layout.coloraxis.colorbar.title.text == "sum of size"
 
 
-@pytest.mark.parametrize("px_fn", [px.density_heatmap, px.density_contour])
-def test_marginal_heatmap_without_z(backend, px_fn):
+def test_marginal_heatmap_without_z(backend):
     df = px.data.tips(return_type=backend)
 
-    fig = px_fn(df, x="total_bill", y="tip", marginal_x="heatmap", marginal_y="heatmap")
+    fig = px.density_heatmap(
+        df, x="total_bill", y="tip", marginal_x="heatmap", marginal_y="heatmap"
+    )
     marginal_x_trace, marginal_y_trace = fig.data[1], fig.data[2]
 
     assert marginal_x_trace.type == "histogram2d"
@@ -84,12 +84,11 @@ def test_marginal_heatmap_without_z(backend, px_fn):
     assert fig.layout.coloraxis.colorbar.title.text == "count"
 
 
-@pytest.mark.parametrize("px_fn", [px.density_heatmap, px.density_contour])
 @pytest.mark.parametrize("text_auto", [True, ".1f"])
-def test_marginal_heatmap_text_auto(backend, px_fn, text_auto):
+def test_marginal_heatmap_text_auto(backend, text_auto):
     df = px.data.tips(return_type=backend)
 
-    fig = px_fn(
+    fig = px.density_heatmap(
         df,
         x="total_bill",
         y="tip",
@@ -102,11 +101,12 @@ def test_marginal_heatmap_text_auto(backend, px_fn, text_auto):
         assert trace.texttemplate == expected
 
 
-@pytest.mark.parametrize("px_fn", [px.density_heatmap, px.density_contour])
-def test_marginal_heatmap_no_text_auto(backend, px_fn):
+def test_marginal_heatmap_no_text_auto(backend):
     df = px.data.tips(return_type=backend)
 
-    fig = px_fn(df, x="total_bill", y="tip", marginal_x="heatmap", marginal_y="heatmap")
+    fig = px.density_heatmap(
+        df, x="total_bill", y="tip", marginal_x="heatmap", marginal_y="heatmap"
+    )
     for trace in fig.data:
         assert trace.texttemplate is None
 
@@ -118,20 +118,12 @@ def test_marginal_heatmap_unsupported_chart_type_raises():
         px.scatter(x=[1, 2, 3], y=[2, 3, 4], marginal_y="heatmap")
     with pytest.raises(ValueError, match="only supported for `density_heatmap`"):
         px.histogram(x=[1, 2, 3], marginal="heatmap")
-
-
-def test_marginal_heatmap_with_discrete_color(backend):  # density_contour + line.color
-    df = px.data.tips(return_type=backend)
-    fig = px.density_contour(
-        df, x="total_bill", y="tip", color="sex", marginal_x="heatmap"
-    )
-    assert len(fig.data) == 4
-    assert [t.type for t in fig.data] == [
-        "histogram2dcontour",
-        "histogram2d",
-        "histogram2dcontour",
-        "histogram2d",
-    ]
+    # density_contour's discrete-looking colorbar isn't compatible with the
+    # continuous marginal heatmap colorbar, so it's intentionally unsupported
+    with pytest.raises(ValueError, match="only supported for `density_heatmap`"):
+        px.density_contour(x=[1, 2, 3], y=[2, 3, 4], marginal_x="heatmap")
+    with pytest.raises(ValueError, match="only supported for `density_heatmap`"):
+        px.density_contour(x=[1, 2, 3], y=[2, 3, 4], marginal_y="heatmap")
 
 
 def test_unsupported_marginal_raises_clear_error():  # issue 4654