Create explict rename legend entry section in guide

story645 · rcomer · story645 · commit 9e63be358966 · 2024-02-01T15:26:18.000-05:00
Co-authored-by: Ruth Comer &lt;10599679+rcomer@users.noreply.github.com&gt;
diff --git a/galleries/users_explain/axes/legend_guide.py b/galleries/users_explain/axes/legend_guide.py
@@ -59,6 +59,9 @@
     line_down, = ax.plot([3, 2, 1], label='Line 1')
     ax.legend(handles=[line_up, line_down])
 
+Renaming legend entries
+-----------------------
+
 In the rare case where the labels cannot directly be set on the handles, they
 can also be directly passed to :func:`legend`::
 
@@ -68,6 +71,17 @@
     ax.legend([line_up, line_down], ['Line Up', 'Line Down'])
 
 
+If the handles are not directly accessible, for example when using some
+`Third-party packages <https://matplotlib.org/mpl-third-party/>`_, they can be accessed
+as follows. Here we use a dictionary to ensure that we rename the correct entry::
+
+    my_map = {'Line Up':'Up', 'Line Down':'Down'}
+
+    handles, labels = ax.get_legend_handles_labels()
+    ax.legend(handles, [my_map[l] for l in labels])
+
+
+
 .. _proxy_legend_handles:
 
 Creating artists specifically for adding to the legend (aka. Proxy artists)
