density_heatmap and fixes to density_contour

Author: nicolaskruchten

gallery.md

@@ -112,7 +112,7 @@ px.scatter(gapminder, x="gdpPercap", y="lifeExp", animation_frame="year", animat
 
 ```python
 px.line(gapminder, x="year", y="lifeExp", color="continent", line_group="country", hover_name="country",
-        line_shape="spline")
+        line_shape="spline", render_mode="svg")
 ```
 
 ```python
@@ -129,6 +129,10 @@ px.density_contour(iris, x="sepal_width", y="sepal_length")
 px.density_contour(iris, x="sepal_width", y="sepal_length", color="species", marginal_x="rug", marginal_y="histogram")
 ```
 
+```python
+px.density_heatmap(iris, x="sepal_width", y="sepal_length", marginal_x="rug", marginal_y="histogram")
+```
+
 ```python
 px.bar(tips, x="sex", y="total_bill", color="smoker", barmode="group")
 ```

plotly_express/__init__.py

@@ -30,6 +30,7 @@
     parallel_categories,
     choropleth,
     density_contour,
+    density_heatmap,
 )
 
 from ._core import (  # noqa: F401
@@ -50,6 +51,7 @@
     "scatter_geo",
     "scatter_matrix",
     "density_contour",
+    "density_heatmap",
     "line",
     "line_polar",
     "line_ternary",

plotly_express/_chart_types.py

@@ -58,6 +58,7 @@ def density_contour(
     data_frame,
     x=None,
     y=None,
+    z=None,
     color=None,
     facet_row=None,
     facet_col=None,
@@ -77,25 +78,91 @@ def density_contour(
     log_y=False,
     range_x=None,
     range_y=None,
+    histfunc=None,
+    histnorm=None,
+    nbinsx=None,
+    nbinsy=None,
     title=None,
     template=None,
     width=None,
     height=None,
 ):
     """
     In a density contour plot, rows of `data_frame` are grouped together into contour marks to \
-    visualize the density of their distribution in 2D space.
+    visualize the 2D distribution of an aggregate function `histfunc` (e.g. the count or sum) \
+    of the value `z`.
     """
     return make_figure(
         args=locals(),
         constructor=go.Histogram2dContour,
-        trace_patch=dict(contours=dict(coloring="none")),
+        trace_patch=dict(
+            contours=dict(coloring="none"),
+            histfunc=histfunc,
+            histnorm=histnorm,
+            nbinsx=nbinsx,
+            nbinsy=nbinsy,
+            xbingroup="x",
+            ybingroup="y",
+        ),
     )
 
 
 density_contour.__doc__ = make_docstring(density_contour)
 
 
+def density_heatmap(
+    data_frame,
+    x=None,
+    y=None,
+    z=None,
+    facet_row=None,
+    facet_col=None,
+    hover_name=None,
+    hover_data=None,
+    animation_frame=None,
+    animation_group=None,
+    category_orders={},
+    labels={},
+    color_continuous_scale=None,
+    color_continuous_midpoint=None,
+    marginal_x=None,
+    marginal_y=None,
+    opacity=None,
+    log_x=False,
+    log_y=False,
+    range_x=None,
+    range_y=None,
+    histfunc=None,
+    histnorm=None,
+    nbinsx=None,
+    nbinsy=None,
+    title=None,
+    template=None,
+    width=None,
+    height=None,
+):
+    """
+    In a density heatmap, rows of `data_frame` are grouped together into colored \
+    rectangular tiles to visualize the 2D distribution of an aggregate function \
+    `histfunc` (e.g. the count or sum) of the value `z`.
+    """
+    return make_figure(
+        args=locals(),
+        constructor=go.Histogram2d,
+        trace_patch=dict(
+            histfunc=histfunc,
+            histnorm=histnorm,
+            nbinsx=nbinsx,
+            nbinsy=nbinsy,
+            xbingroup="x",
+            ybingroup="y",
+        ),
+    )
+
+
+density_heatmap.__doc__ = make_docstring(density_heatmap)
+
+
 def line(
     data_frame,
     x=None,
@@ -164,7 +231,6 @@ def area(
     range_x=None,
     range_y=None,
     line_shape=None,
-    render_mode="auto",
     title=None,
     template=None,
     width=None,
@@ -268,7 +334,8 @@ def histogram(
 ):
     """
     In a histogram, rows of `data_frame` are grouped together into a rectangular mark to \
-    visualize some aggregate quantity like count or sum.
+    visualize the 1D distribution of an aggregate function `histfunc` (e.g. the count or sum) \
+    of the value `y` (or `x` if `orientation` is `'h'`).
     """
     return make_figure(
         args=locals(),
@@ -278,8 +345,9 @@ def histogram(
             histnorm=histnorm,
             histfunc=histfunc,
             nbinsx=nbins if orientation == "v" else None,
-            nbinsy=nbins if orientation == "h" else None,
+            nbinsy=None if orientation == "v" else nbins,
             cumulative=dict(enabled=cumulative),
+            bingroup="x" if orientation == "v" else "y",
         ),
         layout_patch=dict(barmode=barmode, barnorm=barnorm),
     )

plotly_express/_core.py

@@ -3,7 +3,8 @@
 import plotly.io as pio
 from collections import namedtuple, OrderedDict
 from .colors import qualitative, sequential
-import math, pandas
+import math
+import pandas
 
 
 class PxDefaults(object):
@@ -88,8 +89,9 @@ def get_label(args, column):
 def get_decorated_label(args, column, role):
     label = get_label(args, column)
     if "histfunc" in args and (
-        (role == "x" and args["orientation"] == "h")
-        or (role == "y" and args["orientation"] == "v")
+        (role == "x" and "orientation" in args and args["orientation"] == "h")
+        or (role == "y" and "orientation" in args and args["orientation"] == "v")
+        or (role == "z")
     ):
         if label:
             return "%s of %s" % (args["histfunc"] or "count", label)
@@ -171,8 +173,13 @@ def make_trace_kwargs(args, trace_spec, g, mapping_labels, sizeref):
                 mapping_labels["%{xaxis.title.text}"] = "%{x}"
                 mapping_labels["%{yaxis.title.text}"] = "%{y}"
 
-        elif v is not None or (
-            trace_spec.constructor == go.Histogram and k in ["x", "y"]
+        elif (
+            v is not None
+            or (trace_spec.constructor == go.Histogram and k in ["x", "y"])
+            or (
+                trace_spec.constructor in [go.Histogram2d, go.Histogram2dContour]
+                and k == "z"
+            )
         ):
             if k == "size":
                 if "marker" not in result:
@@ -222,20 +229,28 @@ def make_trace_kwargs(args, trace_spec, g, mapping_labels, sizeref):
                     result[error_xy] = {}
                 result[error_xy][arr] = g[v]
             elif k == "hover_name":
-                if trace_spec.constructor not in [go.Histogram, go.Histogram2dContour]:
+                if trace_spec.constructor not in [
+                    go.Histogram,
+                    go.Histogram2d,
+                    go.Histogram2dContour,
+                ]:
                     result["hovertext"] = g[v]
                     if hover_header == "":
                         hover_header = "<b>%{hovertext}</b><br><br>"
             elif k == "hover_data":
-                if trace_spec.constructor not in [go.Histogram, go.Histogram2dContour]:
+                if trace_spec.constructor not in [
+                    go.Histogram,
+                    go.Histogram2d,
+                    go.Histogram2dContour,
+                ]:
                     result["customdata"] = g[v].values
                     for i, col in enumerate(v):
                         v_label_col = get_decorated_label(args, col, None)
                         mapping_labels[v_label_col] = "%%{customdata[%d]}" % i
             elif k == "color":
                 if trace_spec.constructor == go.Choropleth:
                     result["z"] = g[v]
-                    result["z"]["coloraxis"] = "coloraxis1"
+                    result["coloraxis"] = "coloraxis1"
                     mapping_labels[v_label] = "%{z}"
                 else:
                     colorable = "marker"
@@ -255,7 +270,7 @@ def make_trace_kwargs(args, trace_spec, g, mapping_labels, sizeref):
                 if v:
                     result[k] = g[v]
                 mapping_labels[v_label] = "%%{%s}" % k
-    if trace_spec.constructor not in [go.Histogram2dContour, go.Parcoords, go.Parcats]:
+    if trace_spec.constructor not in [go.Parcoords, go.Parcats]:
         hover_lines = [k + "=" + v for k, v in mapping_labels.items()]
         result["hovertemplate"] = hover_header + "<br>".join(hover_lines)
     return result, fit_results
@@ -542,7 +557,7 @@ def make_trace_spec(args, constructor, attrs, trace_patch):
                 trace_spec = TraceSpec(
                     constructor=go.Histogram,
                     attrs=[letter],
-                    trace_patch=dict(opacity=0.5, **axis_map),
+                    trace_patch=dict(opacity=0.5, bingroup=letter, **axis_map),
                 )
             elif args["marginal_" + letter] == "violin":
                 trace_spec = TraceSpec(
@@ -571,10 +586,10 @@ def make_trace_spec(args, constructor, attrs, trace_patch):
                         **axis_map
                     ),
                 )
-            if "color" in attrs:
+            if "color" in attrs or "color" not in args:
                 if "marker" not in trace_spec.trace_patch:
                     trace_spec.trace_patch["marker"] = dict()
-                first_default_color = args["color_discrete_sequence"][0]
+                first_default_color = args["color_continuous_scale"][0]
                 trace_spec.trace_patch["marker"]["color"] = first_default_color
             result.append(trace_spec)
     if "trendline" in args and args["trendline"]:
@@ -702,6 +717,11 @@ def infer_config(args, constructor, trace_patch):
         grouped_attrs.append("marker.symbol")
 
     trace_patch = trace_patch.copy()
+
+    if constructor == go.Histogram2d:
+        show_colorbar = True
+        trace_patch["coloraxis"] = "coloraxis1"
+
     if "opacity" in args:
         if args["opacity"] is None:
             if "barmode" in args and args["barmode"] == "overlay":
@@ -797,8 +817,8 @@ def make_figure(args, constructor, trace_patch={}, layout_patch={}):
         trace_names = trace_names_by_frame[frame_name]
 
         for trace_spec in trace_specs:
-            constructor = trace_spec.constructor
-            if constructor in [go.Scatter, go.Scatterpolar]:
+            constructor_to_use = trace_spec.constructor
+            if constructor_to_use in [go.Scatter, go.Scatterpolar]:
                 if "render_mode" in args and (
                     args["render_mode"] == "webgl"
                     or (
@@ -807,11 +827,18 @@ def make_figure(args, constructor, trace_patch={}, layout_patch={}):
                         and args["animation_frame"] is None
                     )
                 ):
-                    constructor = (
-                        go.Scattergl if constructor == go.Scatter else go.Scatterpolargl
+                    constructor_to_use = (
+                        go.Scattergl
+                        if constructor_to_use == go.Scatter
+                        else go.Scatterpolargl
                     )
-            trace = trace_spec.constructor(name=trace_name)
-            if trace_spec.constructor not in [go.Parcats, go.Parcoords, go.Choropleth]:
+            trace = constructor_to_use(name=trace_name)
+            if trace_spec.constructor not in [
+                go.Parcats,
+                go.Parcoords,
+                go.Choropleth,
+                go.Histogram2d,
+            ]:
                 trace.update(
                     legendgroup=trace_name,
                     showlegend=(trace_name != "" and trace_name not in trace_names),
@@ -870,14 +897,18 @@ def make_figure(args, constructor, trace_patch={}, layout_patch={}):
         )
     layout_patch = layout_patch.copy()
     if show_colorbar:
+        if "color" in args:
+            colorvar = "color"
+        elif constructor == go.Histogram2d:
+            colorvar = "z"
         d = len(args["color_continuous_scale"]) - 1
         layout_patch["coloraxis1"] = dict(
-            colorbar=dict(title=get_decorated_label(args, args["color"], "color")),
             colorscale=[
                 [(1.0 * i) / (1.0 * d), x]
                 for i, x in enumerate(args["color_continuous_scale"])
             ],
             cmid=args["color_continuous_midpoint"],
+            colorbar=dict(title=get_decorated_label(args, args[colorvar], colorvar)),
         )
     for v in ["title", "height", "width", "template"]:
         if args[v]:

plotly_express/_doc.py

@@ -16,14 +16,17 @@
     x=[
         colref,
         "Values from this column are used to position marks along the x axis in cartesian coordinates.",
+        "For horizontal `histogram`s, these values are used as inputs to `histfunc`.",
     ],
     y=[
         colref,
         "Values from this column are used to position marks along the y axis in cartesian coordinates.",
+        "For vertical `histogram`s, these values are used as inputs to `histfunc`.",
     ],
     z=[
         colref,
         "Values from this column are used to position marks along the z axis in cartesian coordinates.",
+        "For `density_heatmap` and `density_contour` these values are used as the inputs to `histfunc`.",
     ],
     a=[
         colref,
@@ -255,12 +258,20 @@
         "(integer, default is 90)",
         "Sets start angle for the angular axis, with 0 being due east and 90 being due north.",
     ],
+    histfunc=[
+        "(string, one of `'count'`, `'sum'`, `'avg'`, `'min'`, `'max'`. Default is `'count'`)"
+        "Function used to aggregate values for summarization (note: can be normalized with `histnorm`).",
+        "The arguments to this function for `histogram` are the values of `y` if `orientation` is `'v'`,",
+        "otherwise the arguements are the values of `x`.",
+        "The arguments to this function for `density_heatmap` and `density_contour` are the values of `z`.",
+    ],
     histnorm=[
         "(string, one of `'percent'`, `'probability'`, `'density'`, `'probability density'`, default `None`)",
-        "If `None`, the span of each bar corresponds to the number of occurrences (i.e. the number of data points lying inside the bins).",
-        "If `'percent'` or `'probability'`, the span of each bar corresponds to the percentage / fraction of occurrences with respect to the total number of sample points (here, the sum of all bin HEIGHTS equals 100% / 1).",
-        "If `'density'`, the span of each bar corresponds to the number of occurrences in a bin divided by the size of the bin interval (here, the sum of all bin AREAS equals the total number of sample points).",
-        "If `'probability density'`, the area of each bar corresponds to the probability that an event will fall into the corresponding bin (here, the sum of all bin AREAS equals 1).",
+        "If `None`, the output of `histfunc` is used as is.",
+        "If `'probability'`, the output of `histfunc` for a given bin is divided by the sum of the output of `histfunc` for all bins.",
+        "If `'percent'`, the output of `histfunc` for a given bin is divided by the sum of the output of `histfunc` for all bins and multiplied by 100.",
+        "If `'density'`, the output of `histfunc` for a given bin is divided by the size of the bin.",
+        "If `'probability density'`, the output of `histfunc` for a given bin is normalized such that it corresponds to the probability that a random event whose distribution is described by the output of `histfunc` will fall into that bin.",
     ],
     barnorm=[
         "(string, one of `'fraction'` or `'percent'`, default is `None`)",
@@ -298,11 +309,6 @@
         "If `True`, an extra line segment is drawn between the first and last point.",
     ],
     line_shape=["(string, one of `'linear'` or `'spline'`)", "Default is `'linear'`."],
-    histfunc=[
-        "(string, one of `'count'`, `'sum'`, `'avg'`, `'min'`, `'max'`. Default is `'count'`)"
-        "Function used to compute histogram bar lengths.",
-        "The arguments to this function are the values of `y` if `orientation` is `'v'`, otherwise the arguements are the values of `x`.",
-    ],
     scope=[
         "(string, one of `'world'`, `'usa'`, `'europe'`, `'asia'`, `'africa'`, `'north america'`, `'south america'`)"
         "Default is `'world'` unless `projection` is set to `'albers usa'`, which forces `'usa'`."
@@ -328,6 +334,8 @@
         "If `True`, histogram values are cumulative.",
     ],
     nbins=["(positive integer)", "Sets the number of bins."],
+    nbinsx=["(positive integer)", "Sets the number of bins along the x axis."],
+    nbinsy=["(positive integer)", "Sets the number of bins along the y axis."],
 )