Documented functionality and added README

nicholas-esterer · nicholas-esterer · commit 64d8a196c18d · 2020-11-13T18:27:21.000-05:00
look in `proto/px_overlay/README.md` for more information.
diff --git a/proto/px_overlay/README.md b/proto/px_overlay/README.md
@@ -0,0 +1,15 @@
+# `px.overlay` prototype
+
+This demonstrates one possible way of combining two figures into a single
+figure.
+
+To see an example, run (from the root of the `plotly.py` repo):
+
+```bash
+PYTHONPATH=proto/px_overlay python proto/px_overlay/multilayered_data_test.py
+```
+
+To see the code that does the overlaying, start with the `px_simple_overlay`
+function in `proto/px_overlay/px_overlay.py`. In this function there are a few
+comments marked with `TODO` that indicate places for improvement in the
+functionality.
diff --git a/proto/px_overlay/multilayered_data_test.py b/proto/px_overlay/multilayered_data_test.py
@@ -3,11 +3,19 @@
 import plotly.express as px
 from px_overlay import px_simple_overlay
 
+# Demonstrates px_overlay prototype.
+
+# Make some data that can be faceted by row, col and color, and split into 2
+# sets, which will go to the first and second figure respectively.
 df = test_data.multilayered_data(d_divs=[2, 3, 4, 2], rwalk=0.1)
-print(df)
+
+# The titles of the figures use the last dimension in the data. The title is
+# formatted "column_name=column_value", so here we extract the column name.
 last_cat = df.columns[3]
 figs = []
 for px_call, last_cat_0 in zip([px.line, px.bar], list(set(df[last_cat]))):
+    # px_call is the chart type to make and last_cat_0 is the column_value for
+    # that figure which is used in forming the title.
     df_slice = df.loc[df[last_cat] == last_cat_0]
     fig = px_call(
         df_slice,
@@ -17,20 +25,32 @@
         facet_col=df.columns[1],
         color=df.columns[2],
     )
+
     fig.update_layout(title="%s=%s" % (last_cat, last_cat_0,))
     figs.append(fig)
 
+# Add some annotations to make sure they are copied to the final figure properly
 figs[0].add_hline(y=1, row=1, col="all")
-figs[1].add_vline(x=10, row="all", col=2)
 figs[0].add_annotation(
     x=0.25, y=0.5, xref="x domain", yref="y domain", row=2, col=3, text="yo"
 )
+# Note that these annotations should be mapped to a secondary y axis (observe this
+# in the final figure by dragging their corresponding secondary y axes).
+figs[1].add_vline(x=10, row="all", col=2)
 figs[1].add_annotation(
     x=0.5, y=0.35, xref="x domain", yref="y", row=1, col=2, text="budday"
 )
+# Set the bar modes for both to see that the first figure that the barmode for
+# the final figure will be taken from the figure that has bars.
 figs[0].layout.barmode = "group"
 figs[1].layout.barmode = "relative"
+
+# overlay the figures
 final_fig = px_simple_overlay(*figs, fig1_secondary_y=True)
+
+# Show the initial figures
 for fig in figs:
     fig.show()
+
+# Show the final figure
 final_fig.show()
diff --git a/proto/px_overlay/px_overlay.py b/proto/px_overlay/px_overlay.py
@@ -199,8 +199,16 @@ def map_annotation_like_obj_axis(oldfig, newfig, an, force_secondary_y=False):
 
 def px_simple_overlay(fig0, fig1, fig1_secondary_y=False):
     """
-    Combines two figures by just using the layout of the first figure and
-    appending the data of the second figure.
+    Combines two figures by putting all the traces from fig0 and fig1 on a new
+    figure (fig). Then the annotation-like objects are copied to fig (i.e., the
+    titles are not copied).
+    The colors are reassigned so each trace has a unique color until all the
+    colors in the colorway are exhausted and then loops through the colorway to
+    assign additional colors (this is referred to as "reflowing" below).
+    In order to differentiate the traces in the legend, if fig0 or fig1 have
+    titles, they are prepended to the trace name.
+    If fig1_secondary_y is True, then the yaxes from fig1 are placed on
+    secondary y axes in the new figure.
     """
     if fig1_secondary_y and (
         ("px" not in fig0._aux.keys()) or ("px" not in fig0._aux.keys())
@@ -212,17 +220,21 @@ def px_simple_overlay(fig0, fig1, fig1_secondary_y=False):
     grid_ref_shape = fig_grid_ref_shape(fig0)
     if grid_ref_shape != fig_grid_ref_shape(fig1):
         raise ValueError(
-            "Only two figures with the same subplot geometry can be overlayd."
+            "Only two figures with the same subplot geometry can be overlayed."
         )
-    # reflow the colors
+    # get colors for reflowing
     colorway = fig0.layout.template.layout.colorway
     specs = None
     if fig1_secondary_y:
         specs = [
             [dict(secondary_y=True) for __ in range(grid_ref_shape[1])]
             for _ in range(grid_ref_shape[0])
         ]
-    fig = make_subplots(*fig_grid_ref_shape(fig0), specs=specs)
+    # TODO: This needs to detect the start_cell of the input figures rather than
+    # assuming 'bottom-left', which is just the px default start_cell
+    fig = make_subplots(
+        *fig_grid_ref_shape(fig0), specs=specs, start_cell="bottom-left"
+    )
     for r, c in multi_index(*fig_grid_ref_shape(fig)):
         print("row,col", r + 1, c + 1)
         for (tr, f), color in zip(
@@ -232,6 +244,7 @@ def px_simple_overlay(fig0, fig1, fig1_secondary_y=False):
                     for f in [fig0, fig1]
                 ]
             ),
+            # reflow the colors
             cycle(colorway),
         ):
             title = f.layout.title.text
@@ -261,6 +274,8 @@ def px_simple_overlay(fig0, fig1, fig1_secondary_y=False):
     )
     for (oldfig, selector), ((newfig, secy), adder) in zip(selectors, adders):
         for ann in selector(oldfig):
+            # TODO this function needs to eventually take into consideration the
+            # start_cell arguments of the figures involved in the mapping.
             newann = map_annotation_like_obj_axis(
                 oldfig, newfig, ann, force_secondary_y=secy
             )
@@ -270,12 +285,11 @@ def px_simple_overlay(fig0, fig1, fig1_secondary_y=False):
     # title will be wrong
     fig.layout.title = None
     # preserve bar mode
-    # if both figures have barmode set, the first is taken, otherwise the set one is taken
+    # if both figures have barmode set, the first is taken from the figure that
+    # has bars (so just the one from fig0 if both have bars), otherwise the set
+    # one is taken.
     # TODO argument to force barmode? or the user can just update it after
     fig.layout.barmode = get_first_set_barmode([fig0, fig1])
-    # also include annotations, shapes and layout images from fig1
-    for kw in ["annotations", "shapes", "images"]:
-        fig.layout[kw] += fig1.layout[kw]
     return fig
 
 
@@ -312,21 +326,25 @@ def set_main_trace_color(tr, color):
 
 
 def get_first_set_barmode(figs):
+    """ Get first bar mode from the figure that has it set and has bar traces. """
+
+    def _bar_mode_filter(f):
+        return (
+            any([type(tr) == type(go.Bar()) for tr in f.data])
+            and f.layout.barmode is not None
+        )
+
     barmode = None
     try:
-        barmode = list(
-            filter(lambda x: x is not None, [f.layout.barmode for f in figs])
-        )[0]
+        barmode = [f.layout.barmode for f in filter(_bar_mode_filter, figs)][0]
     except IndexError:
         # if no figure sets barmode, then it is not set
         pass
     return barmode
 
 
-df = test_data.aug_tips()
-
-
 def simple_overlay_example():
+    df = test_data.aug_tips()
     fig0 = px.scatter(df, x="total_bill", y="tip", facet_row="sex", facet_col="smoker")
     fig1 = px.histogram(
         df, x="total_bill", y="tip", facet_row="sex", facet_col="smoker"
