Support for legend with "handles" and "labels" like MATLAB/matplotlib

[liamtoney]

Description of the desired feature

A wrapper for the GMT 6 legend command with support for specifying "handles" and "labels" as arguments, as in MATLAB (legend docs) and matplotlib (legend docs). The plotting commands (i.e., gmt.Figure.plot(), for now) are modified to return "handles" which are provided as inputs to gmt.Figure.legend(). This addresses part of #214 and #231.

Below is a minimal working example using my add-legend fork:

import gmt

fig = gmt.Figure()

h1 = fig.plot(x=[-5], y=[5], region=[-10, 10, -5, 10], projection='X3i/0', frame='a',
              style='a15p', pen='1.5p,purple')

h2 = fig.plot(x=[0], y=[5],
              style='t10p', color='cyan')

h3 = fig.plot(x=[5], y=[5],
              style='d5p', color='yellow', pen=True)

fig.legend([[h1, h2, h3], ['I am a star!', 'I am a triangle!', 'I am a diamond!']],
           F=True, D='g0/0+w2i+jCM')    

fig.show()

Are you willing to help implement and maintain this feature?

Yes. You can view the source code for my implementation here.

The good news:

• The legend wrapper accepts either the standard specfile (see GMT legend docs) or a list containing a list of handles and a list of labels. So folks can still build a complex legend by creating a specfile.
• The only modification to gmt.Figure.plot() is that it now returns kwargs. So existing users won't have to change their syntax for the plot command.

The bad news:

• This implementation makes use of GMTTempFile since I don't know how to do it any other way (yet).
• Right now I'm using regular expression matching (via re) to separate symbol type and size from the style argument of gmt.Figure.plot(), which is probably really sketchy.
• This only works for symbol entries in the legend, i.e. entries in specfile which have the form:
  S - symbol size fill pen - text
  I feel like this covers a broad portion of typical legend use cases, though.
• I have not written any tests.

[leouieda]

@liamtoney I'm waiting on some new features from GMT that might make this a lot easier (meaning that we might not have to implement it ourselves). But if it doesn't go through, we should definitely do this.

[liamtoney]

Hi @leouieda, it seems like GMT 6 is pretty close to release. Just wanted to ping you for any updates on legend functionality being implemented in the coming release.

[leouieda]

@liamtoney I kind of lost track of this in the main GMT repo (so many things happened in the mean time). I'll start a bit more heavy work on PyGMT soon now that we have 6.0.0rc2 packages for all platforms. I'll get back to this in a little while. Is that OK?

[liamtoney]

@leouieda of course! Thanks for all of your hard work.

[weiji14]

Hi @liamtoney, just wondering if you're still willing in implementing this and maybe submit a Pull Request. Quite keen on getting this legend function wrapped by the end of this month (October 2019) for the PyGMT workshop I'm hosting in November.

I can help out with writing some unit tests and bring the code up to date with GMT 6.0.0rc4 if you're short on time, but just thought I'd ask you first 😄 It'll tie in quite nicely with the colorbar wrapper at #332 I'm currently working on and close #231 once and for all.

[seisman]

FYI, @PaulWessel is implementing the similar feature on the GMT side. I think it also makes the pygmt legend easier to implement.

[weiji14]

Is that with the auto-legend feature at GenericMappingTools/gmt#1749?

[seisman]

Yes, I forgot to post the link to the PR.

[liamtoney]

@weiji14 I'm happy to help implement this. I don't have any experience writing tests, so I'd definitely appreciate help with that. Should we wait until the dust settles on GMT's auto-legend feature? It might change how I'd approach wrapping the command.

[weiji14]

I actually feel that we can go ahead with wrapping legend as it is now, and refactor our code to include the auto-legend stuff once that's merged in (it'll take time for a GMT6.0.0rc5 or 6.0.0 release to come out anyway).

[weiji14]

@weiji14 I'm happy to help implement this. I don't have any experience writing tests, so I'd definitely appreciate help with that. Should we wait until the dust settles on GMT's auto-legend feature? It might change how I'd approach wrapping the command.

Great! Start by creating a test_legend.py file under the pygmt/tests folder. You can have a look at my test_colorbar.py file for inspiration since it's similar. For example: this bit that just tests positioning of a colorbar:

pygmt/pygmt/tests/test_colorbar.py

Lines 1 to 16 in cbca922

	"""
	Tests colorbar
	"""
	import pytest
	from .. import Figure
	@pytest.mark.mpl_image_compare
	def test_colorbar_using_paper_coordinates():
	"""
	Create colorbar positioned at 0cm,0cm with length 1cm and width 0.5cm.
	"""
	fig = Figure()
	fig.colorbar(cmap="rainbow", position="x0c/0c+w1c/0.5c")
	return fig

You'll want to replace colorbar with legend. Also if you're starting out, maybe try running everything outside of the python function and call fig.show() to display the plot.

Once you're happy with the plot, create a 'baseline' output plot using:

py.test --mpl-generate-path=baseline pygmt/tests/test_legend.py

After that, test your code by running make test. Let me know if you have any problems!

[PaulWessel]

Thanks, I will try to wrap up the legend implementation on the C side in the next 1-2 days.

[shicks-seismo]

A legend function is something I've been looking for of late. I'm more than happy to help test any of the implementations mentioned above when they become available.