From 7e00b466367886888782c9aeba35a34dcc4b3f71 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Mon, 31 Jul 2023 01:50:30 +0200 Subject: [PATCH] DOC: Add overview of axes creation methods Closes #17376. There might still be room for further improvements, be it description or formatting. But I would like to leave that for later. The main goal is to get a first version of this in soon. --- .../users_explain/axes/axes_creation.rst | 99 +++++++++++++++++++ galleries/users_explain/axes/index.rst | 2 + 2 files changed, 101 insertions(+) create mode 100644 galleries/users_explain/axes/axes_creation.rst diff --git a/galleries/users_explain/axes/axes_creation.rst b/galleries/users_explain/axes/axes_creation.rst new file mode 100644 index 000000000000..b0dbbe47062c --- /dev/null +++ b/galleries/users_explain/axes/axes_creation.rst @@ -0,0 +1,99 @@ +################################# +Overview of Axes creation methods +################################# + +Depending on the use case, different methods for creating an Axes are most useful. +The following diagram gives an overview by characterizing the desired Axes. + +Additionally, most of the methods come in two flavors: A `.pyplot` function and a +method on a `.Figure` or `~.axes.Axes`. + +``plt.subplots()`` and ``plt.subplot_mosaic()`` return a Figure and one or more Axes. +They are the most common stating points for a Matplotlib plot. All other methods +only return an Axes. + +.. graphviz:: + + digraph { + node[shape=diamond, width=2.7, height=0.8] + q_fullsize; q_regular_grid; q_general_grid; q_inset; q_twin; + node[shape=none, margin=0] + full_size; + + legend [label=< + + + +
pyplot functionsFigure/Axes methods
less used variants
>] + + + q_fullsize [label="full size?"] + full_size [label=< + + + +
plt.subplots()Figure.subplots()
plt.subplot()Figure.add_subplot()
>] + q_regular_grid [label="regular grid?"] + regular_grid [label=< + + + +
plt.subplots(n, m)Figure.subplots(n, m)
plt.subplot(n, m, k)Figure.add_subplot(n, m, k)
>] + q_general_grid [label="general grid?"] + general_grid [label=< + + + + + +
plt.subplot_mosaic()Figure.subplot_mosaic()
plt.subplot2grid()GridSpec.subplots()
plt.subplots(gridspec_kw)Figure.subplots(gridspec_kw)
plt.subplot(subplotspec)Figure.subplot(subplotspec)
>] + q_inset [label="inset?"] + inset [label=< + + +
Axes.inset_axes()
>] + q_twin [label="twin?"] + twin [label=< + + + +
plt.twinx()Axes.twinx()
plt.twiny()Axes.twiny()
>] + axes [label=< + + +
plt.axes()Figure.add_axes()
>] + + legend -> full_size [ style = invis ]; + + q_fullsize -> q_regular_grid [ label = "No" ]; + q_regular_grid -> q_general_grid [label = "No" ]; + q_fullsize -> full_size [ label = "Yes" ]; + q_regular_grid -> regular_grid[ label = "Yes" ]; + q_general_grid -> general_grid [label = "Yes"]; + q_general_grid -> q_inset [label = "No"]; + q_inset -> inset[label="Yes"]; + q_inset -> q_twin [label="No"] + q_twin -> twin[label="Yes"] + q_twin -> axes[label="No"] + + { + rank=same; + q_fullsize full_size + } + { + rank=same; + q_regular_grid regular_grid + } + { + rank=same; + q_general_grid general_grid + } + { + rank=same; + q_inset inset + } + { + rank=same; + q_twin twin + } + } diff --git a/galleries/users_explain/axes/index.rst b/galleries/users_explain/axes/index.rst index 3d0a67ca14e7..d254f7809262 100644 --- a/galleries/users_explain/axes/index.rst +++ b/galleries/users_explain/axes/index.rst @@ -29,6 +29,8 @@ annotations like x- and y-labels, titles, and legends. :maxdepth: 2 axes_intro + axes_creation + .. toctree:: :maxdepth: 1