Feb 26, 2025 · Feb 23, 2025 · Feb 26, 2025 · Feb 25, 2025 · Feb 26, 2025 · Feb 25, 2025
diff --git a/galleries/examples/lines_bars_and_markers/scatter_hist.py b/galleries/examples/lines_bars_and_markers/scatter_hist.py
 Scatter plot with histograms
 ============================

 Show the marginal distributions of a scatter plot as histograms at the sides of
 the plot.
 Add histograms to the x-axes and y-axes margins of a scatter plot.

 This layout features a central scatter plot illustrating the relationship
 between x and y, a histogram at the top displaying the distribution of x, and a
 histogram on the right showing the distribution of y.

 For a nice alignment of the main Axes with the marginals, two options are shown
 below:
 While `.Axes.inset_axes` may be a bit more complex, it allows correct handling
 of main Axes with a fixed aspect ratio.

 An alternative method to produce a similar figure using the ``axes_grid1``
 toolkit is shown in the :doc:`/gallery/axes_grid1/scatter_hist_locatable_axes`
 example.  Finally, it is also possible to position all Axes in absolute
 coordinates using `.Figure.add_axes` (not shown here).

 Let us first define a function that takes x and y data as input, as well
 as three Axes, the main Axes for the scatter, and two marginal Axes. It will
 then create the scatter and histograms inside the provided Axes.
 Let us first define a function that takes x and y data as input, as well as
 three Axes, the main Axes for the scatter, and two marginal Axes. It will then
 create the scatter and histograms inside the provided Axes.
 """

 import matplotlib.pyplot as plt


 # %%
 # Defining the Axes positions using subplot_mosaic
 # ------------------------------------------------
 #
 # Defining the Axes positions using a gridspec
 # --------------------------------------------
 #
 # We define a gridspec with unequal width- and height-ratios to achieve desired
 # layout.  Also see the :ref:`arranging_axes` tutorial.

 # Start with a square Figure.
 fig = plt.figure(figsize=(6, 6))
 # Add a gridspec with two rows and two columns and a ratio of 1 to 4 between
 # the size of the marginal Axes and the main Axes in both directions.
 # Also adjust the subplot parameters for a square plot.
 gs = fig.add_gridspec(2, 2,  width_ratios=(4, 1), height_ratios=(1, 4),
                      left=0.1, right=0.9, bottom=0.1, top=0.9,
                      wspace=0.05, hspace=0.05)
 # Create the Axes.
 ax = fig.add_subplot(gs[1, 0])
 ax_histx = fig.add_subplot(gs[0, 0], sharex=ax)
 ax_histy = fig.add_subplot(gs[1, 1], sharey=ax)
 # Draw the scatter plot and marginals.
 scatter_hist(x, y, ax, ax_histx, ax_histy)
 # We use the `~.pyplot.subplot_mosaic` function to define the positions and
 # names of the three axes; the empty axes is specified by ``'.'``.  We manually
 # specify the size of the figure, and can make the different axes have
 # different sizes by specifying the *width_ratios* and *height_ratios*
 # arguments. The *layout* argument is set to ``'constrained'`` to optimize the
 # spacing between the axes.

 fig, axs = plt.subplot_mosaic([['histx', '.'],
                               ['scatter', 'histy']],
                              figsize=(6, 6),
                              width_ratios=(4, 1), height_ratios=(1, 4),
                              layout='constrained')
 scatter_hist(x, y, axs['scatter'], axs['histx'], axs['histy'])


 # %%

 # %%
 #
 # While we recommend using one of the two methods described above, there are
 # number of other ways to achieve a similar layout:
 #
 # - The Axes can be positioned manually in relative coordinates using
 #   `~matplotlib.figure.Figure.add_axes`.
 # - A gridspec can be used to create the layout
 #   (`~matplotlib.figure.Figure.add_gridspec`) and adding only the three desired
 #   axes (`~matplotlib.figure.Figure.add_subplot`).
 # - Four subplots can be created  using `~.pyplot.subplots`,  and the unused
 #   axes in the upper right can be removed manually.
 # - The ``axes_grid1`` toolkit can be used, as shown in
 #   :doc:`/gallery/axes_grid1/scatter_hist_locatable_axes`.
 #
 # .. admonition:: References
 #
 #    The use of the following functions, methods, classes and modules is shown
 #    in this example:
 #
 #    - `matplotlib.figure.Figure.subplot_mosaic`
 #    - `matplotlib.pyplot.subplot_mosaic`
 #    - `matplotlib.figure.Figure.add_subplot`
 #    - `matplotlib.figure.Figure.add_gridspec`
 #    - `matplotlib.axes.Axes.inset_axes`
 #    - `matplotlib.axes.Axes.scatter`
 #    - `matplotlib.axes.Axes.hist`