pygmt.grd2xyz

pygmt.grd2xyz(grid, output_type='pandas', outfile=None, region=None, verbose=False, outcols=None, **kwargs)[source]

Convert grid to data table.

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

Full GMT docs at https://docs.generic-mapping-tools.org/6.6/grd2xyz.html.

Aliases:

  • C = cstyle

  • W = weight

  • Z = convention

  • b = binary

  • d = nodata

  • f = coltypes

  • h = header

  • s = skiprows

  • R = region

  • V = verbose

  • o = outcols

Parameters:

  • grid (str | PathLike | 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.6/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 | PathLike | 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 [Full usage].

  • 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.6/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.6/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 (int | str | Sequence[int | str] | None, default: None) –

    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 a sequence: specify individual columns in output order (e.g., outcols=(1, 0) for the 2nd column followed by the 1st column).

    • For a string: 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.

      Optionally, append one of the following modifiers to any column or column range to transform the output columns:

      • +l to take the log10 of the input values.

      • +d to divide the output values by the factor divisor [Default is 1].

      • +s to multiple the output values by the factor scale [Default is 1].

      • +o to add the given offset to the output values [Default is 0].

  • 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 the 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