pygmt.grdgradient

pygmt.grdgradient(grid, *, azimuth=None, direction=None, radiance=None, outgrid=None, region=None, verbose=None, interpolation=None, **kwargs)

Compute the directional derivative of the vector gradient of the data.

Can accept azimuth, direction, and radiance input to create the resulting gradient.

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

Aliases:

• A = azimuth

• D = direction

• E = radiance

• G = outgrid

• R = region

• V = verbose

• n = interpolation

Parameters

• grid (str or xarray.DataArray) – The file name of the input grid or the grid loaded as a DataArray.

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

• azimuth (int or float or str or list) – azim[/azim2]. Azimuthal direction for a directional derivative; azim is the angle in the x,y plane measured in degrees positive clockwise from north (the +y direction) toward east (the +x direction). The negative of the directional derivative, -[dz/dx*sin(azim) + dz/dy*cos(azim)], is found; negation yields positive values when the slope of z(x,y) is downhill in the azim direction, the correct sense for shading the illumination of an image by a light source above the x,y plane shining from the azim direction. Optionally, supply two azimuths, azim/azim2, in which case the gradients in each of these directions are calculated and the one larger in magnitude is retained; this is useful for illuminating data with two directions of lineated structures, e.g., 0/270 illuminates from the north (top) and west (left). Finally, if azim is a file it must be a grid of the same domain, spacing and registration as grid that will update the azimuth at each output node when computing the directional derivatives.

• direction (str) – [a][c][o][n]. Find the direction of the positive (up-slope) gradient of the data. To instead find the aspect (the down-slope direction), use a. By default, directions are measured clockwise from north, as azim in azimuth. Append c to use conventional Cartesian angles measured counterclockwise from the positive x (east) direction. Append o to report orientations (0-180) rather than directions (0-360). Append n to add 90 degrees to all angles (e.g., to give local strikes of the surface).

• radiance (str or list) – [m|s|p]azim/elev[+aambient][+ddiffuse][+pspecular][+sshine]. Compute Lambertian radiance appropriate to use with grdimage and grdview. The Lambertian Reflection assumes an ideal surface that reflects all the light that strikes it and the surface appears equally bright from all viewing directions. Here, azim and elev are the azimuth and elevation of the light vector. Optionally, supply ambient [0.55], diffuse [0.6], specular [0.4], or shine [10], which are parameters that control the reflectance properties of the surface. Default values are given in the brackets. Use s for a simpler Lambertian algorithm. Note that with this form you only have to provide azimuth and elevation. Alternatively, use p for the Peucker piecewise linear approximation (simpler but faster algorithm; in this case the azim and elev are hardwired to 315 and 45 degrees. This means that even if you provide other values they will be ignored.)

• 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

• interpolation (str) –

  [b|c|l|n][+a][+bBC][+c][+tthreshold]. Select interpolation mode for grids.

  • b to use B-spline smoothing.

  • c to use bicubic interpolation.

  • l to use bilinear interpolation.

  • n to use nearest-neighbor value (for example to plot

  categorical data).

  The following modifiers are supported:

  • +a to switch off antialiasing (where supported) [Default uses antialiasing].

  • +b to override boundary conditions used, by appending g for geographic, p for periodic, or n for natural boundary conditions. For the latter two you may append x or y to specify just one direction, otherwise both are assumed.

  • +c to clip the interpolated grid to input z-min/z-max [Default may exceed limits].

  • +t to control how close to nodes with NaNs the interpolation will go based on threshold. A threshold of 1.0 requires all (4 or 16) nodes involved in interpolation to be non-NaN. For example, 0.5 will interpolate about half way from a non-NaN value and 0.1 will go about 90% of the way [Default is 0.5].

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)