pygmt.grd2xyz

pygmt.grd2xyz(grid, output_type='pandas', outfile=None, **kwargs)

Convert grid to data table.

Read a grid and output xyz-triplets as a numpy.ndarray, pandas.DataFrame, or ASCII file.

Full option list at https://docs.generic-mapping-tools.org/6.5/grd2xyz.html

Aliases:

• C = cstyle

• R = region

• V = verbose

• W = weight

• Z = convention

• b = binary

• d = nodata

• f = coltypes

• h = header

• o = outcols

• s = skiprows

Parameters:

• grid (str or xarray.DataArray) –

  Name of the input grid file or the grid loaded as a xarray.DataArray object.

  For reading a specific grid file format or applying basic data operations, see https://docs.generic-mapping-tools.org/6.5/gmt.html#grd-inout-full for the available modifiers.

• output_type (Literal['pandas', 'numpy', 'file'], default: 'pandas') –

  Desired output type of the result data.

  • pandas will return a pandas.DataFrame object.

  • numpy will return a numpy.ndarray object.

  • file will save the result to the file specified by the outfile parameter.

• outfile (str | None, default: None) – File name for saving the result data. Required if output_type="file". If specified, output_type will be forced to be "file".

• cstyle (str) – [f|i]. Replace the x- and y-coordinates on output with the corresponding column and row numbers. These start at 0 (C-style counting); append f to start at 1 (Fortran-style counting). Alternatively, append i to write just the two columns index and z, where index is the 1-D indexing that GMT uses when referring to grid nodes.

• region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest. Adding region will select a subsection of the grid. If this subsection exceeds the boundaries of the grid, only the common region will be output.

• weight (str) – [a[+uunit]|weight]. Write out x,y,z,w, where w is the supplied weight (or 1 if not supplied) [Default writes x,y,z only]. Choose a to compute weights equal to the area each node represents. For Cartesian grids this is simply the product of the x and y increments (except for gridline-registered grids at all sides [half] and corners [quarter]). For geographic grids we default to a length unit of k. Change this by appending +uunit. For such grids, the area varies with latitude and also sees special cases for gridline-registered layouts at sides, corners, and poles.

• verbose (bool or str) –

  Select verbosity level [Default is w], which modulates the messages written to stderr. Choose among 7 levels of verbosity:

  • q - Quiet, not even fatal error messages are produced

  • e - Error messages only

  • w - Warnings [Default]

  • t - Timings (report runtimes for time-intensive algorithms)

  • i - Informational messages (same as verbose=True)

  • c - Compatibility warnings

  • d - Debugging messages

• convention (str) –

  [flags]. Write a 1-column ASCII [or binary] table. Output will be organized according to the specified ordering convention contained in flags. If data should be written by rows, make flags start with T (op) if first row is y = ymax or B (ottom) if first row is y = ymin. Then, append L or R to indicate that first element should start at left or right end of row. Likewise for column formats: start with L or R to position first column, and then append T or B to position first element in a row. For gridline registered grids: If grid is periodic in x but the written data should not contain the (redundant) column at x = xmax, append x. For grid periodic in y, skip writing the redundant row at y = ymax by appending y. If the byte-order needs to be swapped, append w. Select one of several data types (all binary except a):

  • a ASCII representation of a single item per record

  • c int8_t, signed 1-byte character

  • u uint8_t, unsigned 1-byte character

  • h int16_t, short 2-byte integer

  • H uint16_t, unsigned short 2-byte integer

  • i int32_t, 4-byte integer

  • I uint32_t, unsigned 4-byte integer

  • l int64_t, long (8-byte) integer

  • L uint64_t, unsigned long (8-byte) integer

  • f 4-byte floating point single precision

  • d 8-byte floating point double precision

  Default format is scanline orientation of ASCII numbers: TLa.

• binary (bool or str) –

  i|o[ncols][type][w][+l|b]. Select native binary input (using binary="i") or output (using binary="o"), where ncols is the number of data columns of type, which must be one of:

  • c - int8_t (1-byte signed char)

  • u - uint8_t (1-byte unsigned char)

  • h - int16_t (2-byte signed int)

  • H - uint16_t (2-byte unsigned int)

  • i - int32_t (4-byte signed int)

  • I - uint32_t (4-byte unsigned int)

  • l - int64_t (8-byte signed int)

  • L - uint64_t (8-byte unsigned int)

  • f - 4-byte single-precision float

  • d - 8-byte double-precision float

  • x - use to skip ncols anywhere in the record

  For records with mixed types, append additional comma-separated combinations of ncols type (no space). The following modifiers are supported:

  • w after any item to force byte-swapping.

  • +l|b to indicate that the entire data file should be read as little- or big-endian, respectively.

  Full documentation is at https://docs.generic-mapping-tools.org/6.5/gmt.html#bi-full.

• nodata (str) – i|onodata. Substitute specific values with NaN (for tabular data). For example, nodata="-9999" will replace all values equal to -9999 with NaN during input and all NaN values with -9999 during output. Prepend i to the nodata value for input columns only. Prepend o to the nodata value for output columns only.

• coltypes (str) – [i|o]colinfo. Specify data types of input and/or output columns (time or geographical data). Full documentation is at https://docs.generic-mapping-tools.org/6.5/gmt.html#f-full.

• header (str) –

  [i|o][n][+c][+d][+msegheader][+rremark][+ttitle]. Specify that input and/or output file(s) have n header records [Default is 0]. Prepend i if only the primary input should have header records. Prepend o to control the writing of header records, with the following modifiers supported:

  • +d to remove existing header records.

  • +c to add a header comment with column names to the output [Default is no column names].

  • +m to add a segment header segheader to the output after the header block [Default is no segment header].

  • +r to add a remark comment to the output [Default is no comment]. The remark string may contain \n to indicate line-breaks.

  • +t to add a title comment to the output [Default is no title]. The title string may contain \n to indicate line-breaks.

  Blank lines and lines starting with # are always skipped.

• outcols (str or 1-D array) –

  cols[,…][,t[word]]. Specify data columns for primary output in arbitrary order. Columns can be repeated and columns not listed will be skipped [Default writes all columns in order, starting with the first (i.e., column 0)].

  • For 1-D array: specify individual columns in output order (e.g., outcols=[1,0] for the 2nd column followed by the 1st column).

  • For str: specify individual columns or column ranges in the format start[:inc]:stop, where inc defaults to 1 if not specified, with columns and/or column ranges separated by commas (e.g., outcols="0:2,4" to output the first three columns followed by the 5th column). To write from a given column until the end of the record, leave off stop when specifying the column range. To write trailing text, add the column t. Append the word number to t to write only a single word from the trailing text. Instead of specifying columns, use outcols="n" to simply read numerical input and skip trailing text. Note: If incols is also used then the columns given to outcols correspond to the order after the incols selection has taken place.

• skiprows (bool or str) –

  [cols][+a][+r]. Suppress output for records whose z-value equals NaN [Default outputs all records]. Optionally, supply a comma-separated list of all columns or column ranges to consider for this NaN test [Default only considers the third data column (i.e., cols = 2)]. Column ranges must be given in the format start[:inc]:stop, where inc defaults to 1 if not specified. The following modifiers are supported:

  • +r to reverse the suppression, i.e., only output the records whose z-value equals NaN.

  • +a to suppress the output of the record if just one or more of the columns equal NaN [Default skips record only if values in all specified cols equal NaN].

Return type:

DataFrame | ndarray | None

Returns:

ret – Return type depends on outfile and output_type:

• None if outfile is set (output will be stored in file set by outfile)

• pandas.DataFrame or numpy.ndarray if outfile is not set (depends on output_type)

Example

>>> import pygmt
>>> # Load a grid of @earth_relief_30m data, with a longitude range of
>>> # 10° E to 30° E, and a latitude range of 15° N to 25° N
>>> grid = pygmt.datasets.load_earth_relief(
...     resolution="30m", region=[10, 30, 15, 25]
... )
>>> # Create a pandas DataFrame with the xyz data from an input grid
>>> xyz_dataframe = pygmt.grd2xyz(grid=grid, output_type="pandas")
>>> xyz_dataframe.head(n=2)
    lon   lat          z
0  10.0  25.0      965.5
1  10.5  25.0      876.5

Examples using pygmt.grd2xyz

Performing grid histogram equalization

Performing grid histogram equalization