Feature: figure semantic legends

docs/colorbars_legends.py

@@ -477,13 +477,19 @@
 #
 # Legends usually annotate artists already drawn on an axes, but sometimes you need
 # standalone semantic keys (categories, size scales, color levels, or geometry types).
-# UltraPlot provides helper methods that build these entries directly:
+# UltraPlot provides helper methods that build these entries directly on both
+# axes and figures:
 #
 # * :meth:`~ultraplot.axes.Axes.entrylegend`
 # * :meth:`~ultraplot.axes.Axes.catlegend`
 # * :meth:`~ultraplot.axes.Axes.sizelegend`
 # * :meth:`~ultraplot.axes.Axes.numlegend`
 # * :meth:`~ultraplot.axes.Axes.geolegend`
+# * :meth:`~ultraplot.figure.Figure.entrylegend`
+# * :meth:`~ultraplot.figure.Figure.catlegend`
+# * :meth:`~ultraplot.figure.Figure.sizelegend`
+# * :meth:`~ultraplot.figure.Figure.numlegend`
+# * :meth:`~ultraplot.figure.Figure.geolegend`
 #
 # These helpers are useful whenever the legend should describe an encoding rather than
 # mirror artists that already happen to be drawn. In practice there are two distinct
@@ -513,7 +519,8 @@
 #
 # The helpers are intentionally composable. Each one accepts ``add=False`` and returns
 # ``(handles, labels)`` so you can merge semantic sections and pass the result through
-# :meth:`~ultraplot.axes.Axes.legend` yourself.
+# :meth:`~ultraplot.axes.Axes.legend` or :meth:`~ultraplot.figure.Figure.legend`
+# yourself.
 #
 # .. code-block:: python
 #
@@ -568,6 +575,27 @@
 #
 # .. code-block:: python
 #
+#    # Add semantic legends around an entire subplot group.
+#    fig, axs = uplt.subplots(ncols=2)
+#    fig.catlegend(
+#        ["Control", "Treatment"],
+#        colors={"Control": "blue7", "Treatment": "red7"},
+#        markers={"Control": "o", "Treatment": "^"},
+#        ref=axs,
+#        loc="b",
+#        title="Group",
+#    )
+#    fig.sizelegend(
+#        [10, 50, 200],
+#        labels=["Small", "Medium", "Large"],
+#        color="gray6",
+#        ref=axs,
+#        loc="r",
+#        title="Population",
+#    )
+#
+# .. code-block:: python
+#
 #    # Compose multiple semantic helpers into one legend.
 #    size_handles, size_labels = ax.sizelegend(
 #        [10, 50, 200],
@@ -685,6 +713,32 @@
 ax.axis("off")
 
 
+# %%
+fig, axs = uplt.subplots(ncols=2, refwidth=2.8, share=False)
+axs[0].scatter([0, 1, 2], [3, 1, 2], c=[0.2, 0.5, 0.8], s=[40, 120, 260])
+axs[1].scatter([0, 1, 2], [2, 3, 1], c=[0.8, 0.4, 0.1], s=[60, 90, 220])
+axs.format(title="Figure semantic legend helpers", grid=False)
+
+fig.catlegend(
+    ["Control", "Treatment"],
+    colors={"Control": "blue7", "Treatment": "red7"},
+    markers={"Control": "o", "Treatment": "^"},
+    ref=axs,
+    loc="bottom",
+    title="Group",
+    frameon=False,
+)
+fig.sizelegend(
+    [40, 120, 260],
+    labels=["Small", "Medium", "Large"],
+    color="gray6",
+    ref=axs,
+    loc="right",
+    title="Size scale",
+    frameon=False,
+)
+
+
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_guides_decouple:
 #

docs/examples/legends_colorbars/03_semantic_legends.py

@@ -6,12 +6,12 @@
 
 Why UltraPlot here?
 -------------------
-UltraPlot adds semantic legend helpers directly on axes:
+UltraPlot adds semantic legend helpers on both axes and figures:
 ``entrylegend``, ``catlegend``, ``sizelegend``, ``numlegend``, and ``geolegend``.
 These are useful when you want legend meaning decoupled from plotted handles, or
 when you want a standalone semantic key that describes an encoding directly.
 
-Key functions: :py:meth:`ultraplot.axes.Axes.entrylegend`, :py:meth:`ultraplot.axes.Axes.catlegend`, :py:meth:`ultraplot.axes.Axes.sizelegend`, :py:meth:`ultraplot.axes.Axes.numlegend`, :py:meth:`ultraplot.axes.Axes.geolegend`.
+Key functions: :py:meth:`ultraplot.axes.Axes.entrylegend`, :py:meth:`ultraplot.axes.Axes.catlegend`, :py:meth:`ultraplot.axes.Axes.sizelegend`, :py:meth:`ultraplot.axes.Axes.numlegend`, :py:meth:`ultraplot.axes.Axes.geolegend`, :py:meth:`ultraplot.figure.Figure.entrylegend`, :py:meth:`ultraplot.figure.Figure.catlegend`, :py:meth:`ultraplot.figure.Figure.sizelegend`, :py:meth:`ultraplot.figure.Figure.numlegend`, :py:meth:`ultraplot.figure.Figure.geolegend`.
 
 See also
 --------
@@ -106,3 +106,29 @@
 )
 ax.axis("off")
 fig.show()
+
+# %%
+fig, axs = uplt.subplots(ncols=2, refwidth=2.8, share=False)
+axs[0].scatter([0, 1, 2], [3, 1, 2], c=[0.2, 0.5, 0.8], s=[40, 120, 260])
+axs[1].scatter([0, 1, 2], [2, 3, 1], c=[0.8, 0.4, 0.1], s=[60, 90, 220])
+axs.format(title="Figure semantic legend helpers")
+
+fig.catlegend(
+    ["Control", "Treatment"],
+    colors={"Control": "blue7", "Treatment": "red7"},
+    markers={"Control": "o", "Treatment": "^"},
+    ref=axs,
+    loc="bottom",
+    title="Group",
+    frameon=False,
+)
+fig.sizelegend(
+    [40, 120, 260],
+    labels=["Small", "Medium", "Large"],
+    color="gray6",
+    ref=axs,
+    loc="right",
+    title="Size scale",
+    frameon=False,
+)
+fig.show()