pygmt.grdvolume

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

Determine the volume between the surface of a grid and a plane.

Read a 2-D grid file and calculate the volume contained below the surface and above the plane specified by the given contour (or zero if not given) and return the contour, area, volume, and maximum mean height (volume/area). Alternatively, a range of contours can be specified to return the volume and area inside the contour for all contour values.

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

Aliases:

• C = contour

• R = region

• S = unit

• V = verbose

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".

• contour (str, float, or list) – cval|low/high/delta|rlow/high|rcval. Find area, volume and mean height (volume/area) inside and above the cval contour. Alternatively, search using all contours from low to high in steps of delta. [Default returns area, volume and mean height of the entire grid]. The area is measured in the plane of the contour. Adding the r prefix computes the volume below the grid surface and above the planes defined by low and high, or below cval and grid’s minimum. Note that this is an outside volume whilst the other forms compute an inside (below the surface) area volume. Use this form to compute for example the volume of water between two contours. If no contour is given then there is no contour and the entire grid area, volume and the mean height is returned and cval will be reported as 0.

• region (str or list) – 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

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 that contains the contour, area, volume,
>>> # and maximum mean height above the plane specified by the given
>>> # contour and below the surface; set the minimum contour z-value to
>>> # 200, the maximum to 400, and the interval to 50.
>>> output_dataframe = pygmt.grdvolume(
...     grid=grid, contour=[200, 400, 50], output_type="pandas"
... )
>>> print(output_dataframe)
       0             1             2           3
0  200.0  2.323600e+12  8.523815e+14  366.836554
1  250.0  2.275864e+12  7.371655e+14  323.905736
2  300.0  2.166707e+12  6.258570e+14  288.851699
3  350.0  2.019284e+12  5.207732e+14  257.899955
4  400.0  1.870441e+12  4.236191e+14  226.480847