Source code for pygmt.src.grdlandmask

"""
grdlandmask - Create a "wet-dry" mask grid from shoreline data base
"""

import xarray as xr
from pygmt.clib import Session
from pygmt.exceptions import GMTInvalidInput
from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias

__doctest_skip__ = ["grdlandmask"]


[docs] @fmt_docstring @use_alias( A="area_thresh", D="resolution", E="bordervalues", I="spacing", N="maskvalues", R="region", V="verbose", r="registration", x="cores", ) @kwargs_to_strings(I="sequence", R="sequence", N="sequence", E="sequence") def grdlandmask(outgrid: str | None = None, **kwargs) -> xr.DataArray | None: r""" Create a grid file with set values for land and water. Read the selected shoreline database and create a grid to specify which nodes in the specified grid are over land or over water. The nodes defined by the selected region and lattice spacing will be set according to one of two criteria: (1) land vs water, or (2) the more detailed (hierarchical) ocean vs land vs lake vs island vs pond. Full option list at :gmt-docs:`grdlandmask.html` {aliases} Parameters ---------- {outgrid} {spacing} {region} {area_thresh} resolution : str *res*\[\ **+f**\]. Select the resolution of the data set to use ((**f**)ull, (**h**)igh, (**i**)ntermediate, (**l**)ow, or (**c**)rude). The resolution drops off by ~80% between data sets. [Default is **l**]. Append **+f** to automatically select a lower resolution should the one requested not be available [abort if not found]. Alternatively, choose (**a**)uto to automatically select the best resolution given the chosen region. Note that because the coastlines differ in details a node in a mask file using one resolution is not guaranteed to remain inside [or outside] when a different resolution is selected. bordervalues : bool, str, float, or list Nodes that fall exactly on a polygon boundary should be considered to be outside the polygon [Default considers them to be inside]. Alternatively, append either a list of four values [*cborder*, *lborder*, *iborder*, *pborder*] or just the single value *bordervalue* (for the case when they should all be the same value). This turns on the line-tracking mode. Now, after setting the mask values specified via ``maskvalues`` we trace the lines and change the node values for all cells traversed by a line to the corresponding border value. Here, *cborder* is used for cells traversed by the coastline, *lborder* for cells traversed by a lake outline, *iborder* for islands-in-lakes outlines, and *pborder* for ponds-in-islands-in-lakes outlines [Default is no line tracing]. maskvalues : str or list [*wet*, *dry*] or [*ocean*, *land*, *lake*, *island*, *pond*]. Set the values that will be assigned to nodes. Values can be any number, including the textstring NaN [Default is [0, 1, 0, 1, 0] (i.e., [0, 1])]. Also select ``bordervalues`` to let nodes exactly on feature boundaries be considered outside [Default is inside]. {verbose} {registration} {cores} Returns ------- ret Return type depends on whether the ``outgrid`` parameter is set: - :class:`xarray.DataArray` if ``outgrid`` is not set - None if ``outgrid`` is set (grid output will be stored in file set by ``outgrid``) Example ------- >>> import pygmt >>> # Create a landmask grid with a longitude range of 125° E to 130° E, a >>> # latitude range of 30° N to 35° N, and a grid spacing of 1 arc-degree >>> landmask = pygmt.grdlandmask(spacing=1, region=[125, 130, 30, 35]) """ if kwargs.get("I") is None or kwargs.get("R") is None: raise GMTInvalidInput("Both 'region' and 'spacing' must be specified.") with Session() as lib: with lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd: kwargs["G"] = voutgrd lib.call_module(module="grdlandmask", args=build_arg_list(kwargs)) return lib.virtualfile_to_raster(vfname=voutgrd, outgrid=outgrid)