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,
@@ -88,6 +90,8 @@
     "box",
     "strip",
     "histogram",
+    "ecdf",
+    "kde",
     "choropleth",
     "choropleth_mapbox",
     "pie",

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

@@ -471,6 +471,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

@@ -1275,6 +1275,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(
@@ -1309,7 +1312,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"
@@ -1323,7 +1326,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, None) is None:
@@ -1420,14 +1426,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
@@ -1437,13 +1451,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
@@ -1925,7 +1935,7 @@ def make_figure(args, constructor, trace_patch=None, layout_patch=None):
                     if (
                         trace_spec != trace_specs[0]
                         and trace_spec.constructor in [go.Violin, go.Box, go.Histogram]
-                        and m.variable == "symbol"
+                        and m.variable in ["symbol", "dash"]
                     ):
                         pass
                     elif (
@@ -1986,6 +1996,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

@@ -541,10 +541,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_core/test_px/test_facets.py

@@ -1,4 +1,3 @@
-import plotly
 import pandas as pd
 import plotly.express as px
 from pytest import approx
@@ -47,6 +46,48 @@ def test_facets():
     assert fig.layout.yaxis4.domain[0] - fig.layout.yaxis.domain[1] == approx(0.08)
 
 
+def test_facets_with_marginals():
+    df = px.data.tips()
+
+    fig = px.histogram(df, x="total_bill", facet_col="sex", marginal="rug")
+    assert len(fig.data) == 4
+    # fig = px.histogram(df, x="total_bill", facet_row="sex", marginal="rug")
+    # assert len(fig.data) == 2 buggy
+
+    fig = px.scatter(df, x="total_bill", y="tip", facet_col="sex", marginal_x="rug")
+    assert len(fig.data) == 4
+    fig = px.scatter(
+        df, x="total_bill", y="tip", facet_col="day", facet_col_wrap=2, marginal_x="rug"
+    )
+    assert len(fig.data) == 8  # ignore the wrap when marginal is used
+    fig = px.scatter(df, x="total_bill", y="tip", facet_col="sex", marginal_y="rug")
+    assert len(fig.data) == 2  # ignore the marginal in the facet direction
+
+    fig = px.scatter(df, x="total_bill", y="tip", facet_row="sex", marginal_x="rug")
+    assert len(fig.data) == 2  # ignore the marginal in the facet direction
+    fig = px.scatter(df, x="total_bill", y="tip", facet_row="sex", marginal_y="rug")
+    assert len(fig.data) == 4
+
+    fig = px.scatter(
+        df, x="total_bill", y="tip", facet_row="sex", marginal_y="rug", marginal_x="rug"
+    )
+    assert len(fig.data) == 4  # ignore the marginal in the facet direction
+    fig = px.scatter(
+        df, x="total_bill", y="tip", facet_col="sex", marginal_y="rug", marginal_x="rug"
+    )
+    assert len(fig.data) == 4  # ignore the marginal in the facet direction
+    fig = px.scatter(
+        df,
+        x="total_bill",
+        y="tip",
+        facet_row="sex",
+        facet_col="sex",
+        marginal_y="rug",
+        marginal_x="rug",
+    )
+    assert len(fig.data) == 2  # ignore all marginals
+
+
 @pytest.fixture
 def bad_facet_spacing_df():
     NROWS = 101
@@ -65,25 +106,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_core/test_px/test_marginals.py

@@ -0,0 +1,26 @@
+import plotly.express as px
+import pytest
+
+
+@pytest.mark.parametrize("px_fn", [px.scatter, px.density_heatmap, px.density_contour])
+@pytest.mark.parametrize("marginal_x", [None, "histogram", "box", "violin"])
+@pytest.mark.parametrize("marginal_y", [None, "rug"])
+def test_xy_marginals(px_fn, marginal_x, marginal_y):
+    df = px.data.tips()
+
+    fig = px_fn(
+        df, x="total_bill", y="tip", marginal_x=marginal_x, marginal_y=marginal_y
+    )
+    assert len(fig.data) == 1 + (marginal_x is not None) + (marginal_y is not None)
+
+
+@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):
+    df = px.data.tips()
+
+    fig = px_fn(
+        df, x="total_bill", y="total_bill", marginal=marginal, orientation=orientation
+    )
+    assert len(fig.data) == 1 + (marginal is not None)