Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit dd74cd0

Browse files
cvanelterencvanelteren
authored
Feature: figure semantic legends (#707)
* expose semantic legend to figure * Add documentation
1 parent d9b3af6 commit dd74cd0

4 files changed

Lines changed: 522 additions & 4 deletions

File tree

‎docs/colorbars_legends.py‎

Lines changed: 56 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -477,13 +477,19 @@
477477
#
478478
# Legends usually annotate artists already drawn on an axes, but sometimes you need
479479
# standalone semantic keys (categories, size scales, color levels, or geometry types).
480-
# UltraPlot provides helper methods that build these entries directly:
480+
# UltraPlot provides helper methods that build these entries directly on both
481+
# axes and figures:
481482
#
482483
# * :meth:`~ultraplot.axes.Axes.entrylegend`
483484
# * :meth:`~ultraplot.axes.Axes.catlegend`
484485
# * :meth:`~ultraplot.axes.Axes.sizelegend`
485486
# * :meth:`~ultraplot.axes.Axes.numlegend`
486487
# * :meth:`~ultraplot.axes.Axes.geolegend`
488+
# * :meth:`~ultraplot.figure.Figure.entrylegend`
489+
# * :meth:`~ultraplot.figure.Figure.catlegend`
490+
# * :meth:`~ultraplot.figure.Figure.sizelegend`
491+
# * :meth:`~ultraplot.figure.Figure.numlegend`
492+
# * :meth:`~ultraplot.figure.Figure.geolegend`
487493
#
488494
# These helpers are useful whenever the legend should describe an encoding rather than
489495
# mirror artists that already happen to be drawn. In practice there are two distinct
@@ -513,7 +519,8 @@
513519
#
514520
# The helpers are intentionally composable. Each one accepts ``add=False`` and returns
515521
# ``(handles, labels)`` so you can merge semantic sections and pass the result through
516-
# :meth:`~ultraplot.axes.Axes.legend` yourself.
522+
# :meth:`~ultraplot.axes.Axes.legend` or :meth:`~ultraplot.figure.Figure.legend`
523+
# yourself.
517524
#
518525
# .. code-block:: python
519526
#
@@ -568,6 +575,27 @@
568575
#
569576
# .. code-block:: python
570577
#
578+
# # Add semantic legends around an entire subplot group.
579+
# fig, axs = uplt.subplots(ncols=2)
580+
# fig.catlegend(
581+
# ["Control", "Treatment"],
582+
# colors={"Control": "blue7", "Treatment": "red7"},
583+
# markers={"Control": "o", "Treatment": "^"},
584+
# ref=axs,
585+
# loc="b",
586+
# title="Group",
587+
# )
588+
# fig.sizelegend(
589+
# [10, 50, 200],
590+
# labels=["Small", "Medium", "Large"],
591+
# color="gray6",
592+
# ref=axs,
593+
# loc="r",
594+
# title="Population",
595+
# )
596+
#
597+
# .. code-block:: python
598+
#
571599
# # Compose multiple semantic helpers into one legend.
572600
# size_handles, size_labels = ax.sizelegend(
573601
# [10, 50, 200],
@@ -685,6 +713,32 @@
685713
ax.axis("off")
686714

687715

716+
# %%
717+
fig, axs = uplt.subplots(ncols=2, refwidth=2.8, share=False)
718+
axs[0].scatter([0, 1, 2], [3, 1, 2], c=[0.2, 0.5, 0.8], s=[40, 120, 260])
719+
axs[1].scatter([0, 1, 2], [2, 3, 1], c=[0.8, 0.4, 0.1], s=[60, 90, 220])
720+
axs.format(title="Figure semantic legend helpers", grid=False)
721+
722+
fig.catlegend(
723+
["Control", "Treatment"],
724+
colors={"Control": "blue7", "Treatment": "red7"},
725+
markers={"Control": "o", "Treatment": "^"},
726+
ref=axs,
727+
loc="bottom",
728+
title="Group",
729+
frameon=False,
730+
)
731+
fig.sizelegend(
732+
[40, 120, 260],
733+
labels=["Small", "Medium", "Large"],
734+
color="gray6",
735+
ref=axs,
736+
loc="right",
737+
title="Size scale",
738+
frameon=False,
739+
)
740+
741+
688742
# %% [raw] raw_mimetype="text/restructuredtext"
689743
# .. _ug_guides_decouple:
690744
#

‎docs/examples/legends_colorbars/03_semantic_legends.py‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,12 @@
66
77
Why UltraPlot here?
88
-------------------
9-
UltraPlot adds semantic legend helpers directly on axes:
9+
UltraPlot adds semantic legend helpers on both axes and figures:
1010
``entrylegend``, ``catlegend``, ``sizelegend``, ``numlegend``, and ``geolegend``.
1111
These are useful when you want legend meaning decoupled from plotted handles, or
1212
when you want a standalone semantic key that describes an encoding directly.
1313
14-
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`.
14+
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`.
1515
1616
See also
1717
--------
@@ -106,3 +106,29 @@
106106
)
107107
ax.axis("off")
108108
fig.show()
109+
110+
# %%
111+
fig, axs = uplt.subplots(ncols=2, refwidth=2.8, share=False)
112+
axs[0].scatter([0, 1, 2], [3, 1, 2], c=[0.2, 0.5, 0.8], s=[40, 120, 260])
113+
axs[1].scatter([0, 1, 2], [2, 3, 1], c=[0.8, 0.4, 0.1], s=[60, 90, 220])
114+
axs.format(title="Figure semantic legend helpers")
115+
116+
fig.catlegend(
117+
["Control", "Treatment"],
118+
colors={"Control": "blue7", "Treatment": "red7"},
119+
markers={"Control": "o", "Treatment": "^"},
120+
ref=axs,
121+
loc="bottom",
122+
title="Group",
123+
frameon=False,
124+
)
125+
fig.sizelegend(
126+
[40, 120, 260],
127+
labels=["Small", "Medium", "Large"],
128+
color="gray6",
129+
ref=axs,
130+
loc="right",
131+
title="Size scale",
132+
frameon=False,
133+
)
134+
fig.show()

0 commit comments

Comments
 (0)