Updated Docstring for Function, added and refined tests, more alias options. Added additional kwarg list type that combines elements with +

Added file contour definition for file based grdcontour test

Author: akshmakov

gmt/base_plotting.py

@@ -127,16 +127,23 @@ def coast(self, **kwargs):
 
     @fmt_docstring
     @use_alias(
-        R="region",
-        J="projection",
-        A="annotation_interval",
-        C="contour_interval",
+        A="annotation",
         B="frame",
+        C="interval",
         G="label_placement",
+        J="projection",
         L="limit",
+        Q="cut",
+        R="region",
+        S="resample",
+        U="logo",
         W="pen",
     )
-    @kwargs_to_strings(R="sequence")
+    @kwargs_to_strings(
+        R="sequence",
+        L='sequence',
+        A="sequence_plus",
+    )
     def grdcontour(self, grid, **kwargs):
         """
         Convert grids or images to contours and plot them on maps
@@ -151,7 +158,38 @@ def grdcontour(self, grid, **kwargs):
         ----------
         grid : str or xarray.DataArray
             The file name of the input grid or the grid loaded as a DataArray.
-
+        C : str or int
+            Specify the contour lines to generate.
+
+            - The filename of a `CPT`  file where the color boundaries will
+              be used as contour levels.
+            - The filename of a 2 (or 3) column file containing the contour
+              levels (col 1), (C)ontour or (A)nnotate (col 2), and optional
+              angle (col 3)
+            - A fixed contour interval ``cont_int`` or a single contour with
+              ``+[cont_int]``
+        A : str,  int, or list
+            Specify or disable annotated contour levels, modifies annotated
+            contours specified in ``-C``.
+
+            - Specify a fixed annotation interval ``annot_int`` or a
+              single annotation level ``+[annot_int]``
+            - Disable all annotation  with  ``'-'``
+            - Optional label modifers can be specifed as a single string
+              ``'[annot_int]+e'``  or with a list of options
+              ``([annot_int], 'e', 'f10p', 'gred')``.
+        L : str or list of 2 ints
+            Do no draw contours below `low` or above `high`, specify as string
+            ``'[low]/[high]'``  or list ``[low,high]``.
+        Q : string or int
+            Do not draw contours with less than `cut` number of points.
+        S : string or int
+            Resample smoothing factor.
+        {J}
+        {R}
+        {B}
+        {G}
+        {W}
         """
         kwargs = self._preprocess(**kwargs)
         kind = data_kind(grid, None, None)

gmt/helpers/decorators.py

@@ -221,6 +221,7 @@ def kwargs_to_strings(convert_bools=True, **conversions):
     * 'sequence': transforms a sequence (list, tuple) into a ``'/'`` separated
       string
     * 'sequence_comma': transforms a sequence into a ``','`` separated string
+    * 'sequence_plus': transforms a sequence into a ``'+'`` separated string
 
     Parameters
     ----------
@@ -262,15 +263,17 @@ def kwargs_to_strings(convert_bools=True, **conversions):
     args: 123
 
     """
-    valid_conversions = ["sequence", "sequence_comma"]
+    valid_conversions = ["sequence", "sequence_comma", "sequence_plus"]
 
     for arg, fmt in conversions.items():
         if fmt not in valid_conversions:
             raise GMTInvalidInput(
                 "Invalid conversion type '{}' for argument '{}'.".format(fmt, arg)
             )
 
-    separators = {"sequence": "/", "sequence_comma": ","}
+    separators = {"sequence": "/",
+                  "sequence_comma": ",",
+                  "sequence_plus": "+"}
 
     # Make the actual decorator function
     def converter(module_func):
@@ -284,7 +287,9 @@ def new_module(*args, **kwargs):
             for arg, fmt in conversions.items():
                 if arg in kwargs:
                     value = kwargs[arg]
-                    issequence = fmt in ("sequence", "sequence_comma")
+                    issequence = fmt in ("sequence",
+                                         "sequence_comma",
+                                         "sequence_plus")
                     if issequence and is_nonstr_iter(value):
                         kwargs[arg] = separators[fmt].join(
                             "{}".format(item) for item in value

gmt/tests/baseline/test_grdcontour_interval_file_full_opts.png

@@ -0,0 +1,10 @@
+-6000 C
+-5000 C
+-4000 A
+-3000 C 
+-2000 C 
+-1000 C
+0 A
+1000 C
+2000 A
+3000 C

gmt/tests/data/contours.txt

@@ -3,12 +3,18 @@
 """
 import pytest
 import numpy as np
+import os
+
 
 from .. import Figure
 from ..exceptions import GMTInvalidInput
 from ..datasets import load_earth_relief
 
 
+TEST_DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
+TEST_CONTOUR_FILE = os.path.join(TEST_DATA_DIR, "contours.txt")
+
+
 @pytest.mark.mpl_image_compare
 def test_grdcontour():
     """Plot a contour image using an xarray grid
@@ -17,7 +23,7 @@ def test_grdcontour():
     grid = load_earth_relief()
     fig = Figure()
     fig.grdcontour(grid,
-                   contour_interval="1000",
+                   interval="1000",
                    projection="W0/6i")
     return fig
 
@@ -30,8 +36,8 @@ def test_grdcontour_labels():
     grid = load_earth_relief()
     fig = Figure()
     fig.grdcontour(grid,
-                   contour_interval="1000",
-                   annotation_interval="5000",
+                   interval="1000",
+                   annotation="5000",
                    projection="W0/6i",
                    pen=["a1p,red", "c0.5p,black"],
                    label_placement="d3i",
@@ -45,7 +51,7 @@ def test_grdcontour_slice():
     grid = load_earth_relief().sel(lat=slice(-30, 30))
     fig = Figure()
     fig.grdcontour(grid,
-                   contour_interval="1000",
+                   interval="1000",
                    projection="M6i")
     return fig
 
@@ -56,7 +62,7 @@ def test_grdcontour_file():
     fig = Figure()
     fig.grdcontour(
         "@earth_relief_60m",
-        contour_interval="1000",
+        interval="1000",
         limit="0",
         pen="0.5p,black",
         region=[-180, 180, -70, 70],
@@ -65,6 +71,33 @@ def test_grdcontour_file():
     return fig
 
 
+@pytest.mark.mpl_image_compare
+def test_grdcontour_interval_file_full_opts():
+    """ Plot based on external contour level file """
+    fig = Figure()
+    comargs = {
+        'region': [-161.5, -154, 18.5, 23],
+        'interval': TEST_CONTOUR_FILE,
+        'grid': "@earth_relief_10m",
+        'resample': "100",
+        'projection': "M6i",
+        'cut': 10,
+    }
+
+    fig.grdcontour(
+        **comargs,
+        limit=(-25000, -1),
+        pen=["a1p,blue", "c0.5p,blue"],
+    )
+
+    fig.grdcontour(
+        **comargs,
+        limit="0",
+        pen=["a1p,black", "c0.5p,black"],
+    )
+    return fig
+
+
 def test_grdcontour_fails():
     "Should fail for unrecognized input"
     fig = Figure()