Need examples for adding texts on maps

[seisman]

Description of the desired feature

We don't have examples for adding texts on maps using Figure.text(). The example should be a Python script in the examples/tutorials directory. See the other Python scripts in that directory for reference.

[hemmelig]

Hi - I've been keeping an eye of pygmt for a while. This seemed like a good place to start in helping out.

For the example, I've written it in 4 sections:

1. Adding text to maps (using various font/angle arguments) - from file, from matrix, from vectors.
2. Explicit demonstration of the justify argument
3. Explicit demonstration of the angle argument
4. Description of the font (-F) argument

In putting together this example along the lines of your other tutorials, I encountered a couple of points. Would be good to address/discuss them before I create a pull request.

1. When plotting text, the optional arguments that can be used in the textfile input don't appear to work. This seems to not be a PyGMT issue, as I had the same issue running the command in GMT 6 on the command line. Am I missing something? The GMT documentation suggests this should work fine. Currently it is treating the text file as if there were only 3 columns of input data (x, y, text).

2. Not strictly related to text, but I encountered it while putting together the examples. Calling plot(x=[1, 2], y=[1.1, 2.2]) does not produce the plot I expect. I expect a line joining (1, 1.1) to (2, 2.2). Instead, a line connecting (0, 2.2) to (1, 1.1) is plotted. I believe the issue is the difference in data types (int/float), and it causes several quite odd things This is not an issue using plot(data=np.array([[1, 1.1], [2, 2.2]])), as numpy.array will cast a mixture of ints/floats to floats. Not sure whether to raise this as an actual issue, but my "correction" has been to specifically cast to numpy.float when using the pygmt.conversion.vectors_to_arrays function:

   arrays = [as_c_contiguous(np.asarray(i, dtype=np.float)) for i in vectors]

To reproduce this:

fig = pygmt.Figure()
fig.basemap(region=[0, 4, 0, 4], projection="X10c", frame=True)
fig.plot(x=[0, 4], y=[2., 2.])
fig.show()

Happy to move this to a separate issue.

3. Finally, if 1 is not addressed (or is just me missing something), then I am wondering if there might be a better way of constructing the argument string that is passed in under the -F flag. I understand it is currently directly relatable to how arguments are passed into GMT functions , but to me a more pythonic interface (along the lines of matplotlib) that constructs the argument string under the hood would be much appreciated! Something like a _construct method that takes the **kwargs (text_font, font_size, font_color or color) passed into text and builds it into the +f argument.

Apologies if I've just missed something! Let me know if there's any more information I can provide.

[weiji14]

Hi @hemmelig! Thanks for offering to help out! You're right that there's a few problems with the current text implementation I wrapped in #321, it was only a very basic start. You're more than welcome to improve it as you see fit though (e.g. with text_font, font_size, etc arguments as you suggested). The kwargs style thing you mentioned is similar to what been proposed in #379, and you could take some cues from that PR.

In regard to point 2, it's already raised in #255, and will be fixed once GMT 6.1.0 is released and we pull that into PyGMT.

[seisman]

When plotting text, the optional arguments that can be used in the textfile input don't appear to work. This seems to not be a PyGMT issue, as I had the same issue running the command in GMT 6 on the command line. Am I missing something? The GMT documentation suggests this should work fine. Currently it is treating the text file as if there were only 3 columns of input data (x, y, text).

Could you please open a separate issue and give an example script for this so that we can reproduce it?

Finally, if 1 is not addressed (or is just me missing something), then I am wondering if there might be a better way of constructing the argument string that is passed in under the -F flag. I understand it is currently directly relatable to how arguments are passed into GMT functions , but to me a more pythonic interface (along the lines of matplotlib) that constructs the argument string under the hood would be much appreciated! Something like a _construct method that takes the **kwargs (text_font, font_size, font_color or color) passed into text and builds it into the +f argument.

Yes, text() now has a lot of limitations. For example, GMT command line can accept varying fonts for each text strings, while Figure.text() currently not. Again, if you have any idea to improve the text() function, please open a separate issue so that we can discuss more details.

For the example, I've written it in 4 sections:

Adding text to maps (using various font/angle arguments) - from file, from matrix, from vectors. Explicit demonstration of the justify argument Explicit demonstration of the angle argument Description of the font (-F) argument

Improving the text() function definitely takes more time. I think we can add a tutorial showing how text() works as it is and perhaps also document its limitations.

[hemmelig]

Can I expect any text preceded by a # (as per other examples) is formatted into markdown? If I wish to add links to parts of the GMT documentation, what would be the best way to do this? I've currently used the markdown format in Jupyter notebook ( text ).

Other than that, I've got round to finishing a simple tutorial and will submit a pull request from my own fork.

[seisman]

Can I expect any text preceded by a # (as per other examples) is formatted into markdown?

I believe the examples are written in ReST syntax.

You can submit your pull request directly. It's easier for us to review and help improve your PR.