Allow to reorder legend entries

[michaelgrund]

Description of the desired feature

In a recent Stack Overflow post the question came up if it's possible to reorder the legend entries in PyGMT (see example below, left plot). As far as I know in principle the legend entries follow the order in which the corrsponding fig.plot() calls (including the label definition) take place. However, I made a suggestion using the following workaround (right plot):

import pygmt

region,frame="g","g"
projection = 'G20.5/89.99999/25/4.5i' # yeah that’s the arctic…

# original figure
fig = pygmt.Figure()
fig.coast(projection=projection, region=region, frame=frame, shorelines=True) # plot cost lines

pen=3.9
fig.plot([90, 80, 25, 40], [90, 70, 85, 60], label='"Cruise 1"',pen=('black',pen))
fig.plot([90, 20, 10, 50], [90, 80, 80, 60], label='"Cruise 2"',pen=('green',pen))
fig.plot([90, 30, 30, 10], [90, 80, 70, 60], label='"Cruise 4"',pen=('purple',pen)) # most recent one
fig.plot([90, 80, 30, 10], [80, 80, 80, 60], label='"Cruise 3"',pen=('yellow',pen)) # should be plotted above the other cruises

fig.legend(position='JTL+jTL+o0.2c',box='+gwhite+p1p') 
# should be sorted as: Cruise 1, Cruise 2, Cruise 3, Cruise 4, 
# but is sorted as: Cruise 1, Cruise 2, Cruise 4, Cruise 3

fig.shift_origin(xshift="w+0.5c")

# workaround to fix the problem
fig.coast(projection=projection, region=region, frame=frame, shorelines=True)
fig.plot([90, 80, 25, 40], [90, 70, 85, 60], label='"Cruise 1"',pen=('black',pen))
fig.plot([90, 20, 10, 50], [90, 80, 80, 60], label='"Cruise 2"',pen=('green',pen))
fig.plot([90, 30, 30, 10], [90, 80, 70, 60], pen=('purple',pen)) 
fig.plot([90, 80, 30, 10], [80, 80, 80, 60], label='"Cruise 3"',pen=('yellow',pen)) 

# add dummy entry for legend entry
fig.plot([90, 90], [90, 90], label='"Cruise 4"',pen=('purple',pen)) 

fig.legend(position='JTL+jTL+o0.2c',box='+gwhite+p1p') 
fig.show()

I guess it's not possible to directly implement something like the zorder option in matplotlib.pyplot.plot in PyGMT since the module is connected to GMT's plot function. However, maybe there are some ideas how we could handle that.

Are you willing to help implement and maintain this feature? First discuss

[yvonnefroehlich]

The GMT-specific legend files are a bit dificult for new users. But as PyGMT supports io.stringIO objects since the release v0.14.0, this can be an way to create more complicated legends.

import io
import pygmt

pen = 3.9  # line thickness in points

# Create new Figure instance
fig = pygmt.Figure()

# Create basic map around the North pole with shorelines 
fig.coast(projection="G20.5/89.99/25/4.5i", region="g", frame="g", shorelines=True)

# Plot four cruises in different colors
fig.plot(x=[90, 80, 25, 40], y=[90, 70, 85, 60], pen=f"{pen}p,black")
fig.plot(x=[90, 20, 10, 50], y=[90, 80, 80, 60], pen=f"{pen}p,green")
fig.plot(x=[90, 30, 30, 10], y=[90, 80, 70, 60], pen=f"{pen}p,purple")
fig.plot(x=[90, 80, 30, 10], y=[80, 80, 80, 60], pen=f"{pen}p,yellow")

# Set up an io.StringIO object for storing the legend information and pass it 
# to the spec parameter of Figure.legend()
spec_io = io.StringIO(
"""
S 0.2c - 0.3c - 2p,black 0.5c Cruise 1
S 0.2c - 0.3c - 2p,green 0.5c Cruise 2
S 0.2c - 0.3c - 2p,yellow 0.5c Cruise 3
S 0.2c - 0.3c - 2p,purple 0.5c Cruise 4
"""
)
fig.legend(spec=spec_io)

fig.show()

---

Besides this, the code posted at the beginning is not correct.

Click to show corrected code

import pygmt

pen = 3.9  # line thickness in points

# Create new Figure instance
fig = pygmt.Figure()

# Create basic map around the North pole with shorelines 
fig.coast(projection="G20.5/89.99999/25/4.5i", region="g", frame="g", shorelines=True)

# Plot four cruises in different colors
fig.plot(x=[90, 80, 25, 40], y=[90, 70, 85, 60], pen=f"{pen}p,black", label="Cruise 1")
fig.plot(x=[90, 20, 10, 50], y=[90, 80, 80, 60], pen=f"{pen}p,green", label="Cruise 2")
fig.plot(x=[90, 30, 30, 10], y=[90, 80, 70, 60], pen=f"{pen}p,purple")  # NO label here
fig.plot(x=[90, 80, 30, 10], y=[80, 80, 80, 60], pen=f"{pen}p,yellow", label="Cruise 3")

# Plot dummy entry in the color of cruise 4 here WITH label
fig.plot(x=[90, 90], y=[90, 90], pen=f"{pen}p,purple", label="Cruise 4")

# Add legend in the Top Left corner with a white fill and a black outline
fig.legend(position="JTL+jTL+o0.2c", box="+gwhite+pblack")

fig.show()

[seisman]

I've been thinking about providing a class for customized legend specification. The class will be used like below and can be passed directly to Figure.legend, converted to io.StringIO, or saved to an plaintext file.

spec = LegendSpec()

spec.set_title("Earthquake Catalog", font="12p,1,blue")
spec.set_ncolumns(2)
spec.add_symbol("c", dx=0.2, size="0.4c", fill="red", pen="1p", dx2=0.5, label="Mw 5–6")
spec.add_symbol("c", dx=0.2, size="0.4c", fill="red", pen="1p", dx2=0.5, label="Mw 6–7")
spec.add_colorbar("seis.cpt", offset=0, height="0.3c")
spec.add_hline(pen="1p,blue")

which is equivalent to:

H 12p,1,blue Earthquake Catalog 2025
N 2 
S 0.2 c 0.4c red 1p 0.5 Mw 5-6
S 0.2 c 0.4c red 1p 0.5 Mw 6-7
B seis.cpt 0 0.3c
D 1p,blue

[seisman]

I think it's technically impossible (or at least very difficult) to reorder legend entries defined by the label parameter, and a manually created legend specification is the best choice. So I prefer to close this feature request.

As for the LegenSpec class propsed in #1513 (comment), I may open a separate feature request later.