Figure.text: Parsing of additional arguments when plotting text from file

[hemmelig]

Description of the problem

I am finding that adding text from a file isn't working as expected (based on the GMT documentation). The additional arguments are not parsed, instead the input files are treated as if there were only 3 input columns (x, y, text).

Full code that generated the error

You will need an additional file:
echo 117,5.2,Helvetica,0,CM,SABAH > example.txt

fig = pygmt.Figure()
with pygmt.config(MAP_FRAME_TYPE="plain"):
    fig.basemap(region=[108, 120, -5, 8], projection="M20c", frame="a")
fig.coast(land="black", water="skyblue", N="1/2p,white")

fig.text(textfiles="example.txt", font="12p,Helvetica-Bold,white")

fig.show()

Full error message

This actually appeared to be a problem with GMT 6 as well. Maybe I'm just missing something? I am interpreting it from: This is one or more files containing 1 or more records with (x, y[, font, angle, justify], text). If so, apologies. I also tried delimiting with spaces instead of commas to no avail.

System information

Please paste the output of python -c "import pygmt; print(pygmt.__version__)":

v0.1.1

(Note: I had to change the above command, as pygmt.show_versions() didn't exist!)

[welcome]

👋 Thanks for opening your first issue here! Please make sure you filled out the template with as much detail as possible. You might also want to take a look at our contributing guidelines and code of conduct.

[seisman]

The text documentation says:

This is one or more files containing 1 or more records with (x, y[, font, angle, justify], text). The attributes in brackets can alternatively be set directly via -F.

The font, angle and justify are not needed unless you add more modifiers to -F option.

For example, if you don't use -F option, then your input data should be: x y text, e.g.,

echo 117 5.2 SABAH | gmt text -R108/120/-5/8 -JM20c -Ba -pdf map

If you use -F+f+a+j, then your input file format is: x y font angle justify text, e.g.,

echo 117 5.2 Helvetica 0 CM SABAH | gmt text -R108/120/-5/8 -JM20c -Ba -F+f+a+j -pdf map

[hemmelig]

Ok - I understand now, though I do not think it is made adequately clear in the documentation that you must add this -F+f+a+j in order for it to work.

The attributes in the brackets can alternatively be set directly via -F.

This phrasing suggests you can use fields in the text file OR set them with -F.

I see why there would be issues replicating this with the current implementation of the PyGMT text binding. I'm happy for this issue to be closed and I'll gather my thoughts and open a new issue (as suggested by you here) on the implementation of text in PyGMT. Thanks for your response.

[weiji14]

(Note: I had to change the above command, as pygmt.show_versions() didn't exist!)

Oops, this is only available on the master pygmt branch. Will need to do a proper pygmt release to get it to work!

[weiji14]

Just to cross-reference #481 (comment) and confuse things further, it should be -F+a+f+j instead of -F+f+a+j, because GMT requires external interfaces (like PyGMT) to have numerical columns (like angle) first, and the text columns (like font, justify) later. See also https://docs.generic-mapping-tools.org/dev/text.html#use-from-external-interface.

Unfortunately, the current PyGMT text implementation hardcodes the +a+f+j order, so passing in either fig.text(..., angle=True, font=True, justify=True) or fig.text(..., font=True, angle=True, justify=True) doesn't make a difference, fig.text will still expect columns in +a+f+j order, which is tricky if your data columns were designed for GMT and you want to port them to PyGMT. Note that this only applies when using the textfiles argument, doing fig.text(x=1, y=2, text="lala", ...) will still be fine.

[seisman]

Unfortunately, the current PyGMT text implementation hardcodes the +a+f+j order, so passing in either fig.text(..., angle=True, font=True, justify=True) or fig.text(..., font=True, angle=True, justify=True) doesn't make a difference, fig.text will still expect columns in +a+f+j order

I think we don't have many choices. The only two options I can see:

1. Improve the docstrings to make it clear that the order of the three columns must be angle font justify.
2. Add one more parameter like justify_first. If it's true, then angle justify font.

I prefer to option 1 because with option 2, (1) the codes will be more complicated; (2) angle is still required to be the 3rd column, so it's impossible to be as flexible as the GMT CLI.