Add examples

ZachDaChampion · ZachDaChampion · commit cb55d34dbbfa · 2023-04-04T12:46:09.000-04:00
diff --git a/galleries/examples/subplots_axes_and_figures/secondary_axis.py b/galleries/examples/subplots_axes_and_figures/secondary_axis.py
@@ -40,6 +40,26 @@ def rad2deg(x):
 secax.set_xlabel('angle [rad]')
 plt.show()
 
+# %%
+# Normally, secondary axes are placed at either the 'top' or 'bottom'
+# of the plot. We can also pass a custom transform to the axis and
+# draw it relative to that transform. Here, we draw an axis at Y = 0
+# in our data.
+
+fig, ax = plt.subplots(layout='constrained')
+x = np.arange(0, 10)
+np.random.seed(34)
+y = np.random.randn(len(x))
+ax.plot(x, y)
+ax.set_xlabel('X')
+ax.set_ylabel('Y')
+ax.set_title('Random data')
+
+# Pass ax.transData as a transform to place the axis relative to our data
+secax = ax.secondary_xaxis(0, transform=ax.transData)
+secax.set_xlabel('Axis at Y = 0')
+plt.show()
+
 # %%
 # Here is the case of converting from wavenumber to wavelength in a
 # log-log scale.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -581,6 +581,18 @@ def invert(x):
             secax = ax.secondary_xaxis('top', functions=(invert, invert))
             secax.set_xlabel('Period [s]')
             plt.show()
+
+        To add a secondary axis relative to your data, you can pass a transform
+        to the new axis.
+
+        .. plot::
+
+            fig, ax = plt.subplots()
+            ax.plot(range(0, 5), range(-1, 4))
+
+            # Pass 'ax.transData' as a transform to place the axis
+            # relative to your data at y=0
+            secax = ax.secondary_xaxis(0, transform=ax.transData)
         """
         if not (location in ['top', 'bottom'] or isinstance(location, Real)):
             raise ValueError('secondary_xaxis location must be either '
