adding subplot titles to make_subplots

Adds titles to subplots and insets.
@chriddyp @theengineear @etpinard @aneda @jackparmer

Author: cldougl

plotly/tools.py

@@ -630,6 +630,9 @@ def make_subplots(rows=1, cols=1,
         Space between subplot rows.
         Applies to all rows (use 'specs' subplot-dependents spacing)
 
+    subplot_titles (kwarg, list of strings, default=empty list):
+        Title of each subplot.
+
     specs (kwarg, list of lists of dictionaries):
         Subplot specifications.
 
@@ -719,7 +722,7 @@ def make_subplots(rows=1, cols=1,
 
     # Throw exception if non-valid kwarg is sent
     VALID_KWARGS = ['horizontal_spacing', 'vertical_spacing',
-                    'specs', 'insets']
+                    'specs', 'insets', 'subplot_titles']
     for key in kwargs.keys():
         if key not in VALID_KWARGS:
             raise Exception("Invalid keyword argument: '{0}'".format(key))
@@ -734,6 +737,12 @@ def make_subplots(rows=1, cols=1,
     except KeyError:
         vertical_spacing = 0.3 / rows
 
+    # Set 'subplot_titles'
+    try:
+        subplot_titles = kwargs['subplot_titles']
+    except KeyError:
+        subplot_titles = [""]*rows*cols
+
     # Sanitize 'specs' (must be a list of lists)
     exception_msg = "Keyword argument 'specs' must be a list of lists"
     try:
@@ -906,6 +915,8 @@ def _get_anchors(r, c, x_cnt, y_cnt, shared_xaxes, shared_yaxes):
 
         return x_anchor, y_anchor
 
+    list_of_domains = []  # added for subplot titles
+
     # Function pasting x/y domains in layout object (2d case)
     def _add_domain(layout, x_or_y, label, ___domain, anchor, position):
         name = label[0] + 'axis' + label[1:]
@@ -916,11 +927,13 @@ def _add_domain(layout, x_or_y, label, ___domain, anchor, position):
         if isinstance(position, float):
             axis['position'] = position
         layout[name] = axis
+        list_of_domains.append(___domain)  # added for subplot titles
 
     # Function pasting x/y domains in layout object (3d case)
     def _add_domain_is_3d(layout, s_label, x_domain, y_domain):
         scene = graph_objs.Scene(___domain={'x': x_domain, 'y': y_domain})
         layout[s_label] = scene
+        list_of_domains.append(___domain)  # added for subplot titles
 
     x_cnt = y_cnt = s_cnt = 1  # subplot axis/scene counters
 
@@ -1129,6 +1142,34 @@ def _pad(s, cell_len=cell_len):
                 s_str + _get_cell_str(r, c, ref) + e_str + '\n'
             )
 
+    # Add subplot titles
+    x_dom = list_of_domains[::2]
+    y_dom = list_of_domains[1::2]
+
+    subtitle_pos_x = []
+    for index in range(len(x_dom)):
+        subtitle_pos_x.append(((x_dom[index][1])-(x_dom[index][0]))/2 +
+                              x_dom[index][0])
+
+    subtitle_pos_y = []
+    for index in range(len(y_dom)):
+        subtitle_pos_y.append(y_dom[index][1])
+
+    plot_titles = []
+    for index in range(len(x_dom)):
+        plot_titles.append({'y': subtitle_pos_y[index],
+                            'xref': 'paper',
+                            'x': subtitle_pos_x[index],
+                            'yref': 'paper',
+                            'text': subplot_titles[index],
+                            'showarrow': False,
+                            'font': Font(size=18),
+                            'xanchor': 'center',
+                            'yanchor': 'bottom'
+                            })
+
+    layout['annotations'] = plot_titles
+
     if print_grid:
         print(grid_str)