Enhance text with extra functionality and aliases

[weiji14]

Description of proposed changes

Adding extra functionality to text, including aliases that were missing in initial implementation at #321. In support of the text tutorial at #480. Preview documentation at https://pygmt-git-enhance-text.gmt.vercel.app/api/generated/pygmt.Figure.text.html

TODO:

• Allow setting angle=True so that users can parse the angle from a textfile (in GMT it will be -F+a. (4c52613)
• Alias W=pen (138617f)
• Alias C=clearance (45a9858)
• Alias G=color/fill (9b8e837)
• Alias -F+c=position (9e7a353)
• Alias D=offset (187a733)
• etc

I'd be quite keen to enable text placement without setting an x or y by using position (-F+c in GMT) to get the x/y from the map frame's region. For example, the GMT gallery example at https://docs.generic-mapping-tools.org/latest/gallery/ex40.html does gmt text -Dj0.1i/0.1i -F+cLT+jTL+f18p+t"T = 100 km"to print the text at the top-left (TL) position in the map frame.

Fixes #

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

[seisman]

These lines convert a list or a tuple into comma-separated strings. They don't make sense here.

pygmt/pygmt/base_plotting.py

Lines 820 to 822 in 0267dd1

	angle="sequence_comma",
	font="sequence_comma",
	justify="sequence_comma",

[weiji14]

These lines convert a list or a tuple into comma-separated strings. They don't make sense here.

pygmt/pygmt/base_plotting.py

Lines 820 to 822 in 0267dd1

	angle="sequence_comma",
	font="sequence_comma",
	justify="sequence_comma",

True. I can understand the rationale for font (e.g. doing font=("12p", "Helvetica", "green"), but not sure why I used it for angle and justify. Anyway, if we're going to support passing in an array or list of angle/font/justify, this probably has to go.

[seisman]

textfiles : str or list
A text data file name, or a list of filenames containing 1 or more
records with (x, y[, font, angle, justify], text).

The current implementation only allows -F+a+f+j, so the input format should be

x, y[, angle, font, justify], text

[weiji14]

The current implementation only allows -F+a+f+j, so the input format should be

x, y[, angle, font, justify], text

Done. I seem to recall reading somewhere (was it upstream in GMT?) that the reason was because we want all the numerical values first, and then the string values after. Can't seem to track down that issue/comment though :/ Edit: found it at https://docs.generic-mapping-tools.org/dev/text.html#use-from-external-interface.

[weiji14]

Suggested change

	pd.DataFrame.from_dict(
	{
	"x": np.atleast_1d(x),
	"y": np.atleast_1d(y),
	"text": np.atleast_1d(text),
	}
	).to_csv(
	tmpfile.name,
	sep="\t",
	header=False,
	index=False,
	quoting=csv.QUOTE_NONE,
	)
	file_context = lib.virtualfile_from_vectors(
	np.atleast_1d(x), np.atleast_1d(y), np.atleast_1d(text)
	)

@leouieda mentioned before at #321 (comment) to use virtualfiles, and I finally figured out what he meant. Unfortunately, virtualfile_from_vectors doesn't yet support str types. This is the error on _check_dtype_and_dim:

        if array.dtype.name not in DTYPES:
            raise GMTInvalidInput(
>               "Unsupported numpy data type '{}'.".format(array.dtype.name)
            )
E           pygmt.exceptions.GMTInvalidInput: Unsupported numpy data type 'str864'.

From what I can tell, we'll need to use GMT_Put_Strings is that right? We should do this refactor in a separate PR, this one is already getting a bit too long.

[seisman]

Yes, as I understand it, we need to use GMT_Put_Strings to pass trailing strings to GMT.

[seisman]

See the comment above.

Besides that, I think the PR is good to merge. There are still some missing features about the text() method:

1. Using virtual files instead of temporary file
2. Let angle, font, and justify accept list/array as input
3. more flexible input format, e.g., -F+a+j+f and -F+a+f+j.

I think we can address them in separate PRs in the feature.

[weiji14]

Great, thanks for taking the time to review this so thoroughly @seisman! I'll open a new issue for tackling those future improvements.