wip

Author: nicolaskruchten

packages/python/plotly/plotly/express/__init__.py

@@ -34,6 +34,8 @@
     box,
     strip,
     histogram,
+    ecdf,
+    kde,
     scatter_matrix,
     parallel_coordinates,
     parallel_categories,
@@ -89,6 +91,8 @@
     "box",
     "strip",
     "histogram",
+    "ecdf",
+    "kde",
     "choropleth",
     "choropleth_mapbox",
     "pie",

packages/python/plotly/plotly/express/_chart_types.py

@@ -477,6 +477,121 @@ def histogram(
 )
 
 
+def ecdf(
+    data_frame=None,
+    x=None,
+    y=None,
+    color=None,
+    line_dash=None,
+    facet_row=None,
+    facet_col=None,
+    facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
+    hover_name=None,
+    hover_data=None,
+    animation_frame=None,
+    animation_group=None,
+    category_orders=None,
+    labels=None,
+    color_discrete_sequence=None,
+    color_discrete_map=None,
+    line_dash_sequence=None,
+    line_dash_map=None,
+    marginal=None,
+    opacity=None,
+    orientation=None,
+    line_shape=None,
+    norm=None,  # TODO use this
+    complementary=None,  # TODO use this
+    log_x=False,
+    log_y=False,
+    range_x=None,
+    range_y=None,
+    title=None,
+    template=None,
+    width=None,
+    height=None,
+):
+    """
+    In a Empirical Cumulative Distribution Function (ECDF) plot, rows of `data_frame`
+    are sorted by the value `x` (or `y` if `orientation` is `'h'`) and their cumulative
+    count (or the cumulative sum of `y` if supplied and `orientation` is `h`) is drawn
+    as a line.
+    """
+    return make_figure(args=locals(), constructor=go.Scatter)
+
+
+ecdf.__doc__ = make_docstring(
+    ecdf,
+    append_dict=dict(
+        x=[
+            "If `orientation` is `'h'`, the cumulative sum of this argument is plotted rather than the cumulative count."
+        ]
+        + _wide_mode_xy_append,
+        y=[
+            "If `orientation` is `'v'`, the cumulative sum of this argument is plotted rather than the cumulative count."
+        ]
+        + _wide_mode_xy_append,
+    ),
+)
+
+
+def kde(
+    data_frame=None,
+    x=None,
+    y=None,
+    color=None,
+    line_dash=None,
+    facet_row=None,
+    facet_col=None,
+    facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
+    hover_name=None,
+    hover_data=None,
+    animation_frame=None,
+    animation_group=None,
+    category_orders=None,
+    labels=None,
+    color_discrete_sequence=None,
+    color_discrete_map=None,
+    line_dash_sequence=None,
+    line_dash_map=None,
+    marginal=None,
+    opacity=None,
+    orientation=None,
+    norm=None,  # TODO use this
+    kernel=None,  # TODO use this
+    bw_method=None,  # TODO use this
+    bw_adjust=None,  # TODO use this
+    log_x=False,
+    log_y=False,
+    range_x=None,
+    range_y=None,
+    title=None,
+    template=None,
+    width=None,
+    height=None,
+):
+    """
+    In a Kernel Density Estimation (KDE) plot, rows of `data_frame`
+    are used as inputs to a KDE smoothing function which is rendered as a line.
+    """
+    return make_figure(args=locals(), constructor=go.Scatter)
+
+
+kde.__doc__ = make_docstring(
+    kde,
+    append_dict=dict(
+        x=["If `orientation` is `'h'`, this argument is used as KDE weights."]
+        + _wide_mode_xy_append,
+        y=["If `orientation` is `'v'`, this argument is used as KDE weights."]
+        + _wide_mode_xy_append,
+    ),
+)
+
+
 def violin(
     data_frame=None,
     x=None,

packages/python/plotly/plotly/express/_core.py

@@ -1316,6 +1316,9 @@ def build_dataframe(args, constructor):
     wide_cross_name = None  # will likely be "index" in wide_mode
     value_name = None  # will likely be "value" in wide_mode
     hist2d_types = [go.Histogram2d, go.Histogram2dContour]
+    hist1d_orientation = (
+        constructor == go.Histogram or "complementary" in args or "kernel" in args
+    )
     if constructor in cartesians:
         if wide_x and wide_y:
             raise ValueError(
@@ -1350,7 +1353,7 @@ def build_dataframe(args, constructor):
                 df_provided and var_name in df_input
             ):
                 var_name = "variable"
-            if constructor == go.Histogram:
+            if hist1d_orientation:
                 wide_orientation = "v" if wide_x else "h"
             else:
                 wide_orientation = "v" if wide_y else "h"
@@ -1364,7 +1367,10 @@ def build_dataframe(args, constructor):
         var_name = _escape_col_name(df_input, var_name, [])
 
     missing_bar_dim = None
-    if constructor in [go.Scatter, go.Bar, go.Funnel] + hist2d_types:
+    if (
+        constructor in [go.Scatter, go.Bar, go.Funnel] + hist2d_types
+        and not hist1d_orientation
+    ):
         if not wide_mode and (no_x != no_y):
             for ax in ["x", "y"]:
                 if args.get(ax) is None:
@@ -1461,14 +1467,22 @@ def build_dataframe(args, constructor):
         df_output[var_name] = df_output[var_name].astype(str)
         orient_v = wide_orientation == "v"
 
-        if constructor in [go.Scatter, go.Funnel] + hist2d_types:
+        if hist1d_orientation:
+            args["x" if orient_v else "y"] = value_name
+            if wide_cross_name is None and constructor == go.Scatter:
+                args["y" if orient_v else "x"] = count_name
+                df_output[count_name] = 1
+            else:
+                args["y" if orient_v else "x"] = wide_cross_name
+            args["color"] = args["color"] or var_name
+        elif constructor in [go.Scatter, go.Funnel] + hist2d_types:
             args["x" if orient_v else "y"] = wide_cross_name
             args["y" if orient_v else "x"] = value_name
             if constructor != go.Histogram2d:
                 args["color"] = args["color"] or var_name
             if "line_group" in args:
                 args["line_group"] = args["line_group"] or var_name
-        if constructor == go.Bar:
+        elif constructor == go.Bar:
             if _is_continuous(df_output, value_name):
                 args["x" if orient_v else "y"] = wide_cross_name
                 args["y" if orient_v else "x"] = value_name
@@ -1478,13 +1492,9 @@ def build_dataframe(args, constructor):
                 args["y" if orient_v else "x"] = count_name
                 df_output[count_name] = 1
                 args["color"] = args["color"] or var_name
-        if constructor in [go.Violin, go.Box]:
+        elif constructor in [go.Violin, go.Box]:
             args["x" if orient_v else "y"] = wide_cross_name or var_name
             args["y" if orient_v else "x"] = value_name
-        if constructor == go.Histogram:
-            args["x" if orient_v else "y"] = value_name
-            args["y" if orient_v else "x"] = wide_cross_name
-            args["color"] = args["color"] or var_name
     if no_color:
         args["color"] = None
     args["data_frame"] = df_output
@@ -1973,11 +1983,11 @@ def make_figure(args, constructor, trace_patch=None, layout_patch=None):
                         trace_spec != trace_specs[0]
                         and (
                             trace_spec.constructor in [go.Violin, go.Box]
-                            and m.variable in ["symbol", "pattern"]
+                            and m.variable in ["symbol", "pattern", "dash"]
                         )
                         or (
                             trace_spec.constructor in [go.Histogram]
-                            and m.variable in ["symbol"]
+                            and m.variable in ["symbol", "dash"]
                         )
                     ):
                         pass
@@ -2036,6 +2046,12 @@ def make_figure(args, constructor, trace_patch=None, layout_patch=None):
             ):
                 trace.update(marker=dict(color=trace.line.color))
 
+            if "complementary" in args:  # ECDF
+                base = args["x"] if args["orientation"] == "v" else args["y"]
+                var = args["x"] if args["orientation"] == "h" else args["y"]
+                group = group.sort_values(by=base)
+                group[var] = group[var].cumsum()
+
             patch, fit_results = make_trace_kwargs(
                 args, trace_spec, group, mapping_labels.copy(), sizeref
             )

packages/python/plotly/plotly/express/_doc.py

@@ -558,10 +558,17 @@
         "Sets the number of rendered sectors from any given `level`. Set `maxdepth` to -1 to render all the"
         "levels in the hierarchy.",
     ],
+    norm=["TODO"],
+    complementary=["TODO"],
+    kernel=["TODO"],
+    bw_method=["TODO"],
+    bw_adjust=["TODO"],
 )
 
 
-def make_docstring(fn, override_dict={}, append_dict={}):
+def make_docstring(fn, override_dict=None, append_dict=None):
+    override_dict = {} if override_dict is None else override_dict
+    append_dict = {} if append_dict is None else append_dict
     tw = TextWrapper(width=75, initial_indent="    ", subsequent_indent="    ")
     result = (fn.__doc__ or "") + "\nParameters\n----------\n"
     for param in getfullargspec(fn)[0]:

packages/python/plotly/plotly/tests/test_optional/test_px/test_facets.py

@@ -1,4 +1,3 @@
-import plotly
 import pandas as pd
 import plotly.express as px
 from pytest import approx
@@ -112,25 +111,21 @@ def bad_facet_spacing_df():
 def test_bad_facet_spacing_eror(bad_facet_spacing_df):
     df = bad_facet_spacing_df
     with pytest.raises(
-        ValueError, match="Use the facet_row_spacing argument to adjust this spacing\."
+        ValueError, match="Use the facet_row_spacing argument to adjust this spacing."
     ):
-        fig = px.scatter(
-            df, x="x", y="y", facet_row="category", facet_row_spacing=0.01001
-        )
+        px.scatter(df, x="x", y="y", facet_row="category", facet_row_spacing=0.01001)
     with pytest.raises(
-        ValueError, match="Use the facet_col_spacing argument to adjust this spacing\."
+        ValueError, match="Use the facet_col_spacing argument to adjust this spacing."
     ):
-        fig = px.scatter(
-            df, x="x", y="y", facet_col="category", facet_col_spacing=0.01001
-        )
+        px.scatter(df, x="x", y="y", facet_col="category", facet_col_spacing=0.01001)
     # Check error is not raised when the spacing is OK
     try:
-        fig = px.scatter(df, x="x", y="y", facet_row="category", facet_row_spacing=0.01)
+        px.scatter(df, x="x", y="y", facet_row="category", facet_row_spacing=0.01)
     except ValueError:
         # Error shouldn't be raised, so fail if it is
         assert False
     try:
-        fig = px.scatter(df, x="x", y="y", facet_col="category", facet_col_spacing=0.01)
+        px.scatter(df, x="x", y="y", facet_col="category", facet_col_spacing=0.01)
     except ValueError:
         # Error shouldn't be raised, so fail if it is
         assert False

packages/python/plotly/plotly/tests/test_optional/test_px/test_marginals.py

@@ -14,7 +14,7 @@ def test_xy_marginals(px_fn, marginal_x, marginal_y):
     assert len(fig.data) == 1 + (marginal_x is not None) + (marginal_y is not None)
 
 
-@pytest.mark.parametrize("px_fn", [px.histogram])
+@pytest.mark.parametrize("px_fn", [px.histogram, px.ecdf, px.kde])
 @pytest.mark.parametrize("marginal", [None, "rug", "histogram", "box", "violin"])
 @pytest.mark.parametrize("orientation", ["h", "v"])
 def test_single_marginals(px_fn, marginal, orientation):