Wrap the GMT API function GMT_Read_Data to read data into GMT data containers #3324
Conversation
… need cast is needed outside the function
pygmt/tests/test_clib_read_data.py
Outdated
| data_ptr = lib.read_data(infile, kind="grid", mode="GMT_CONTAINER_ONLY") | ||
| grid = data_ptr.contents | ||
| header = grid.header.contents | ||
| assert header.n_rows == 14 | ||
| assert header.n_columns == 8 | ||
| assert header.wesn[:] == [-55.0, -47.0, -24.0, -10.0] | ||
| assert header.z_min == 190.0 | ||
| assert header.z_max == 981.0 | ||
| assert header.n_bands == 1 # Explicitely check n_bands | ||
| assert not grid.data # The data is not read yet |
There was a problem hiding this comment.
Can't do xrgrid = data_ptr.contents.to_dataarray() here because data is not read yet, so grid.data is NULL. Maybe we should modify the GMT_GRID.to_dataarray() method to fill the DataArray with np.empty() if grid.data is not read yet?
Edit: I think it's not necessary after thinking twice.
pygmt/clib/session.py
Outdated
| mode | ||
| How the data is to be read from the file. This option varies depending on | ||
| the given family. See the GMT API documentation for details. |
There was a problem hiding this comment.
Can you link to where in the GMT API documentation what options there are for mode?
There was a problem hiding this comment.
Co-authored-by: Wei Ji <[email protected]>
Co-authored-by: Wei Ji <[email protected]>
Co-authored-by: Wei Ji <[email protected]>
| kind: Literal["dataset", "grid"], | ||
| family: str | None = None, | ||
| geometry: str | None = None, | ||
| mode: str = "GMT_READ_NORMAL", |
There was a problem hiding this comment.
Thinking on whether to make this an enum or use Literal instead of a str. Looking at https://docs.generic-mapping-tools.org/6.5/devdocs/api.html#import-from-a-file-stream-or-handle, it seems like it's possible to pass in mode as one of the variants of GMT_enum_container or GMT_enum_gridio? It also looks like mode can be None (or unset) if reading from text or table.
There was a problem hiding this comment.
I believe the documentation is incomplete, and mode can accept specific values plus some modifiers, making it impossible to list all of them.
There was a problem hiding this comment.
Yeah that what I thought too, there might be other options we's unaware of. That said, should we allow for mode=None (or whatever works when we don't want to set a mode)?
There was a problem hiding this comment.
In the GMT C API, mode has an unsigned int type, so the mode argument must be an integer number and can't be None. The C enum GMT_READ_NORMAL has a value of 0 (https://github.com/GenericMappingTools/gmt/blob/3e9fcb1f54e4e93fc1e309e0be6e2288eb79f3d2/src/gmt_resources.h#L244), which is also the default read mode.
We can define mode=None, and add one line code like:
if mode == None:
mode = "GMT_READ_NORMAL"
but I feel it's not as good as setting GMT_READ_NORMAL as the default.
There was a problem hiding this comment.
Ah ok then, then the GMT_READ_NORMAL default here makes sense. Maybe good to mention it in the docstring.
There was a problem hiding this comment.
Thanks @seisman, just one additional suggestion on documenting the default mode="GMT_READ_NORMAL". Also need to fix the W505 doc-line-too-long lint error before merging.
| kind: Literal["dataset", "grid"], | ||
| family: str | None = None, | ||
| geometry: str | None = None, | ||
| mode: str = "GMT_READ_NORMAL", |
There was a problem hiding this comment.
Ah ok then, then the GMT_READ_NORMAL default here makes sense. Maybe good to mention it in the docstring.
Description of proposed changes
See #3318 for the motivations.
This PR wraps the GMT API functions
GMT_Read_Datafor reading data file into GMT data containers. Currently, onlyGMT_DATASETandGMT_GRIDare supported, other data containers will be supported later.The first two commits 5a56ba8 and 7ccf641 are cherry-picked from PR #3318.
Preview at https://pygmt-dev--3324.org.readthedocs.build/en/3324/api/generated/pygmt.clib.Session.read_data.html
Reminders
make formatandmake checkto make sure the code follows the style guide.doc/api/index.rst.Slash Commands
You can write slash commands (
/command) in the first line of a comment to performspecific operations. Supported slash command is:
/format: automatically format and lint the code