Merge branch 'master' into mapping/plot3d

weiji14 · weiji14 · commit 37578e1b01c3 · 2020-11-03T13:49:03.000+13:00
diff --git a/.github/workflows/ci_tests.yaml b/.github/workflows/ci_tests.yaml
@@ -117,6 +117,14 @@ jobs:
         shell: bash -l {0}
         run: make test PYTEST_EXTRA="-r P"
 
+      # Upload diff images on test failure
+      - name: Upload diff images if any test fails
+        uses: actions/upload-artifact@v2
+        if: ${{ failure() }}
+        with:
+          name: artifact-${{ runner.os }}-${{ matrix.python-version }}
+          path: tmp-test-dir-with-unique-name
+
       # Build the documentation
       - name: Build the documentation
         shell: bash -l {0}
diff --git a/.github/workflows/ci_tests_dev.yaml b/.github/workflows/ci_tests_dev.yaml
@@ -86,3 +86,11 @@ jobs:
       # Run the tests
       - name: Test with pytest
         run: make test PYTEST_EXTRA="-r P"
+
+      # Upload diff images on test failure
+      - name: Upload diff images if any test fails
+        uses: actions/upload-artifact@v2
+        if: ${{ failure() }}
+        with:
+          name: artifact-GMT-${{ matrix.gmt_git_ref }}-${{ runner.os }}
+          path: tmp-test-dir-with-unique-name
diff --git a/doc/conf.py b/doc/conf.py
@@ -37,10 +37,8 @@
 
 # configure links to GMT docs
 extlinks = {
-    "gmt-docs": (
-        "https://docs.generic-mapping-tools.org/latest/%s",
-        "https://docs.generic-mapping-tools.org/latest/",
-    )
+    "gmt-docs": ("https://docs.generic-mapping-tools.org/latest/%s", None),
+    "gmt-term": ("https://docs.generic-mapping-tools.org/latest/gmt.conf#term-%s", ""),
 }
 
 # intersphinx configuration
diff --git a/doc/index.rst b/doc/index.rst
@@ -33,6 +33,7 @@
     tutorials/coastlines.rst
     tutorials/plot.rst
     tutorials/text.rst
+    tutorials/configuration.rst
 
 .. toctree::
     :maxdepth: 2
diff --git a/examples/tutorials/configuration.py b/examples/tutorials/configuration.py
@@ -0,0 +1,76 @@
+"""
+Configuring PyGMT defaults
+==========================
+
+Default GMT parameters can be set globally or locally using :class:`pygmt.config`.
+"""
+
+import pygmt
+
+########################################################################################
+# Configuring default GMT parameters
+# ----------------------------------
+#
+# Users can override default parameters either temporarily (locally) or permanently
+# (globally) using :meth:`pygmt.config`. The full list of default parameters that can be
+# changed can be found at :gmt-docs:`gmt.conf.html`.
+#
+# We demonstrate the usage of :meth:`pygmt.config` by configuring a map plot.
+
+# Start with a basic figure with the default style
+fig = pygmt.Figure()
+fig.basemap(region=[115, 119.5, 4, 7.5], projection="M10c", frame=True)
+fig.coast(land="black", water="skyblue")
+
+fig.show()
+
+########################################################################################
+# Globally overriding defaults
+# ----------------------------
+#
+# The ``MAP_FRAME_TYPE`` parameter specifies the style of map frame to use, of which there
+# are 5 options: ``fancy`` (default, seen above), ``fancy+``, ``plain``, ``graph``
+# (which does not apply to geographical maps) and ``inside``.
+#
+# The ``FORMAT_GEO_MAP`` parameter controls the format of geographical tick annotations.
+# The default uses degrees and minutes. Here we specify the ticks to be a decimal number
+# of degrees.
+
+fig = pygmt.Figure()
+
+# Configuration for the 'current figure'.
+pygmt.config(MAP_FRAME_TYPE="plain")
+pygmt.config(FORMAT_GEO_MAP="ddd.xx")
+
+fig.basemap(region=[115, 119.5, 4, 7.5], projection="M10c", frame=True)
+fig.coast(land="black", water="skyblue")
+
+fig.show()
+
+########################################################################################
+# Locally overriding defaults
+# ---------------------------
+#
+# It is also possible to temporarily override the default parameters, which is very
+# useful for limiting the scope of changes to a particular plot. :class:`pygmt.config` is
+# implemented as a context manager, which handles the setup and teardown of a GMT
+# session. Python users are likely familiar with the ``with open(...) as file:`` snippet,
+# which returns a ``file`` context manager. In this way, it can be used to override a parameter
+# for a single command, or a sequence of commands. An application of :class:`pygmt.config`
+# as a context manager is shown below:
+
+fig = pygmt.Figure()
+
+# This will have a fancy+ frame
+with pygmt.config(MAP_FRAME_TYPE="fancy+"):
+    fig.basemap(region=[115, 119.5, 4, 7.5], projection="M10c", frame=True)
+fig.coast(land="black", water="skyblue")
+
+# Shift plot origin down by 10cm to plot another map
+fig.shift_origin(yshift="-10c")
+
+# This figure retains the default "fancy" frame
+fig.basemap(region=[115, 119.5, 4, 7.5], projection="M10c", frame=True)
+fig.coast(land="black", water="skyblue")
+
+fig.show()
diff --git a/pygmt/mathops.py b/pygmt/mathops.py
@@ -8,40 +8,105 @@
 
 @fmt_docstring
 @use_alias(
+    A="transparency",
     C="cmap",
-    T="series",
+    D="background",
+    F="color_model",
     G="truncate",
     H="output",
     I="reverse",
+    M="overrule_bg",
+    N="no_bg",
+    Q="log",
+    T="series",
     V="verbose",
+    W="categorical",
+    Ww="cyclic",
     Z="continuous",
 )
 @kwargs_to_strings(T="sequence", G="sequence")
 def makecpt(**kwargs):
     """
-    Creates a static color palette table (CPT).
+    Make GMT color palette tables.
+
+    This is a module that will help you make static color palette tables
+    (CPTs). By default, the CPT will simply be saved to the current session,
+    but you can use *output* to save it to a file. You define an equidistant
+    set of contour intervals or pass your own z-table or list, and create a new
+    CPT based on an existing master (dynamic) CPT. The resulting CPT can be
+    reversed relative to the master cpt, and can be made continuous or
+    discrete. For color tables beyond the standard GMT offerings, visit
+    `cpt-city <http://soliton.vm.bytemark.co.uk/pub/cpt-city/>`_ and
+    `Scientific Colour-Maps <http://www.fabiocrameri.ch/colourmaps.php>`_.
+
+    The CPT includes three additional colors beyond the range of z-values.
+    These are the background color (B) assigned to values lower than the lowest
+    *z*-value, the foreground color (F) assigned to values higher than the
+    highest *z*-value, and the NaN color (N) painted wherever values are
+    undefined.
+
+    If the master CPT includes B, F, and N entries, these will be copied into
+    the new master file. If not, the parameters :gmt-term:`COLOR_BACKGROUND`,
+    :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` from the
+    :gmt-docs:`gmt.conf <gmt.conf>` file or the command line will be used. This
+    default behavior can be overruled using the options *background*,
+    *overrule_bg* or *no_bg*.
+
+    The color model (RGB, HSV or CMYK) of the palette created by **makecpt**
+    will be the same as specified in the header of the master CPT. When there
+    is no :gmt-term:`COLOR_MODEL` entry in the master CPT, the
+    :gmt-term:`COLOR_MODEL` specified in the :gmt-docs:`gmt.conf <gmt.conf>`
+    file or on the command line will be used.
 
     Full option list at :gmt-docs:`makecpt.html`
 
     {aliases}
 
     Parameters
     ----------
+    transparency : str
+        Sets a constant level of transparency (0-100) for all color slices.
+        Append **+a** to also affect the fore-, back-, and nan-colors
+        [Default is no transparency, i.e., 0 (opaque)].
     cmap : str
         Selects the master color palette table (CPT) to use in the
         interpolation. Full list of built-in color palette tables can be found
         at :gmt-docs:`cookbook/cpts.html#built-in-color-palette-tables-cpt`.
+    background : bool or str
+        Select the back- and foreground colors to match the colors for lowest
+        and highest *z*-values in the output CPT [Default (``background=True``
+        or ``background='o'``) uses the colors specified in the master file, or
+        those defined by the parameters :gmt-term:`COLOR_BACKGROUND`,
+        :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN`]. Use
+        ``background='i'`` to match the colors for the lowest and highest
+        values in the input (instead of the output) CPT.
+    color_model :
+        ``[R|r|h|c][+c[label]]``.
+        Force output CPT to be written with r/g/b codes, gray-scale values or
+        color name (**R**, default) or r/g/b codes only (**r**), or h-s-v codes
+        (**h**), or c/m/y/k codes (**c**).  Optionally or alternatively, append
+        **+c** to write discrete palettes in categorical format. If *label* is
+        appended then we create labels for each category to be used when the
+        CPT is plotted. The *label* may be a comma-separated list of category
+        names (you can skip a category by not giving a name), or give
+        *start*[-], where we automatically build monotonically increasing
+        labels from *start* (a single letter or an integer). Append - to build
+        ranges *start*-*start+1* instead.
     series : list or str
-        ``[min/max/inc[+b|l|n]|file|list]``. Defines the range of the new CPT
-        by giving the lowest and highest z-value (and optionally an interval).
-        If this is not given, the existing range in the master CPT will be used
-        intact.
+        ``[min/max/inc[+b|l|n]|file|list]``.
+        Defines the range of the new CPT by giving the lowest and highest
+        z-value (and optionally an interval). If this is not given, the
+        existing range in the master CPT will be used intact. The values
+        produced defines the color slice boundaries.  If **+n** is used it
+        refers to the number of such boundaries and not the number of slices.
+        For details on array creation, see
+        :gmt-docs:`makecpt.html#generate-1d-array`.
     truncate : list or str
-        ``zlo/zhi``. Truncate the incoming CPT so that the lowest and highest
-        z-levels are to zlo and zhi. If one of these equal NaN then we leave
-        that end of the CPT alone. The truncation takes place before any
-        resampling. See also
-        :gmt-docs:`cookbook/features.html#manipulating-cpts`.
+        ``zlo/zhi``.
+        Truncate the incoming CPT so that the lowest and highest z-levels are
+        to *zlo* and *zhi*. If one of these equal NaN then we leave that end of
+        the CPT alone. The truncation takes place before any resampling. See
+        also :gmt-docs:`cookbook/features.html#manipulating-cpts`.
     output : str
         Optional. The file name with extension .cpt to store the generated CPT
         file. If not given or False (default), saves the CPT as the session
@@ -51,19 +116,38 @@ def makecpt(**kwargs):
         progression in the master CPT. Set this to z to reverse the sign of
         z-values in the color table. Note that this change of z-direction
         happens before *truncate* and *series* values are used so the latter
-        must be compatible with the changed z-range. See also
+        must be compatible with the changed *z*-range. See also
         :gmt-docs:`cookbook/features.html#manipulating-cpts`.
+    overrule_bg :
+        Overrule background, foreground, and NaN colors specified in the master
+        CPT with the values of the parameters :gmt-term:`COLOR_BACKGROUND`,
+        :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` specified in
+        the :gmt-docs:`gmt.conf <gmt.conf>` file or on the command line. When
+        combined with **background**, only :gmt-term:`COLOR_NAN` is considered.
+    no_bg : bool
+        Do not write out the background, foreground, and NaN-color fields
+        [Default will write them, i.e. ``no_bg=False``].
+    log : bool
+        For logarithmic interpolation scheme with input given as logarithms.
+        Expects input z-values provided via **series** to be log10(*z*),
+        assigns colors, and writes out *z*.
     continuous : bool
-        Creates a continuous CPT [Default is discontinuous, i.e., constant
-        colors for each interval]. This option has no effect when no *series*
-        is used, or when using *series=[z_min, z_max]*; in the first case the
-        input CPT remains untouched, in the second case it is only scaled to
-        match the range z_min/z_max.
-
+        Force a continuous CPT when building from a list of colors and a list
+        of z-values [Default is None, i.e. discrete values].
     {V}
-
+    categorical : bool
+        Do not interpolate the input color table but pick the output colors
+        starting at the beginning of the color table, until colors for all
+        intervals are assigned. This is particularly useful in combination with
+        a categorical color table, like ``cmap='categorical'``.
+    cyclic : bool
+        Produce a wrapped (cyclic) color table that endlessly repeats its
+        range. Note that ``cyclic=True`` cannot be set together with
+        ``categorical=True``.
     """
     with Session() as lib:
+        if "W" in kwargs and "Ww" in kwargs:
+            raise GMTInvalidInput("Set only categorical or cyclic to True, not both.")
         if "H" not in kwargs.keys():  # if no output is set
             arg_str = build_arg_string(kwargs)
         elif "H" in kwargs.keys():  # if output is set
diff --git a/pygmt/tests/test_makecpt.py b/pygmt/tests/test_makecpt.py
@@ -182,3 +182,41 @@ def test_makecpt_continuous(grid):
     makecpt(cmap="blue,white", continuous=True, series="-4500,4500")
     fig.grdimage(grid, projection="W0/6i")
     return fig
+
+
+@check_figures_equal()
+def test_makecpt_categorical(region):
+    """
+    Use static color palette table that is categorical.
+    """
+    fig_ref = Figure()
+    makecpt(C="categorical", W="")
+    fig_ref.colorbar(cmap=True, region=region, frame=True, position="JBC")
+
+    fig_test = Figure()
+    makecpt(cmap="categorical", categorical=True)
+    fig_test.colorbar(cmap=True, region=region, frame=True, position="JBC")
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_makecpt_cyclic(region):
+    """
+    Use static color palette table that is cyclic.
+    """
+    fig_ref = Figure()
+    makecpt(C="cork", W="w")
+    fig_ref.colorbar(cmap=True, region=region, frame=True, position="JBC")
+
+    fig_test = Figure()
+    makecpt(cmap="cork", cyclic=True)
+    fig_test.colorbar(cmap=True, region=region, frame=True, position="JBC")
+    return fig_ref, fig_test
+
+
+def test_makecpt_categorical_and_cyclic():
+    """
+    Use incorrect setting by setting both categorical and cyclic to True.
+    """
+    with pytest.raises(GMTInvalidInput):
+        makecpt(cmap="batlow", categorical=True, cyclic=True)
