Add dcw alias (E) to Figure.coast (#765)

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

pygmt/base_plotting.py

@@ -63,6 +63,7 @@ def _preprocess(self, **kwargs):  # pylint: disable=no-self-use
         C="lakes",
         B="frame",
         D="resolution",
+        E="dcw",
         I="rivers",
         L="map_scale",
         N="borders",
@@ -141,6 +142,25 @@ def coast(self, **kwargs):
         shorelines : str
             ``'[level/]pen'``
             Draw shorelines [Default is no shorelines]. Append pen attributes.
+        dcw : str or list
+            *code1,code2,…*\ [**+l**\|\ **L**\ ][**+g**\ *fill*\ ]
+            [**+p**\ *pen*\ ][**+z**]
+            Select painting or dumping country polygons from the
+            `Digital Chart of the World
+            <https://en.wikipedia.org/wiki/Digital_Chart_of_the_World>`__.
+            Append one or more comma-separated countries using the 2-character
+            `ISO 3166-1 alpha-2 convention
+            <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`__.
+            To select a state of a country (if available), append
+            .\ *state*, (e.g, US.TX for Texas).  To specify a whole continent,
+            prepend **=** to any of the continent codes (e.g. =EU for Europe).
+            Append **+p**\ *pen* to draw polygon outlines
+            (default is no outline) and **+g**\ *fill* to fill them
+            (default is no fill). Append **+l**\|\ **+L** to *=continent* to
+            only list countries in that continent; repeat if more than one
+            continent is requested. Append **+z** to place the country code in
+            the segment headers via **-Z**\ *code* settings.To apply different
+            settings to different countries, pass a list of string arguments.
         {XY}
         {p}
         {t}

pygmt/tests/test_coast.py

@@ -57,6 +57,7 @@ def test_coast_aliases():
         Y="a10c",
         p="135/25",
         t=13,
+        E="MA+gred",
         C="blue",
     )
     fig_test.coast(
@@ -75,6 +76,7 @@ def test_coast_aliases():
         yshift="a10c",  # Y
         perspective=[135, 25],  # p
         transparency=13,  # t
+        dcw="MA+gred",  # E
         lakes="blue",  # C
     )
     return fig_ref, fig_test
@@ -93,3 +95,91 @@ def test_coast_world_mercator():
         water="white",
     )
     return fig
+
+
+@check_figures_equal()
+def test_coast_dcw_single():
+    "Test passing a single country code to dcw"
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.coast(R="-10/15/25/44", J="M15c", B="a", G="brown", E="ES+gbisque+pblue")
+    fig_test.coast(
+        region=[-10, 15, 25, 44],
+        frame="a",
+        projection="M15c",
+        land="brown",
+        dcw="ES+gbisque+pblue",
+    )
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_coast_dcw_multiple():
+    "Test passing multiple country code to dcw"
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.coast(R="-10/15/25/44", J="M15c", B="a", G="brown", E="ES,IT+gbisque+pblue")
+    fig_test.coast(
+        region=[-10, 15, 25, 44],
+        frame="a",
+        projection="M15c",
+        land="brown",
+        dcw="ES,IT+gbisque+pblue",
+    )
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_coast_dcw_list():
+    "Test passing a list of country codes and fill options to dcw"
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.coast(
+        R="-10/15/25/44",
+        J="M15c",
+        B="a",
+        G="brown",
+        E=["ES+gbisque+pgreen", "IT+gcyan+pblue"],
+    )
+    fig_test.coast(
+        region=[-10, 15, 25, 44],
+        frame="a",
+        projection="M15c",
+        land="brown",
+        dcw=["ES+gbisque+pgreen", "IT+gcyan+pblue"],
+    )
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_coast_dcw_continent():
+    "Test passing a continent code to dcw"
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.coast(R="-10/15/25/44", J="M15c", B="a", G="brown", E="=AF+gbisque+pblue")
+    fig_test.coast(
+        region=[-10, 15, 25, 44],
+        frame="a",
+        projection="M15c",
+        land="brown",
+        dcw="=AF+gbisque+pblue",
+    )
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_coast_dcw_state():
+    "Test passing a US state code to dcw"
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.coast(
+        R="-75/-69/40/44", J="M15c", B="a", G="brown", E="US.MA+gbisque+pblue"
+    )
+    fig_test.coast(
+        region=[-75, -69, 40, 44],
+        frame="a",
+        projection="M15c",
+        land="brown",
+        dcw="US.MA+gbisque+pblue",
+    )
+    return fig_ref, fig_test