Revamp tls.get_subplots

plotly/graph_objs/graph_objs.py

@@ -919,6 +919,87 @@ def __init__(self, *args, **kwargs):
                 kwargs['layout'] = Layout()
         super(Figure, self).__init__(*args, **kwargs)
     Figure.__init__ = __init__  # override method!
+
+    def print_grid(self):
+        """Print a visual layout of the figure's axes arrangement.
+
+        This is only valid for figures that are created
+        with plotly.tools.make_subplots.
+        """
+        try:
+            grid_str = self._grid_str
+        except KeyError:
+            raise Exception("Use plotly.tools.make_subplots "
+                            "to create a subplot grid.")
+        print(grid_str)
+    Figure.print_grid = print_grid
+
+    def append_trace(self, trace, row, col):
+        """ Helper function to add a data traces to your figure
+        that is bound to axes at the row, col index.
+
+        The row, col index is generated from figures created with
+        plotly.tools.make_subplots and can be viewed with Figure.print_grid.
+
+        Example:
+        # stack two subplots vertically
+        fig = tools.make_subplots(rows=2)
+
+        This is the format of your plot grid:
+        [ (1,1) x1,y1 ]
+        [ (2,1) x2,y2 ]
+
+        fig.append_trace(Scatter(x=[1,2,3], y=[2,1,2]), 1, 1)
+        fig.append_trace(Scatter(x=[1,2,3], y=[2,1,2]), 2, 1)
+
+        Arguments:
+
+        trace (plotly trace object):
+            The data trace to be bound.
+
+        row (int):
+            Subplot row index on the subplot grid (see Figure.print_grid)
+
+        col (int):
+            Subplot column index on the subplot grid (see Figure.print_grid)
+
+        """
+        try:
+            grid_ref = self._grid_ref
+        except KeyError:
+            raise Exception("In order to use Figure.append_trace, "
+                            "you must first use plotly.tools.make_subplots "
+                            "to create a subplot grid.")
+        if row <= 0:
+            raise Exception("Row value is out of range. "
+                            "Note: the starting cell is (1, 1)")
+        if col <= 0:
+            raise Exception("Col value is out of range. "
+                            "Note: the starting cell is (1, 1)")
+        try:
+            ref = grid_ref[row-1][col-1]
+        except IndexError:
+            raise Exception("The (row, col) pair sent is out of range. "
+                            "Use Figure.print_grid to view the subplot grid. ")
+        if 'scene' in ref[0]:
+            trace['scene'] = ref[0]
+            if ref[0] not in self['layout']:
+                raise Exception("Something went wrong. "
+                                "The scene object for ({r},{c}) subplot cell "
+                                "got deleted.".format(r=row, c=col))
+        else:
+            xaxis_key = "xaxis{ref}".format(ref=ref[0][1:])
+            yaxis_key = "yaxis{ref}".format(ref=ref[1][1:])
+            if (xaxis_key not in self['layout']
+                    or yaxis_key not in self['layout']):
+                raise Exception("Something went wrong. "
+                                "An axis object for ({r},{c}) subplot cell "
+                                "got deleted.".format(r=row, c=col))
+            trace['xaxis'] = ref[0]
+            trace['yaxis'] = ref[1]
+        self['data'] += [trace]
+    Figure.append_trace = append_trace
+
     return Figure
 
 Figure = get_patched_figure_class(Figure)

plotly/graph_reference/graph_objs_meta.json

@@ -1586,9 +1586,9 @@
             }, 
             "scene": {
                 "key_type": "plot_info", 
-                "val_types": "'s1' | 's2' | 's3' | etc.", 
+                "val_types": "'scene1' | 'scene2' | 'scene3' | etc.", 
                 "required": false, 
-                "description": "This key determines the scene on which this trace will be plotted in. More info coming soon."
+                "description": "This key determines the scene on which this trace will be plotted in."
             }, 
             "stream": {
                 "key_type": "object", 
@@ -1657,9 +1657,9 @@
             }, 
             "scene": {
                 "key_type": "plot_info", 
-                "val_types": "'s1' | 's2' | 's3' | etc.", 
+                "val_types": "'scene1' | 'scene2' | 'scene3' | etc.", 
                 "required": false, 
-                "description": "This key determines the scene on which this trace will be plotted in. More info coming soon."
+                "description": "This key determines the scene on which this trace will be plotted in."
             }, 
             "stream": {
                 "key_type": "object", 
@@ -3317,6 +3317,16 @@
                 ], 
                 "description": "Sets the camera position with respect to the scene. The first entry (a list or 1d numpy array of length 4) sets the angular position of the camera. The second entry (a list or 1d numpy array of length 3) sets the (x,y,z) translation of the camera. The third entry (a scalar) sets zoom of the camera."
             }, 
+            "domain": {
+                "key_type": "plot_info", 
+                "val_types": "domain dictionary", 
+                "required": false, 
+                "examples": [
+                    "{'x': [0, 0.4], 'y': [0.6, 1]}", 
+                    "dict(x=[0, 0.4], y=[0.6, 1])"
+                ], 
+                "description": "Sets the x-y domain of this scene on the plotting surface."
+            }, 
             "bgcolor": {
                 "key_type": "style", 
                 "val_types": "a string describing color", 

plotly/tests/test_core/test_graph_objs/test_append_trace.py

@@ -0,0 +1,176 @@
+import plotly
+from plotly.graph_objs import *
+import plotly.tools as tls
+from nose.tools import raises
+
+
+@raises(Exception)
+def test_print_grid_before_make_subplots():
+    fig.print_grid()
+
+@raises(Exception)
+def test_append_trace_before_make_subplots():
+    trace = Scatter(
+           x=[1,2,3],
+           y=[2,3,4]
+    )
+    fig.append_trace(trace, 2, 2)
+
+@raises(Exception)
+def test_append_trace_row_out_of_range():
+    trace = Scatter(
+           x=[1,2,3],
+           y=[2,3,4]
+    )
+    fig = tls.make_subplots(rows=2, cols=3)
+    fig.append_trace(trace, 10, 2)
+
+@raises(Exception)
+def test_append_trace_col_out_of_range():
+    trace = Scatter(
+           x=[1,2,3],
+           y=[2,3,4]
+    )
+    fig = tls.make_subplots(rows=2, cols=3)
+    fig.append_trace(trace, 2, 0)
+
+def test_append_scatter():
+    expected = Figure(
+        data=Data([
+            Scatter(
+                x=[1, 2, 3],
+                y=[2, 3, 4],
+                xaxis='x5',
+                yaxis='y5'
+            )
+        ]),
+        layout=Layout(
+            xaxis1=XAxis(
+                domain=[0.0, 0.2888888888888889],
+                anchor='y1'
+            ),
+            xaxis2=XAxis(
+                domain=[0.35555555555555557, 0.6444444444444445],
+                anchor='y2'
+            ),
+            xaxis3=XAxis(
+                domain=[0.7111111111111111, 1.0],
+                anchor='y3'
+            ),
+            xaxis4=XAxis(
+                domain=[0.0, 0.2888888888888889],
+                anchor='y4'
+            ),
+            xaxis5=XAxis(
+                domain=[0.35555555555555557, 0.6444444444444445],
+                anchor='y5'
+            ),
+            xaxis6=XAxis(
+                domain=[0.7111111111111111, 1.0],
+                anchor='y6'
+            ),
+            yaxis1=YAxis(
+                domain=[0.575, 1.0],
+                anchor='x1'
+            ),
+            yaxis2=YAxis(
+                domain=[0.575, 1.0],
+                anchor='x2'
+            ),
+            yaxis3=YAxis(
+                domain=[0.575, 1.0],
+                anchor='x3'
+            ),
+            yaxis4=YAxis(
+                domain=[0.0, 0.425],
+                anchor='x4'
+            ),
+            yaxis5=YAxis(
+                domain=[0.0, 0.425],
+                anchor='x5'
+            ),
+            yaxis6=YAxis(
+                domain=[0.0, 0.425],
+                anchor='x6'
+            )
+        )
+    )
+
+    trace = Scatter(
+           x=[1,2,3],
+           y=[2,3,4]
+    )
+    fig = tls.make_subplots(rows=2, cols=3)
+    fig.append_trace(trace, 2, 2)
+    assert fig == expected
+
+@raises(Exception)
+def test_append_scatter_after_deleting_xaxis():
+    trace = Scatter(
+           x=[1,2,3],
+           y=[2,3,4]
+    )
+    fig = tls.make_subplots(rows=2, cols=3)
+    fig['layout'].pop('xaxis5', None)
+    fig.append_trace(trace, 2, 2)
+
+@raises(Exception)
+def test_append_scatter_after_deleting_yaxis():
+    trace = Scatter(
+           x=[1,2,3],
+           y=[2,3,4]
+    )
+    fig = tls.make_subplots(rows=2, cols=3)
+    fig['layout'].pop('yaxis5', None)
+    fig.append_trace(trace, 2, 2)
+
+def test_append_scatter3d():
+    expected = Figure(
+        data=Data([
+            Scatter3d(
+                x=[1, 2, 3],
+                y=[2, 3, 4],
+                z=[1, 2, 3],
+                scene='scene2'
+            ),
+            Scatter3d(
+                x=[1, 2, 3],
+                y=[2, 3, 4],
+                z=[1, 2, 3],
+                scene='scene2'
+            )
+        ]),
+        layout=Layout(
+            scene1=Scene(
+                domain={'y': [0.575, 1.0], 'x': [0.0, 1.0]}
+            ),
+            scene2=Scene(
+                domain={'y': [0.0, 0.425], 'x': [0.0, 1.0]}
+            )
+        )
+    )
+
+    fig = tls.make_subplots(rows=2, cols=1,
+                            specs=[[{'is_3d': True}], 
+                                   [{'is_3d': True}]])
+    trace = Scatter3d(
+           x=[1,2,3],
+           y=[2,3,4],
+           z=[1,2,3]
+    )
+    fig.append_trace(trace, 1, 1)
+    fig.append_trace(trace, 2, 1)
+    assert fig == expected
+
+@raises(Exception)
+def test_append_scatter3d_after_deleting_scene():
+    fig = tls.make_subplots(rows=2, cols=1,
+                            specs=[[{'is_3d': True}], 
+                                   [{'is_3d': True}]])
+    trace = Scatter3d(
+           x=[1,2,3],
+           y=[2,3,4],
+           z=[1,2,3]
+    )
+    fig['layout'].pop('scene1', None)
+    fig.append_trace(trace, 1, 1)