pygmt.clib.Session.read_data

Session.read_data(infile, kind, family=None, geometry=None, mode='GMT_READ_NORMAL', region=None, data=None)[source]

Read a data file into a GMT data container.

Wraps GMT_Read_Data but only allows reading from a file. The function definition is different from the original C API function.

Parameters:

  • infile (str) – The input file name.

  • kind (Literal['dataset', 'grid', 'image']) – The data kind of the input file. Valid values are "dataset", "grid" and "image".

  • family (str | None, default: None) – A valid GMT data family name (e.g., "GMT_IS_DATASET"). See the FAMILIES attribute for valid names. If None, will determine the data family from the kind parameter.

  • geometry (str | None, default: None) – A valid GMT data geometry name (e.g., "GMT_IS_POINT"). See the GEOMETRIES attribute for valid names. If None, will determine the data geometry from the kind parameter.

  • mode (str, default: 'GMT_READ_NORMAL') – 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. Default is GMT_READ_NORMAL which corresponds to the default read mode value of 0 in the GMT_enum_read enum.

  • region (Sequence[float] | None, default: None) – Subregion of the data, in the form of [xmin, xmax, ymin, ymax, zmin, zmax]. If None, the whole data is read.

  • data (default: None) – None or the pointer returned by this function after a first call. It’s useful when reading grids/images/cubes in two steps (get a grid/image/cube structure with a header, then read the data).

Returns:

Pointer to the data container, or None if there were errors.

Raises:

GMTCLibError – If the GMT API function fails to read the data.