`pygmt.Figure.text()`: `incols` (`-i`) parameter does not work as described in the documentation

[yvonnefroehlich]

Description of the problem

The incols (-i) parameter of the method pygmt.Figure.text() does not provide the functionality as described in the documentation.

In this minimal example the data is provided via a txt-file (test_text.txt) with three columns (x,y,text) and two lines and passed through the textfiles parameter. I tested both passing a string and a 1-D array through the incols parameter. When trying to resort the columns 'x' and 'y' via incols=[1,0,2] or incols='1,0,2' the below given error arises (cases (iv), (v)). This problem occurs already when using the incols parameter without any resorting of the columns, i. e. incols=[0,1,2] or incols='0,1,2' (cases (ii), (iii)). This holds also for skipping columns (no code example provided).

Relation to GMT In the GMT documentation (version 6.3) I can not find -iflags for text (in contrast to plot), only -itword and -:[i|o] are listed. However, the PyGMT documentation (version 0.6.1) describes the same functionality of the incols parameter for pygmt.Figure.text() and pygmt.Figure.plot(). Maybe it is not a bug, but an error in the PyGMT documentation (?), since the error message below says:

text [ERROR]: Option -i: Must give -it<word> from 0 (first) to nwords-1

Full code that generated the error

import pygmt as gmt
# Is this an upstream bug?
#gmt.config(GMT_VERBOSE='d')

#-----------------------------------------------------------------------------
#-----------------------------------------------------------------------------
# general stuff
size = 10
RR_use = '0/' + str(size) + '/0/' + str(size)
JJ_use = 'X' + str(size) + 'c'

# (x, y[, angle, font, justify], text)
# here only two lines with x,y,text
data_text = 'test_text.txt'

#-----------------------------------------------------------------------------
#-----------------------------------------------------------------------------
# create figure object
fig = gmt.Figure()

fig.basemap(region=RR_use, projection=JJ_use, frame='agf',)

#-----------------------------------------------------------------------------
#%% (i) no usage of incols parameter - for reference, works correctly
fig.text(textfiles=data_text,)
fig.show()
#-----------------------------------------------------------------------------
#%% (ii) passing a string to incols parameter (no re-ordering of columns)
fig.text(textfiles=data_text, incols='0,1,2',)
fig.show()
#-----------------------------------------------------------------------------
#%% (iii) passing a 1-D array to incols parameter (no re-ordering of columns)
fig.text(textfiles=data_text, incols=[0,1,2],)
fig.show()
#-----------------------------------------------------------------------------
#%% (iv) passing a string to incols parameter (re-ordering of columns)
fig.text(textfiles=data_text, incols='1,0,2',)
fig.show()
#-----------------------------------------------------------------------------
#%% (v) passing a 1-D array to incols parameter (re-ordering of columns)
fig.text(textfiles=data_text, incols=[1,0,2],)
fig.show()

Full error message

For the cases (ii) to (v):

text [ERROR]: Option -i: Must give -it<word> from 0 (first) to nwords-1.
Traceback (most recent call last):

  File ~\C2\EigeneDokumente\Studium\Promotion\E_GMT\00_testing\question_text\text_read_from_file.py:55 in <module>
    fig.text(textfiles=data_text, incols='1,0,2',)

  File C:\ProgramData\Anaconda3\envs\pygmt_env\lib\site-packages\pygmt\helpers\decorators.py:585 in new_module
    return module_func(*args, **kwargs)

  File C:\ProgramData\Anaconda3\envs\pygmt_env\lib\site-packages\pygmt\helpers\decorators.py:725 in new_module
    return module_func(*args, **kwargs)

  File C:\ProgramData\Anaconda3\envs\pygmt_env\lib\site-packages\pygmt\src\text.py:236 in text_
    lib.call_module("text", build_arg_string(kwargs, infile=fname))

  File C:\ProgramData\Anaconda3\envs\pygmt_env\lib\site-packages\pygmt\clib\session.py:502 in call_module
    raise GMTCLibError(

GMTCLibError: Module 'text' failed with status code 72:
text [ERROR]: Option -i: Must give -it<word> from 0 (first) to nwords-1.

System information

Output of python -c "import pygmt; pygmt.show_versions()":

PyGMT information:
  version: v0.6.1
System information:
  python: 3.9.12 | packaged by conda-forge | (main, Mar 24 2022, 23:17:03) [MSC v.1929 64 bit (AMD64)]
  executable: C:\ProgramData\Anaconda3\envs\pygmt_env\python.exe
  machine: Windows-10-10.0.19043-SP0
Dependency information:
  numpy: 1.22.3
  pandas: 1.4.2
  xarray: 2022.3.0
  netCDF4: 1.5.8
  packaging: 21.3
  geopandas: 0.10.2
  ghostscript: 9.54.0
  gmt: 6.3.0
GMT library information:
  binary dir: C:/ProgramData/Anaconda3/envs/pygmt_env
  cores: 4
  grid layout: rows
  library path: C:/ProgramData/Anaconda3/envs/pygmt_env/Library/bin/gmt.dll
  padding: 2
  plugin dir: C:/ProgramData/Anaconda3/envs/pygmt_env/Library/bin/gmt_plugins
  share dir: C:/Program Files (x86)/gmt6/share
  version: 6.3.0

[seisman]

@PaulWessel Could you please explain why text only allows -it, not the general -i option?

[PaulWessel]

pstext was written a long time ago when GMT4 syntax for input prevailed. Input was expected to be

lon lat size angle font justification text

We later improved this via the -F settings. The overall result is that because of backwards compatibility this module is not reading data as numerical plus trailing text but as two leading numerical columns (3 if -Z) and the rest is read as trailing text which we further parse internally in text based on -F. Thus -i does not really work for this module.

[seisman]

@PaulWessel Thanks for the good explanations.

@yvonnefroehlich I think we just need to update the -it description for text following the GMT official documentation.

[yvonnefroehlich]

Also, from my side thanks to @PaulWessel for the background explanations!

@yvonnefroehlich I think we just need to update the -it description for text following the GMT official documentation.

@seisman Yes, looks like this. So, should I open a pull request to reduce the incols description of pygmt.Figure.text() to the tword option/argument corresponding to the GMT documentation for text?

[seisman]

should I open a pull request to reduce the incols description of pygmt.Figure.text() to the tword option/argument corresponding to the GMT documentation for text?

Yes, should remove the {i} placeholder and add the correct docstrings for -it.

https://github.com/GenericMappingTools/pygmt/blob/1067fa316b214d470f26f4affba743a4835a53c8/pygmt/src/text.py#L159