pygmt.Figure.clip

Figure.clip(data=None, x=None, y=None, *, straight_line=None, frame=None, projection=None, invert=None, region=None, pen=None, verbose=None, **kwargs)

Create a polygonal clip path.

This function sets a clip path for the figure. The clip path is applied to plotting functions that are called within the context manager.

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

Aliases:

  • A = straight_line

  • B = frame

  • J = projection

  • N = invert

  • R = region

  • V = verbose

  • W = pen

Parameters

  • data (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 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.

  • x/y (1d arrays) – The x and y coordinates of the clip path.

  • frame (bool or str or list) – Set map boundary frame and axes attributes.

  • projection (str) – projcode[projparams/]width. Select map projection.

  • region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.

  • straight_line (bool or str) – [m|p|x|y|r|t]. By default, geographic line segments are connected as great circle arcs. To connect them as straight lines, use straight_line. Alternatively, add m to connect the line by first following a meridian, then a parallel. Or append p to start following a parallel, then a meridian. (This can be practical to connect a line along parallels, for example). For Cartesian data, points are simply connected, unless you append x or y to draw stair-case curves that whose first move is along x or y, respectively. For polar projection, append r or t to connect staircase curves whose first move is along r or theta, respectively.

  • invert (bool) – Invert the sense of what is inside and outside. For example, when using a single clip path, use invert=True to only plot points outside to path. Cannot be used with frame.

  • 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

  • pen (str) – Draw the output of the clip path using the pen attributes before clipping is initiated [Default is no outline].

Examples

>>> import pygmt
>>>
>>> # Create x,y data for the clip path
>>> x = [-60, 60, 60, -60]
>>> y = [-30, -30, 30, 30]
>>>
>>> # Load the 1 degree global earth relief
>>> grid = pygmt.datasets.load_earth_relief()
>>>
>>> # Create a figure and draw the map frame
>>> fig = pygmt.Figure()
>>> fig.basemap(region="d", projection="W15c", frame=True)
>>>
>>> # Use a "with" statement to initialize the clip context manager
>>> with fig.clip(x=x, y=y):
...     # Map elements under the "with" statement are clipped
...     fig.grdimage(grid=grid)
...
>>> fig.show()  
<IPython.core.display.Image object>