Add clip parameter to pygmt.Figure.coast

pygmt/src/coast.py

@@ -37,7 +37,7 @@
  t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
-def coast(self, **kwargs):
+def coast(self, clip=None, **kwargs):
  r"""
  Plot continents, shorelines, rivers, and borders on maps
 
@@ -81,7 +81,7 @@ def coast(self, **kwargs):
  (**h**\ )igh, (**i**\ )ntermediate, (**l**\ )ow,
  and (**c**\ )rude.
  land : str
- Select filling or clipping of "dry" areas.
+ Select filling of "dry" areas.
  rivers : int or str or list
  *river*\ [/*pen*].
  Draw rivers. Specify the type of rivers and [optionally] append
@@ -147,7 +147,7 @@ def coast(self, **kwargs):
 
  a = All boundaries (1-3)
  water : str
- Select filling or clipping of "wet" areas.
+ Select filling of "wet" areas.
  {U}
  shorelines : int or str or list
  [*level*\ /]\ *pen*.
@@ -159,6 +159,13 @@ def coast(self, **kwargs):
  lake-in-island-in-lake shore. Pass a list of *level*\ /*pen*
  strings to ``shorelines`` to set multiple levels. When specific
  level pens are set, those not listed will not be drawn.
+ clip : str
+ To clip land do ``clip="land"``, ``clip="water"`` clips water. Use
+ ``clip="end"`` to mark end of existing clip path. The clip path applies
+ to all plotting calls between the start of the clip path and the end of
+ the clip path. No projection information is needed. Also supply
+ ``xshift`` and ``yshift`` settings if you have moved since the clip
+ started.
  dcw : str or list
  *code1,code2,…*\ [**+l**\|\ **L**\ ][**+g**\ *fill*\ ]
  [**+p**\ *pen*\ ][**+z**].
@@ -181,12 +188,47 @@ def coast(self, **kwargs):
  {p}
  {t}
  {V}
+
+ Example
+ -------
+ >>> # Initiate a clip path for Africa so that the subsequent colorimage of
+ >>> # gridded topography is only seen over land
+ >>> import pygmt # doctest: +SKIP
+ >>> # Load a grid of earth_relief_05m data, with an x-range of -30 to 30,
+ >>> # and a y-range of -40 to 40
+ >>> grid = pygmt.datasets.load_earth_relief(
+ ... resolution="05m", region=[-30, 30, -40, 40]
+ ... ) # doctest: +SKIP
+ >>> # Create an instance of the Figure class
+ >>> fig = pygmt.Figure() # doctest: +SKIP
+ >>> # Initiate clip path for land areas based on low-resolution coastlines
+ >>> fig.coast(
+ ... projection="M12c", resolution="l", clip="land", frame=True
+ ... ) # doctest: +SKIP
+ >>> # Plot the clipped grid
+ >>> fig.grdimage(grid=grid, cmap="relief") # doctest: +SKIP
+ >>> # End clip path
+ >>> fig.coast(clip="end") # doctest: +SKIP
  """
  kwargs = self._preprocess(**kwargs) # pylint: disable=protected-access
+
+ if clip:
+ if clip == "land":
+ kwargs["G"] = True
+ elif clip == "water":
+ kwargs["S"] = True
+ elif clip == "end":
+ kwargs["Q"] = True
+ else:
+ raise GMTInvalidInput(
+ "Invalid clip parameter. Must be one of 'land', 'water', and 'end'."
+ )
+
  if not args_in_kwargs(args=["C", "G", "S", "I", "N", "E", "Q", "W"], kwargs=kwargs):
  raise GMTInvalidInput(
  """At least one of the following parameters must be specified:
- lakes, land, water, rivers, borders, dcw, Q, or shorelines"""
+ lakes, land, water, rivers, borders, dcw, clip, or shorelines"""
  )
+
  with Session() as lib:
  lib.call_module("coast", build_arg_string(kwargs))

pygmt/tests/baseline/test_coast_clip_land.png.dvc

@@ -0,0 +1,4 @@
+outs:
+- md5: 12f5586967f870a7e70e012a5dadf76c
+ size: 14597
+ path: test_coast_clip_land.png

pygmt/tests/baseline/test_coast_clip_water.png.dvc

@@ -0,0 +1,4 @@
+outs:
+- md5: dcae0e21783cd153f6daaae927e3a771
+ size: 23423
+ path: test_coast_clip_water.png

pygmt/tests/test_coast.py

@@ -72,3 +72,57 @@ def test_coast_dcw_list():
  dcw=["ES+gbisque+pgreen", "IT+gcyan+pblue"],
  )
  return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_coast_clip_land():
+ """
+ Test to clip dry areas.
+ """
+ region = [-28, -10, 62, 68]
+
+ fig = Figure()
+ fig.basemap(region=region, projection="M8c", frame=True)
+ fig.coast(resolution="l", clip="land")
+ fig.plot(
+ x=[-22.5, -22.5, -15, -15],
+ y=[66, 64, 66, 64],
+ style="c4c",
+ color="red",
+ pen="1.5p,black",
+ )
+ fig.coast(clip="end")
+ return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_coast_clip_water():
+ """
+ Test to clip wet areas.
+ """
+ region = [-28, -10, 62, 68]
+
+ fig = Figure()
+ fig.basemap(region=region, projection="M8c", frame=True)
+ fig.coast(resolution="l", clip="water")
+ fig.plot(
+ x=[-22.5, -22.5, -15, -15],
+ y=[66, 64, 66, 64],
+ style="c4c",
+ color="red",
+ pen="1.5p,black",
+ )
+ fig.coast(clip="end")
+ return fig
+
+
+def test_coast_fail_invalid_parameter():
+ """
+ Coast should raise an exception if an invalid parameter is given as input.
+ """
+ region = [-28, -10, 62, 68]
+
+ fig = Figure()
+
+ with pytest.raises(GMTInvalidInput):
+ fig.coast(region=region, resolution="l", clip="invalid")