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,18 @@ 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 +288,7 @@ def new_module(*args, **kwargs):
             for arg, fmt in conversions.items():
                 if arg in kwargs:
                     value = kwargs[arg]
-                    issequence = fmt == "sequence" or fmt == "sequence_comma"
+                    issequence = "sequence" in fmt
                     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,11 +23,10 @@ def test_grdcontour():
     grid = load_earth_relief()
     fig = Figure()
     fig.grdcontour(grid,
-                   contour_interval="1000",
+                   interval="1000",
                    projection="W0/6i")
     return fig
 
-
 @pytest.mark.mpl_image_compare
 def test_grdcontour_labels():
     """Plot a contour image using a xarray grid
@@ -30,40 +35,63 @@ 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",
                    )
     return fig
 
-
 @pytest.mark.mpl_image_compare
 def test_grdcontour_slice():
     "Plot an contour image using an xarray grid that has been sliced"
     grid = load_earth_relief().sel(lat=slice(-30, 30))
     fig = Figure()
     fig.grdcontour(grid,
-                   contour_interval="1000",
+                   interval="1000",
                    projection="M6i")
     return fig
 
-
 @pytest.mark.mpl_image_compare
 def test_grdcontour_file():
     "Plot a contour image using grid file input"
     fig = Figure()
     fig.grdcontour(
         "@earth_relief_60m",
-        contour_interval="1000",
+        interval="1000",
         limit="0",
         pen="0.5p,black",
         region=[-180, 180, -70, 70],
         projection="M10i",
     )
     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"