Figure.coast: Use long names ("crude"/"low"/"intermediate"/"high"/"full") for the 'resolution' parameter

Author: seisman

examples/tutorials/basics/coastlines.py

@@ -27,9 +27,9 @@
 # 3. island-in-lake shore
 # 4. lake-in-island-in-lake shore
 #
-# You can specify which level you want to plot by passing the level number and
-# a GMT pen configuration. For example, to plot just the coastlines with 0.5p
-# thickness and black lines:
+# You can specify which level you want to plot by passing the level number and a GMT
+# pen configuration. For example, to plot just the coastlines with 0.5p thickness and
+# black lines:
 
 fig = pygmt.Figure()
 fig.basemap(region="g", projection="W15c", frame=True)
@@ -50,18 +50,14 @@
 # Resolutions
 # -----------
 #
-# The coastline database comes with 5 resolutions. The resolution drops by 80%
-# between levels:
-#
-# 1. ``"c"``: crude
-# 2. ``"l"``: low (default)
-# 3. ``"i"``: intermediate
-# 4. ``"h"``: high
-# 5. ``"f"``: full
+# The coastline database comes with 5 resolutions: ``"full"``, ``"high"``,
+# ``"intermediate"``, ``"low"``, and ``"crude"``. The resolution drops by 80% between
+# levels. The ``resolution`` parameter defaults to ``"auto"`` to automatically select
+# the best resolution given the chosen map scale.
 
 oahu = [-158.3, -157.6, 21.2, 21.8]
 fig = pygmt.Figure()
-for res in ["c", "l", "i", "h", "f"]:
+for res in ["crude", "low", "intermediate", "high", "full"]:
     fig.coast(resolution=res, shorelines="1p", region=oahu, projection="M5c")
     fig.shift_origin(xshift="5c")
 fig.show()
@@ -71,9 +67,9 @@
 # Land and water
 # --------------
 #
-# Use the ``land`` and ``water`` parameters to specify a fill color for land
-# and water bodies. The colors can be given by name or hex codes (like the ones
-# used in HTML and CSS):
+# Use the ``land`` and ``water`` parameters to specify a fill color for land and water
+# bodies. The colors can be given by name or hex codes (like the ones used in HTML and
+# CSS):
 
 fig = pygmt.Figure()
 fig.basemap(region="g", projection="W15c", frame=True)

pygmt/src/coast.py

@@ -2,6 +2,8 @@
 coast - Plot land and water.
 """
 
+from typing import Literal
+
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
@@ -37,7 +39,13 @@
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
-def coast(self, **kwargs):
+def coast(
+    self,
+    resolution: Literal[  # noqa: ARG001
+        "auto", "full", "high", "intermediate", "low", "crude"
+    ] = "auto",
+    **kwargs,
+):
     r"""
     Plot continents, shorelines, rivers, and borders on maps.
 
@@ -73,10 +81,11 @@ def coast(self, **kwargs):
         parameter. Optionally, specify separate fills by appending
         **+l** for lakes or **+r** for river-lakes, and passing multiple
         strings in a list.
-    resolution : str
-        **f**\|\ **h**\|\ **i**\|\ **l**\|\ **c**.
-        Select the resolution of the data set to: (**f**\ )ull, (**h**\ )igh,
-        (**i**\ )ntermediate, (**l**\ )ow, and (**c**\ )rude.
+    resolution
+        Select the resolution of the coastline dataset to use. The available resolutions
+        from highest to lowest are: ``"full"``, ``"high"``, ``"intermediate"``,
+        ``"low"``, and ``"crude"``. Default is ``"auto"`` to automatically select the
+        most suitable resolution given the chosen map scale.
     land : str
         Select filling of "dry" areas.
     rivers : int, str, or list
@@ -199,5 +208,9 @@ def coast(self, **kwargs):
             """At least one of the following parameters must be specified:
             lakes, land, water, rivers, borders, dcw, Q, or shorelines"""
         )
+    # resolution
+    if kwargs.get("D") is not None:
+        kwargs["D"] = kwargs["D"][0]
+
     with Session() as lib:
         lib.call_module(module="coast", args=build_arg_list(kwargs))

pygmt/tests/test_coast.py

@@ -29,7 +29,7 @@ def test_coast_world_mercator():
         projection="M15c",
         frame="af",
         land="#aaaaaa",
-        resolution="c",
+        resolution="crude",
         water="white",
     )
     return fig