DOC

jklymak · jklymak · commit 96ff8f073163 · 2020-10-10T08:00:07.000-07:00
diff --git a/doc/users/next_whats_new/suplabels.rst b/doc/users/next_whats_new/suplabels.rst
@@ -0,0 +1,18 @@
+suplabelx and suplabely
+-----------------------
+
+It is possible to add x and ylabels to a whole figure, analogous to
+`.FigureBase.suptitle` using the new `.FigureBase.supxlabel` and
+`.FigureBase.supylabel` methods.
+
+.. plot::
+
+  fig, axs = plt.subplots(3, 2, figsize=(5, 5), constrained_layout=True,
+                          sharey=True, sharex=True)
+
+  for nn, ax in enumerate(axs.flat):
+      ax.set_title(f'Channel {nn}')
+      ax.plot(np.cumsum(np.random.randn(50)))
+
+  fig.supxlabel('Time [s]')
+  fig.supylabel('Data [V]')
diff --git a/examples/subplots_axes_and_figures/figure_title.py b/examples/subplots_axes_and_figures/figure_title.py
@@ -1,12 +1,16 @@
 """
-============
-Figure title
-============
+=============================================
+Figure labels: suptitle, supxlabel, supylabel
+=============================================
 
-Each subplot can have its own title (`.Axes.set_title`). Additionally,
-`.Figure.suptitle` adds a centered title at the top of the figure.
+Often it is desirable to have a title for a figure, while each subplot gets
+its own title using `.FigureBase.suptitle`.
+
+We can also add figure-level supxlabel and supylabel
 """
+from matplotlib.cbook import get_sample_data
 import matplotlib.pyplot as plt
+
 import numpy as np
 
 
@@ -24,4 +28,36 @@
 
 fig.suptitle('Different types of oscillations', fontsize=16)
 
+##############################################################################
+# Note it is also sometimes useful to have a global x- or y-label, which
+# can be achieved with the `.FigureBase.supxlabel` and `.FigureBase.supylabel`
+# methods.
+
+fig, axs = plt.subplots(3, 5, figsize=(8, 5), constrained_layout=True,
+                        sharey=True, sharex=True)
+
+fname = get_sample_data('percent_bachelors_degrees_women_usa.csv',
+                        asfileobj=False)
+gender_degree_data = np.genfromtxt(fname, delimiter=',', names=True)
+
+majors = ['Health Professions', 'Public Administration', 'Education',
+          'Psychology', 'Foreign Languages', 'English',
+          'Art and Performance', 'Biology',
+          'Agriculture', 'Business',
+          'Math and Statistics', 'Architecture', 'Physical Sciences',
+          'Computer Science', 'Engineering']
+
+for nn, ax in enumerate(axs.flat):
+    ax.set_xlim(1969.5, 2011.1)
+    column = majors[nn]
+    column_rec_name = column.replace('\n', '_').replace(' ', '_')
+
+    line, = ax.plot('Year', column_rec_name, data=gender_degree_data,
+                    lw=2.5)
+    ax.set_title(column, fontsize='small', loc='left')
+    ax.set_ylim([0, 100])
+    ax.grid()
+fig.supxlabel('Year')
+fig.supylabel('Percent Degrees Awarded To Women')
+
 plt.show()
