From 77c61d4650831b39cbd9dbfa3e1c63bcf38765fb Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Wed, 28 Oct 2020 16:48:16 +1300 Subject: [PATCH 1/8] Start completing documentation for makecpt Starting to properly document all major arguments for `makecpt` as per upstream GMT docs at https://docs.generic-mapping-tools.org/6.1/makecpt.html. Begin by refreshing current aliases series (T), truncate (G), reverse (I) and continuous (Z). --- pygmt/mathops.py | 46 +++++++++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/pygmt/mathops.py b/pygmt/mathops.py index a4a61c13d42..55e4b3f9c6b 100644 --- a/pygmt/mathops.py +++ b/pygmt/mathops.py @@ -9,17 +9,28 @@ @fmt_docstring @use_alias( C="cmap", - T="series", G="truncate", H="output", I="reverse", + T="series", V="verbose", 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). In classic mode we write the CPT to standard output, while under + modern mode we simply save the CPT as the current session CPT (but see + **output**). 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 `_ and + `Scientific Colour-Maps `_. Full option list at :gmt-docs:`makecpt.html` @@ -32,16 +43,20 @@ def makecpt(**kwargs): interpolation. Full list of built-in color palette tables can be found at :gmt-docs:`cookbook/cpts.html#built-in-color-palette-tables-cpt`. 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,14 +66,11 @@ 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`. 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} From da8f3b05a29ca8093631155fec145570b926a31d Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Wed, 28 Oct 2020 16:48:59 +1300 Subject: [PATCH 2/8] Add sphinx extlink 'gmt-term' for linking to gmt.conf parameters --- doc/conf.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 6b61ac02008..0202fad58c6 100644 --- 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 From 17382b8f980717d517e99a66e58e51b8d9b3540e Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Wed, 28 Oct 2020 16:49:53 +1300 Subject: [PATCH 3/8] Complete long description of makecpt --- pygmt/mathops.py | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/pygmt/mathops.py b/pygmt/mathops.py index 55e4b3f9c6b..c5ad27cc632 100644 --- a/pygmt/mathops.py +++ b/pygmt/mathops.py @@ -32,6 +32,25 @@ def makecpt(**kwargs): `cpt-city `_ and `Scientific Colour-Maps `_. + 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 ` file or the command line will be used. This + default behavior can be overruled using the options **-D**, **-M** or + **-N**. + + 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 :doc:`gmt.conf` file or on the + command line will be used. + Full option list at :gmt-docs:`makecpt.html` {aliases} From 0cf4f0c552a8d8c3f4f3b83a65e7559ca77baa2d Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Mon, 2 Nov 2020 16:50:13 +1300 Subject: [PATCH 4/8] Alias transparency (A), color_model (F) and log (Q) for makecpt --- pygmt/mathops.py | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/pygmt/mathops.py b/pygmt/mathops.py index c5ad27cc632..b4c419a9d58 100644 --- a/pygmt/mathops.py +++ b/pygmt/mathops.py @@ -8,10 +8,13 @@ @fmt_docstring @use_alias( + A="transparency", C="cmap", + F="color_model", G="truncate", H="output", I="reverse", + Q="log", T="series", V="verbose", Z="continuous", @@ -57,10 +60,26 @@ def makecpt(**kwargs): 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`. + 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 @@ -87,6 +106,10 @@ def makecpt(**kwargs): happens before *truncate* and *series* values are used so the latter must be compatible with the changed *z*-range. See also :gmt-docs:`cookbook/features.html#manipulating-cpts`. + 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 Force a continuous CPT when building from a list of colors and a list of z-values [Default is None, i.e. discrete values]. From 916bbbfa630f63ce6d4827e25f9161d71c2c49f1 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Mon, 2 Nov 2020 17:07:23 +1300 Subject: [PATCH 5/8] Alias categorical (W) for makecpt --- pygmt/mathops.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/pygmt/mathops.py b/pygmt/mathops.py index b4c419a9d58..07b249bc266 100644 --- a/pygmt/mathops.py +++ b/pygmt/mathops.py @@ -17,6 +17,7 @@ Q="log", T="series", V="verbose", + W="categorical", Z="continuous", ) @kwargs_to_strings(T="sequence", G="sequence") @@ -113,8 +114,14 @@ def makecpt(**kwargs): continuous : bool 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 or str + 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 "categorical". Alternatively, use + ``categorical='w'`` to produce a wrapped (cyclic) color table that + endlessly repeats its range. """ with Session() as lib: From 65d057c1b2efa8064d9911f1c8cace5fc963142a Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Mon, 2 Nov 2020 17:24:39 +1300 Subject: [PATCH 6/8] Alias background (D), overrule_bg (M) and no_bg (N) --- pygmt/mathops.py | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/pygmt/mathops.py b/pygmt/mathops.py index 07b249bc266..6d7468f87d8 100644 --- a/pygmt/mathops.py +++ b/pygmt/mathops.py @@ -10,10 +10,13 @@ @use_alias( A="transparency", C="cmap", + D="background", F="color_model", G="truncate", H="output", I="reverse", + M="overrule_bg", + N="no_bg", Q="log", T="series", V="verbose", @@ -28,8 +31,8 @@ def makecpt(**kwargs): This is a module that will help you make static color palette tables (CPTs). In classic mode we write the CPT to standard output, while under modern mode we simply save the CPT as the current session CPT (but see - **output**). 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 + *output*). 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 @@ -46,14 +49,14 @@ def makecpt(**kwargs): 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 ` file or the command line will be used. This - default behavior can be overruled using the options **-D**, **-M** or - **-N**. + 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 :doc:`gmt.conf` file or on the - command line will be used. + :gmt-term:`COLOR_MODEL` specified in the :gmt-docs:`gmt.conf ` + file or on the command line will be used. Full option list at :gmt-docs:`makecpt.html` @@ -69,6 +72,14 @@ def makecpt(**kwargs): 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 @@ -107,6 +118,15 @@ def makecpt(**kwargs): happens before *truncate* and *series* values are used so the latter 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 ` 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*), From be5141cf0d0efe6344e34e30305d76ece37d2116 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Mon, 2 Nov 2020 20:23:17 +1300 Subject: [PATCH 7/8] Alias cyclic (Ww) and ensure this cannot be used with categorical (W) --- pygmt/mathops.py | 14 +++++++++----- pygmt/tests/test_makecpt.py | 38 +++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+), 5 deletions(-) diff --git a/pygmt/mathops.py b/pygmt/mathops.py index 6d7468f87d8..34e5508a2f4 100644 --- a/pygmt/mathops.py +++ b/pygmt/mathops.py @@ -21,6 +21,7 @@ T="series", V="verbose", W="categorical", + Ww="cyclic", Z="continuous", ) @kwargs_to_strings(T="sequence", G="sequence") @@ -135,16 +136,19 @@ def makecpt(**kwargs): 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 or str + 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 "categorical". Alternatively, use - ``categorical='w'`` to produce a wrapped (cyclic) color table that - endlessly repeats its range. - + 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 index 3c1716a1f8d..70443ee1b14 100644 --- 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) From 1303188ab7d777085a01b468606244e2f4f39d05 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Tue, 3 Nov 2020 13:02:53 +1300 Subject: [PATCH 8/8] Remove classic mode mention in makecpt description --- pygmt/mathops.py | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/pygmt/mathops.py b/pygmt/mathops.py index 34e5508a2f4..e74deb82c3a 100644 --- a/pygmt/mathops.py +++ b/pygmt/mathops.py @@ -30,13 +30,12 @@ def makecpt(**kwargs): Make GMT color palette tables. This is a module that will help you make static color palette tables - (CPTs). In classic mode we write the CPT to standard output, while under - modern mode we simply save the CPT as the current session CPT (but see - *output*). 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 + (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 `_ and `Scientific Colour-Maps `_.