exclude_empty_subplots for add_{shape,annotation,layout_image,trace}

These will by default add their respective graph object to all subplots
but if exclude_empty_subplots is True, they will only add the graph
object to those subplots that already have traces on them.

Author: nicholas-esterer

Diff for: packages/python/plotly/plotly/basedatatypes.py

@@ -109,6 +109,9 @@ def _axis_spanning_shapes_docstr(shape_type):
 x1: float or int
     A number representing the x coordinate of the other side of the rectangle."""
     docstr += """
+exclude_empty_subplots: Boolean
+    If True (default) do not place the shape on subplots that have no data
+    plotted on them.
 row: None, int or 'all'
     Subplot row for shape indexed starting at 1. If 'all', addresses all rows in
     the specified column(s). If both row and col are None, addresses the
@@ -1747,7 +1750,9 @@ def _validate_rows_cols(name, n, vals):
         else:
             BaseFigure._raise_invalid_rows_cols(name=name, n=n, invalid=vals)
 
-    def add_trace(self, trace, row=None, col=None, secondary_y=None):
+    def add_trace(
+        self, trace, row=None, col=None, secondary_y=None, exclude_empty_subplots=False
+    ):
         """
         Add a trace to the figure
 
@@ -1787,6 +1792,9 @@ def add_trace(self, trace, row=None, col=None, secondary_y=None):
                 make_subplots. See the make_subplots docstring for more info.
               * The trace argument is a 2D cartesian trace
                 (scatter, bar, etc.)
+        exclude_empty_subplots: boolean
+            If True, the trace will not be added to subplots that don't already
+            have traces.
         Returns
         -------
         BaseFigure
@@ -1832,17 +1840,31 @@ def add_trace(self, trace, row=None, col=None, secondary_y=None):
             # TODO add product argument
             rows_cols = self._select_subplot_coordinates(row, col)
             for r, c in rows_cols:
-                self.add_trace(trace, row=r, col=c, secondary_y=secondary_y)
+                self.add_trace(
+                    trace,
+                    row=r,
+                    col=c,
+                    secondary_y=secondary_y,
+                    exclude_empty_subplots=exclude_empty_subplots,
+                )
             return self
 
         return self.add_traces(
             data=[trace],
             rows=[row] if row is not None else None,
             cols=[col] if col is not None else None,
             secondary_ys=[secondary_y] if secondary_y is not None else None,
+            exclude_empty_subplots=exclude_empty_subplots,
         )
 
-    def add_traces(self, data, rows=None, cols=None, secondary_ys=None):
+    def add_traces(
+        self,
+        data,
+        rows=None,
+        cols=None,
+        secondary_ys=None,
+        exclude_empty_subplots=False,
+    ):
         """
         Add traces to the figure
 
@@ -1879,6 +1901,10 @@ def add_traces(self, data, rows=None, cols=None, secondary_ys=None):
             List of secondary_y booleans for traces to be added. See the
             docstring for `add_trace` for more info.
 
+        exclude_empty_subplots: boolean
+            If True, the trace will not be added to subplots that don't already
+            have traces.
+
         Returns
         -------
         BaseFigure
@@ -1955,6 +1981,16 @@ def add_traces(self, data, rows=None, cols=None, secondary_ys=None):
             for trace, row, col, secondary_y in zip(data, rows, cols, secondary_ys):
                 self._set_trace_grid_position(trace, row, col, secondary_y)
 
+        if exclude_empty_subplots:
+            data = list(
+                filter(
+                    lambda trace: self._subplot_contains_trace(
+                        trace["xaxis"], trace["yaxis"]
+                    ),
+                    data,
+                )
+            )
+
         # Make deep copy of trace data (Optimize later if needed)
         new_traces_data = [deepcopy(trace._props) for trace in data]
 
@@ -3748,9 +3784,7 @@ def _process_multiple_axis_spanning_shapes(
                     lambda x: x is not None,
                     [
                         self._make_axis_spanning_layout_object(
-                            direction,
-                            self.layout[layout_obj][n],
-                            none_if_no_trace=exclude_empty_subplots,
+                            direction, self.layout[layout_obj][n],
                         )
                         for n in range(n_layout_objs_before, n_layout_objs_after)
                     ],