pygmt.xyz2grd

pygmt.xyz2grd(table, *, duplicate=None, dname=None, outgrid=None, spacing=None, region=None, verbose=None, onecolumn=None, registration=None, **kwargs)

Create a grid file from table data.

xyz2grd reads one or more z or xyz tables and creates a binary grid file. xyz2grd will report if some of the nodes are not filled in with data. Such unconstrained nodes are set to a value specified by the user [Default is NaN]. Nodes with more than one value will be set to the mean value.

Full option list at https://docs.generic-mapping-tools.org/latest/xyz2grd.html

Aliases:

• A = duplicate

• D = dname

• G = outgrid

• I = spacing

• R = region

• V = verbose

• Z = onecolumn

• r = registration

Parameters

• table (str or numpy.ndarray or pandas.DataFrame or xarray.Dataset or geopandas.GeoDataFrame) – Pass in either a file name to an ASCII data table, a 1D/2D numpy.ndarray, a pandas.DataFrame, an xarray.Dataset made up of 1D xarray.DataArray data variables, or a geopandas.GeoDataFrame containing the tabular data.

• outgrid (str or None) – Optional. The name of the output netCDF file with extension .nc to store the grid in.

• duplicate (str) – [d|f|l|m|n|r|S|s|u|z] By default we will calculate mean values if multiple entries fall on the same node. Use -A to change this behavior, except it is ignored if -Z is given. Append f or s to simply keep the first or last data point that was assigned to each node. Append l or u or d to find the lowest (minimum) or upper (maximum) value or the difference between the maximum and miminum value at each node, respectively. Append m or r or S to compute mean or RMS value or standard deviation at each node, respectively. Append n to simply count the number of data points that were assigned to each node (this only requires two input columns x and y as z is not consulted). Append z to sum multiple values that belong to the same node.

• dname (str) – [+xxname][+yyname][+zzname][+dvname] [+sscale][+ooffset][+ninvalid][+ttitle] [+rremark][+vvarname]. Give one or more combinations for values xname, yname, zname (3rd dimension in cube), and dname (data value name) and give the names of those variables and in square bracket their units, e.g., “distance [km]”), scale (to multiply data values after read [normally 1]), offset (to add to data after scaling [normally 0]), invalid (a value to represent missing data [NaN]), title (anything you like), and remark (anything you like). Items not listed will remain untouched. Give a blank name to completely reset a particular string. Use quotes to group texts with more than one word. If any of your text contains plus symbols you need to escape them (place a backslash before each plus-sign) so they are not confused with the option modifiers. Alternatively, you can place the entire double-quoted string inside single quotes.

• spacing (str) –

  xinc[+e|n][/yinc[+e|n]]. x_inc [and optionally y_inc] is the grid spacing.

  • Geographical (degrees) coordinates: Optionally, append an increment unit. Choose among m to indicate arc minutes or s to indicate arc seconds. If one of the units e, f, k, M, n or u is appended instead, the increment is assumed to be given in meter, foot, km, mile, nautical mile or US survey foot, respectively, and will be converted to the equivalent degrees longitude at the middle latitude of the region (the conversion depends on PROJ_ELLIPSOID). If y_inc is given but set to 0 it will be reset equal to x_inc; otherwise it will be converted to degrees latitude.

  • All coordinates: If +e is appended then the corresponding max x (east) or y (north) may be slightly adjusted to fit exactly the given increment [by default the increment may be adjusted slightly to fit the given domain]. Finally, instead of giving an increment you may specify the number of nodes desired by appending +n to the supplied integer argument; the increment is then recalculated from the number of nodes, the registration, and the domain. The resulting increment value depends on whether you have selected a gridline-registered or pixel-registered grid; see GMT File Formats for details.

  Note: If region=grdfile is used then the grid spacing and the registration have already been initialized; use spacing and registration to override these values.

• region (str or list) – Required if this is the first plot command. xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.

• 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

• onecolumn (str) –

  [flags] Read a 1-column ASCII [or binary] table. This assumes that all the nodes are present and sorted according to specified ordering convention contained in flags. If incoming data represents 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 is 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. Note: These two row/column indicators are only required for grids; for other tables they do not apply. For gridline registered grids: If data are periodic in x but the incoming data do not contain the (redundant) column at x = xmax, append x. For data periodic in y without redundant row at y = ymax, append y. Append sn to skip the first n number of bytes (probably a header). If the byte-order or the words needs to be swapped, append w. Select one of several data types (all binary except a):

  A ASCII representation of one or more floating point values per record

  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, signed 2-byte integer

  H uint16_t, unsigned 2-byte integer

  i int32_t, signed 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: -ZTLa. The difference between A and a is that the latter can decode both dateTclock and ddd:mm:ss[.xx] formats but expects each input record to have a single value, while the former can handle multiple values per record but can only parse regular floating point values. Translate incoming z-values via the -i0 option and needed modifiers.

• registration (str) – g|p. Force gridline (g) or pixel (p) node registration. [Default is g(ridline)].

Returns

ret (xarray.DataArray or None) – Return type depends on whether the outgrid parameter is set:

• xarray.DataArray: if outgrid is not set

• None if outgrid is set (grid output will be stored in file set by outgrid)```