From c75d2d1167fce77db8c79c68c1020998b1b61aa7 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Mon, 1 Jun 2020 21:49:34 +1200 Subject: [PATCH 01/25] Turn common aliases from short form to long form To make things more readable, we'll shift our documentation to use long form arguments by default. Starting from the common aliases R, J, B, U, CPT, G and W. --- pygmt/helpers/decorators.py | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 391a1af2c35..1ecfe8fbb81 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -14,30 +14,30 @@ COMMON_OPTIONS = { "R": """\ - R : str or list + region : str or list *Required if this is the first plot command*. ``'xmin/xmax/ymin/ymax[+r][+uunit]'``. Specify the region of interest.""", "J": """\ - J : str + projection : str *Required if this is the first plot command*. Select map projection.""", "B": """\ - B : str or list + frame : str or list Set map boundary frame and axes attributes.""", "U": """\ - U : bool or str + logo : bool or str Draw GMT time stamp logo on plot.""", "CPT": """\ - C : str + cmap : str File name of a CPT file or ``C='color1,color2[,color3,...]'`` to build a linear continuous CPT from those colors automatically.""", "G": """\ - G : str + color : str Select color or pattern for filling of symbols or polygons. Default is no fill.""", "W": """\ - W : str + pen : str Set pen attributes for lines or the outline of symbols.""", } @@ -55,13 +55,13 @@ def fmt_docstring(module_func): The following are places for common parameter descriptions: - * ``{R}``: R (region) option with 4 bounds - * ``{J}``: J (projection) - * ``{B}``: B (frame) - * ``{U}``: U (insert time stamp) - * ``{CPT}``: CPT (the color palette table) - * ``{G}``: G (color) - * ``{W}``: W (pen) + * ``{R}``: region (bounding box as west, east, south, north) + * ``{J}``: projection (coordinate system to use) + * ``{B}``: frame (map frame and axes parameters) + * ``{U}``: logo (insert time stamp logo) + * ``{CPT}``: cmap (the color palette table) + * ``{G}``: color + * ``{W}``: pen Parameters ---------- From 1e14b7272e02b507405c5e6be446f28e27439e4c Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Mon, 1 Jun 2020 22:00:56 +1200 Subject: [PATCH 02/25] Fix fmt_docstring test --- pygmt/helpers/decorators.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 1ecfe8fbb81..6f33a254f84 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -96,11 +96,11 @@ def fmt_docstring(module_func): Parameters ---------- - R : str or list + region : str or list *Required if this is the first plot command*. ``'xmin/xmax/ymin/ymax[+r][+uunit]'``. Specify the region of interest. - J : str + projection : str *Required if this is the first plot command*. Select map projection. From 144effa0a8e10e58e3fd7aff4db398c969ef2326 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Tue, 2 Jun 2020 10:51:12 +1200 Subject: [PATCH 03/25] Alias U as timestamp instead of logo Also added timestamp (U) alias to the plotting functions that have them. Co-Authored-By: Dongdong Tian --- pygmt/base_plotting.py | 6 ++++-- pygmt/helpers/decorators.py | 4 ++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 06d4dd43bd5..71724904760 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -70,6 +70,7 @@ def _preprocess(self, **kwargs): # pylint: disable=no-self-use W="shorelines", G="land", S="water", + U="timestamp", ) @kwargs_to_strings(R="sequence") def coast(self, **kwargs): @@ -439,6 +440,7 @@ def grdview(self, grid, **kwargs): i="columns", l="label", C="cmap", + U="timestamp", ) @kwargs_to_strings(R="sequence", i="sequence_comma") def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): @@ -623,7 +625,7 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs): lib.call_module("contour", arg_str) @fmt_docstring - @use_alias(R="region", J="projection", B="frame") + @use_alias(R="region", J="projection", B="frame", U="timestamp") @kwargs_to_strings(R="sequence") def basemap(self, **kwargs): """ @@ -664,7 +666,7 @@ def basemap(self, **kwargs): lib.call_module("basemap", build_arg_string(kwargs)) @fmt_docstring - @use_alias(R="region", J="projection") + @use_alias(R="region", J="projection", U="timestamp") @kwargs_to_strings(R="sequence") def logo(self, **kwargs): """ diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 6f33a254f84..adb311cfc74 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -26,7 +26,7 @@ frame : str or list Set map boundary frame and axes attributes.""", "U": """\ - logo : bool or str + timestamp : bool or str Draw GMT time stamp logo on plot.""", "CPT": """\ cmap : str @@ -58,7 +58,7 @@ def fmt_docstring(module_func): * ``{R}``: region (bounding box as west, east, south, north) * ``{J}``: projection (coordinate system to use) * ``{B}``: frame (map frame and axes parameters) - * ``{U}``: logo (insert time stamp logo) + * ``{U}``: timestamp (insert time stamp logo) * ``{CPT}``: cmap (the color palette table) * ``{G}``: color * ``{W}``: pen From 2223ae237dc6dfeddd2489ff2ffb35ea7fb656d7 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Tue, 2 Jun 2020 16:20:52 +1200 Subject: [PATCH 04/25] Remove short aliases for makecpt --- pygmt/mathops.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/pygmt/mathops.py b/pygmt/mathops.py index b2a904a25b7..971edbc2645 100644 --- a/pygmt/mathops.py +++ b/pygmt/mathops.py @@ -19,38 +19,38 @@ def makecpt(**kwargs): Parameters ---------- - cmap (C) : str + 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`. - series (T) : list or str + 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. - truncate (G) : list or str + 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`. - output (H) : str + 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 current CPT. - reverse (I) : str + reverse : str Set this to True or c [Default] to reverse the sense of color 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 -G and -T values are used so the latter must be - compatible with the changed z-range. See also + 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`. - continuous (Z) : bool + continuous : bool Creates a continuous CPT [Default is discontinuous, i.e., constant - colors for each interval]. This option has no effect when no -T is - used, or when using -Tz_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. + 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. """ with Session() as lib: From f5fc1a3df7a9ded4f4560d33852f15348e9efd40 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Tue, 2 Jun 2020 16:23:36 +1200 Subject: [PATCH 05/25] Remove short aliases for surface --- pygmt/gridding.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pygmt/gridding.py b/pygmt/gridding.py index 9b2e49b6f00..375d45461ed 100644 --- a/pygmt/gridding.py +++ b/pygmt/gridding.py @@ -41,20 +41,20 @@ def surface(x=None, y=None, z=None, data=None, **kwargs): Parameters ---------- - x, y, z : 1d arrays + x/y/z : 1d arrays Arrays of x and y coordinates and values z of the data points. data : str or 2d array Either a data file name or a 2d numpy array with the tabular data. - spacing (I) : str + spacing : str ``'xinc[unit][+e|n][/yinc[unit][+e|n]]'``. x_inc [and optionally y_inc] is the grid spacing. - region (R) : str or list + region : str or list ``'xmin/xmax/ymin/ymax[+r][+uunit]'``. Specify the region of interest. - outfile (G) : str + outfile : str Optional. The file name for the output netcdf file with extension .nc to store the grid in. From 8906d597938d8fcf7c0b99fbd3e727518f40998f Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Tue, 2 Jun 2020 17:31:16 +1200 Subject: [PATCH 06/25] Add common alias interpolation (n) for grdtrack Also standardize formatting of grdtrack docstring in line with other docs. --- pygmt/helpers/decorators.py | 11 +++++++++++ pygmt/sampling.py | 28 +++++++++++++++++++--------- 2 files changed, 30 insertions(+), 9 deletions(-) diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index adb311cfc74..0e7933ea36c 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -39,6 +39,16 @@ "W": """\ pen : str Set pen attributes for lines or the outline of symbols.""", + "n": """\ + interpolation : str + ``[b|c|l|n][+a][+bBC][+c][+tthreshold]`` + Select interpolation mode for grids. You can select the type of + spline used: + + - 'b' for B-spline + - 'c' for bicubic [Default] + - 'l' for bilinear + - 'n' for nearest-neighbor""", } @@ -62,6 +72,7 @@ def fmt_docstring(module_func): * ``{CPT}``: cmap (the color palette table) * ``{G}``: color * ``{W}``: pen + * ``{n}``: interpolation Parameters ---------- diff --git a/pygmt/sampling.py b/pygmt/sampling.py index 8b6ba7b45d1..891b8676a60 100644 --- a/pygmt/sampling.py +++ b/pygmt/sampling.py @@ -10,11 +10,13 @@ GMTTempFile, data_kind, dummy_context, + use_alias, ) from .exceptions import GMTInvalidInput @fmt_docstring +@use_alias(n="interpolation") def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): """ Sample grids at specified (x,y) locations. @@ -23,30 +25,38 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs): positions in the first two columns (more columns may be present). It interpolates the grid(s) at the positions in the table and writes out the table with the interpolated values added as (one or more) new columns. A - bicubic [Default], bilinear, B-spline or nearest-neighbor (see -n) - interpolation is used, requiring boundary conditions at the limits of the - region. + bicubic [Default], bilinear, B-spline or nearest-neighbor interpolation is + used, requiring boundary conditions at the limits of the region (see + *interpolation*; Default uses “natural” conditions (second partial + derivative normal to edge is zero) unless the grid is automatically + recognized as periodic.) Full option list at :gmt-docs:`grdtrack.html` + {aliases} + Parameters ---------- - points: pandas.DataFrame or file (csv, txt, etc) + points : pandas.DataFrame or str Either a table with (x, y) or (lon, lat) values in the first two - columns, or a data file name. More columns may be present. + columns, or a filename (e.g. csv, txt format). More columns may be + present. - grid: xarray.DataArray or file (netcdf) - Gridded array from which to sample values from. + grid : xarray.DataArray or str + Gridded array from which to sample values from, or a filename (netcdf + format). - newcolname: str + newcolname : str Required if 'points' is a pandas.DataFrame. The name for the new column in the track pandas.DataFrame table where the sampled values will be placed. - outfile: str + outfile : str Required if 'points' is a file. The file name for the output ASCII file. + {n} + Returns ------- track: pandas.DataFrame or None From db842e79ddb98c4b3868b57a3befe2b0207bfe17 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Tue, 2 Jun 2020 21:56:02 +1200 Subject: [PATCH 07/25] Remove short alias for which and refactor test --- pygmt/modules.py | 2 +- pygmt/tests/test_which.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pygmt/modules.py b/pygmt/modules.py index 02bcb3ba299..64f765d41d5 100644 --- a/pygmt/modules.py +++ b/pygmt/modules.py @@ -117,7 +117,7 @@ def which(fname, **kwargs): ---------- fname : str The file name that you want to check. - G : bool or str + download : bool or str If the file is downloadable and not found, we will try to download the it. Use True or 'l' (default) to download to the current directory. Use 'c' to place in the user cache directory or 'u' user data directory diff --git a/pygmt/tests/test_which.py b/pygmt/tests/test_which.py index 1ef48bcb6f8..407127b9551 100644 --- a/pygmt/tests/test_which.py +++ b/pygmt/tests/test_which.py @@ -11,8 +11,8 @@ def test_which(): "Make sure which returns file paths for @files correctly without errors" - for fname in "tut_quakes.ngdc tut_bathy.nc".split(): - cached_file = which("@{}".format(fname), download="c") + for fname in ["tut_quakes.ngdc", "tut_bathy.nc"]: + cached_file = which(f"@{fname}", download="c") assert os.path.exists(cached_file) assert os.path.basename(cached_file) == fname From 71fb973d25c7eae143a40ad3322d51acb04d9e37 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 2 Jun 2020 08:26:22 -0400 Subject: [PATCH 08/25] Remove short aliases from coast --- pygmt/base_plotting.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 71724904760..5c7c200e717 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -101,7 +101,7 @@ def coast(self, **kwargs): ---------- {J} {R} - A : int, float, or str + area_thresh : int, float, or str ``'min_area[/min_level/max_level][+ag|i|s|S][+r|l][+ppercent]'`` Features with an area smaller than min_area in km^2 or of hierarchical level that is lower than min_level or higher than @@ -109,26 +109,26 @@ def coast(self, **kwargs): {B} C : str Set the shade, color, or pattern for lakes and river-lakes. - D : str + resolution : str Selects the resolution of the data set to use ((f)ull, (h)igh, (i)ntermediate, (l)ow, and (c)rude). - G : str + land : str Select filling or clipping of “dry” areas. - I : str + rivers : str ``'river[/pen]'`` Draw rivers. Specify the type of rivers and [optionally] append pen attributes. - L : str + map_scale : str ``'[g|j|J|n|x]refpoint'`` Draws a simple map scale centered on the reference point specified. - N : str + borders : str ``'border[/pen]'`` Draw political boundaries. Specify the type of boundary and [optionally] append pen attributes - S : str + water : str Select filling or clipping of “wet” areas. {U} - W : str + shorelines : str ``'[level/]pen'`` Draw shorelines [Default is no shorelines]. Append pen attributes. From f131cd5ba0011c98a72cde9b637b8d650c8c4e3a Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 2 Jun 2020 08:28:16 -0400 Subject: [PATCH 09/25] Remove short aliases from colorbar --- pygmt/base_plotting.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 5c7c200e717..c9635c4f479 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -167,7 +167,7 @@ def colorbar(self, **kwargs): Parameters ---------- - position (D) : str + position : str ``[g|j|J|n|x]refpoint[+wlength[/width]][+e[b|f][length]][+h|v] [+jjustify][+m[a|c|l|u]][+n[txt]][+odx[/dy]]``. Defines the reference point on the map for the color scale using one of four @@ -183,7 +183,7 @@ def colorbar(self, **kwargs): default, the anchor point on the scale is assumed to be the bottom left corner (BL), but this can be changed by appending +j followed by a 2-char justification code justify. - box (F) : bool or str + box : bool or str ``[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]] [+s[[dx/dy/][shade]]]``. If set to True, draws a rectangular border around the color scale. Alternatively, specify a different @@ -199,12 +199,12 @@ def colorbar(self, **kwargs): offset background shaded region. Here, dx/dy indicates the shift relative to the foreground frame [4p/-4p] and shade sets the fill style to use for shading [gray50]. - truncate (G) : list or str + 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 the plotting. - scale (W) : float + scale : float Multiply all z-values in the CPT by the provided scale. By default the CPT is used as is. From 57f25eab7ae32efad0dd8e31d072fc9abef1521d Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 2 Jun 2020 09:02:41 -0400 Subject: [PATCH 10/25] Improve docstring of colorbar --- pygmt/base_plotting.py | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index c9635c4f479..89b08ea889d 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -171,18 +171,19 @@ def colorbar(self, **kwargs): ``[g|j|J|n|x]refpoint[+wlength[/width]][+e[b|f][length]][+h|v] [+jjustify][+m[a|c|l|u]][+n[txt]][+odx[/dy]]``. Defines the reference point on the map for the color scale using one of four - coordinate systems: (1) Use -Dg for map (user) coordinates, (2) use - -Dj or -DJ for setting refpoint via a 2-char justification code - that refers to the (invisible) map domain rectangle, (3) use -Dn - for normalized (0-1) coordinates, or (4) use -Dx for plot - coordinates (inches, cm, etc.). All but -Dx requires both -R and - -J to be specified. Append +w followed by the length and width of - the color bar. If width is not specified then it is set to 4% of - the given length. Give a negative length to reverse the scale bar. - Append +h to get a horizontal scale [Default is vertical (+v)]. By - default, the anchor point on the scale is assumed to be the bottom - left corner (BL), but this can be changed by appending +j followed - by a 2-char justification code justify. + coordinate systems: (1) Use *g* for map (user) coordinates, (2) use + *j* or *J* for setting refpoint via a 2-char justification code + that refers to the (invisible) map domain rectangle, (3) use *n* + for normalized (0-1) coordinates, or (4) use *x* for plot + coordinates (inches, cm, etc.). All but *x* requires both *region* + and *projection* to be specified. Append +w followed by the length + and width of the color bar. If width is not specified then it is + set to 4% of the given length. Give a negative length to reverse + the scale bar. Append +h to get a horizontal scale + [Default is vertical (+v)]. By default, the anchor point on the + scale is assumed to be the bottom left corner (BL), but this can be + changed by appending +j followed by a 2-char justification code + *justify*. box : bool or str ``[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]] [+s[[dx/dy/][shade]]]``. If set to True, draws a rectangular From ce6e84ffe6fc86be7f3d542da1f78fe554bd9da3 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 2 Jun 2020 09:51:02 -0400 Subject: [PATCH 11/25] Remove short aliases from grdcontour --- pygmt/base_plotting.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 89b08ea889d..5790e462f7d 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -225,7 +225,7 @@ def colorbar(self, **kwargs): Q="cut", R="region", S="resample", - U="logo", + U="timestamp", W="pen", ) @kwargs_to_strings(R="sequence", L="sequence", A="sequence_plus") @@ -243,7 +243,7 @@ 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 + interval : str or int Specify the contour lines to generate. - The filename of a `CPT` file where the color boundaries will @@ -253,7 +253,7 @@ def grdcontour(self, grid, **kwargs): angle (col 3) - A fixed contour interval ``cont_int`` or a single contour with ``+[cont_int]`` - A : str, int, or list + annotation : str, int, or list Specify or disable annotated contour levels, modifies annotated contours specified in ``-C``. @@ -263,12 +263,12 @@ def grdcontour(self, grid, **kwargs): - Optional label modifiers can be specified 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 + limit : 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 + cut : string or int Do not draw contours with less than `cut` number of points. - S : string or int + resample : string or int Resample smoothing factor. {J} {R} From cb5fb41d09eabb37d64d557d6ba3c5888ccf7ce3 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 2 Jun 2020 10:23:41 -0400 Subject: [PATCH 12/25] Remove short aliases from legend --- pygmt/base_plotting.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 5790e462f7d..c8f6a992140 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -761,12 +761,12 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg specification file. {J} {R} - position (D) : str + position : str ``'[g|j|J|n|x]refpoint+wwidth[/height][+jjustify][+lspacing] [+odx[/dy]]'`` Defines the reference point on the map for the legend. By default, uses 'JTR+jTR+o0.2c' which places the legend at the top-right corner inside the map frame, with a 0.2 cm offset. - box (F) : bool or str + box : bool or str ``'[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]] [+s[[dx/dy/][shade]]]'`` Without further options, draws a rectangular border around the legend using **MAP_FRAME_PEN**. By From ac6aad3959ada691454b7e11b591540c27ac1d85 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 2 Jun 2020 10:24:46 -0400 Subject: [PATCH 13/25] Remove short aliases for logo --- pygmt/base_plotting.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index c8f6a992140..3e2eceb78cc 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -667,7 +667,7 @@ def basemap(self, **kwargs): lib.call_module("basemap", build_arg_string(kwargs)) @fmt_docstring - @use_alias(R="region", J="projection", U="timestamp") + @use_alias(R="region", J="projection", U="timestamp", D="position", F="box") @kwargs_to_strings(R="sequence") def logo(self, **kwargs): """ @@ -686,10 +686,10 @@ def logo(self, **kwargs): ---------- {J} {R} - D : str + position : str ``'[g|j|J|n|x]refpoint+wwidth[+jjustify][+odx[/dy]]'``. Sets reference point on the map for the image. - F : bool or str + box : bool or str Without further options, draws a rectangular border around the GMT logo. {U} From 52b8d0c666ef042b22a813b42b00a2bb6089a0dd Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Wed, 3 Jun 2020 14:17:52 +1200 Subject: [PATCH 14/25] Aliased per_column(C), spacing(I), nearest_multiple(T) for info Also updated test_info.py to use long aliases instead of short ones, though the output of `info` are still strings that use short aliases. --- pygmt/modules.py | 15 +++++++++------ pygmt/tests/test_info.py | 31 +++++++++++++++++-------------- 2 files changed, 26 insertions(+), 20 deletions(-) diff --git a/pygmt/modules.py b/pygmt/modules.py index 64f765d41d5..89c6a46db88 100644 --- a/pygmt/modules.py +++ b/pygmt/modules.py @@ -52,6 +52,7 @@ def grdinfo(grid, **kwargs): @fmt_docstring +@use_alias(C="per_column", I="spacing", T="nearest_multiple") def info(fname, **kwargs): """ Get information about data tables. @@ -62,23 +63,25 @@ def info(fname, **kwargs): n columns rounded up and down to the nearest multiple of the supplied increments. By default, this output will be in the form *-Rw/e/s/n*, or the output will be in column form for as many columns as there are - increments provided. The *T* option will provide a *-Tzmin/zmax/dz* string - for makecpt. + increments provided. The *nearest_multiple* option will provide a + *-Tzmin/zmax/dz* string for makecpt. Full option list at :gmt-docs:`gmtinfo.html` + {aliases} + Parameters ---------- fname : str The file name of the input data table file. - C : bool + per_column : bool Report the min/max values per column in separate columns. - I : str + spacing : str ``'[b|p|f|s]dx[/dy[/dz...]]'``. Report the min/max of the first n columns to the nearest multiple of the provided increments and output results in the form *-Rw/e/s/n* - (unless *C* is set). - T : str + (unless *per_column* is set). + nearest_multiple : str ``'dz[+ccol]'`` Report the min/max of the first (0'th) column to the nearest multiple of dz and output this as the string *-Tzmin/zmax/dz*. diff --git a/pygmt/tests/test_info.py b/pygmt/tests/test_info.py index 1e95c51fc0a..3e9da3abf81 100644 --- a/pygmt/tests/test_info.py +++ b/pygmt/tests/test_info.py @@ -17,32 +17,35 @@ def test_info(): "Make sure info works" output = info(fname=POINTS_DATA) expected_output = ( - "{}: N = 20 " "<11.5309/61.7074> " "<-2.9289/7.8648> " "<0.1412/0.9338>\n" - ).format(POINTS_DATA) + f"{POINTS_DATA}: N = 20 " + "<11.5309/61.7074> " + "<-2.9289/7.8648> " + "<0.1412/0.9338>\n" + ) assert output == expected_output -def test_info_c(): - "Make sure the C option works" - output = info(fname=POINTS_DATA, C=True) +def test_info_per_column(): + "Make sure the per_column option works" + output = info(fname=POINTS_DATA, per_column=True) assert output == "11.5309 61.7074 -2.9289 7.8648 0.1412 0.9338\n" -def test_info_i(): - "Make sure the I option works" - output = info(fname=POINTS_DATA, I=0.1) +def test_info_spacing(): + "Make sure the spacing option works" + output = info(fname=POINTS_DATA, spacing=0.1) assert output == "-R11.5/61.8/-3/7.9\n" -def test_info_c_i(): - "Make sure the C and I options work together" - output = info(fname=POINTS_DATA, C=True, I=0.1) +def test_info_per_column_spacing(): + "Make sure the per_column and spacing options work together" + output = info(fname=POINTS_DATA, per_column=True, spacing=0.1) assert output == "11.5 61.8 -3 7.9 0.1412 0.9338\n" -def test_info_t(): - "Make sure the T option works" - output = info(fname=POINTS_DATA, T=0.1) +def test_info_nearest_multiple(): + "Make sure the nearest_multiple option works" + output = info(fname=POINTS_DATA, nearest_multiple=0.1) assert output == "-T11.5/61.8/0.1\n" From aa369dc2ff057633d9eed6644d7be2eac3cc94a6 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Wed, 3 Jun 2020 14:51:57 +1200 Subject: [PATCH 15/25] Remove short aliases for psconvert and improve fmt docstring --- pygmt/figure.py | 41 +++++++++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/pygmt/figure.py b/pygmt/figure.py index 3c867137646..60532228b3c 100644 --- a/pygmt/figure.py +++ b/pygmt/figure.py @@ -105,7 +105,15 @@ def region(self): return wesn @fmt_docstring - @use_alias(F="prefix", T="fmt", A="crop", E="dpi") + @use_alias( + A="crop", + C="gs_option", + E="dpi", + F="prefix", + I="icc_gray", + T="fmt", + Q="anti_aliasing", + ) @kwargs_to_strings() def psconvert(self, **kwargs): """ @@ -116,7 +124,7 @@ def psconvert(self, **kwargs): If no input files are given, will convert the current active figure (see :func:`pygmt.figure`). In this case, an output name must be given - using parameter *F*. + using parameter *prefix*. Full option list at :gmt-docs:`psconvert.html` @@ -124,37 +132,38 @@ def psconvert(self, **kwargs): Parameters ---------- - A : str or bool + crop : str or bool Adjust the BoundingBox and HiResBoundingBox to the minimum required by the image content. Append ``u`` to first remove any GMT-produced time-stamps. Default is True. - C : str + gs_option : str Specify a single, custom option that will be passed on to GhostScript as is. - E : int + dpi : int Set raster resolution in dpi. Default = 720 for PDF, 300 for others. - F : str + prefix : str Force the output file name. By default output names are constructed using the input names as base, which are appended with an appropriate extension. Use this option to provide a different name, but without extension. Extension is still determined automatically. - I : bool + icc_gray : bool Enforce gray-shades by using ICC profiles. - Q : str + anti_aliasing : str Set the anti-aliasing options for graphics or text. Append the size of the subsample box (1, 2, or 4) [4]. Default is no anti-aliasing (same as bits = 1). - T : str - Sets the output format, where b means BMP, e means EPS, E means EPS - with PageSize command, f means PDF, F means multi-page PDF, j means - JPEG, g means PNG, G means transparent PNG (untouched regions are - transparent), m means PPM, s means SVG, and t means TIFF [default - is JPEG]. To bjgt you can append - in order to get a grayscale + fmt : str + Sets the output format, where *b* means BMP, *e* means EPS, *E* + means EPS with PageSize command, *f* means PDF, *F* means + multi-page PDF, *j* means JPEG, *g* means PNG, *G* means + transparent PNG (untouched regions are transparent), *m* means PPM, + *s* means SVG, and *t* means TIFF [default is JPEG]. To ``'bjgt'`` + you can append ``'+m'`` in order to get a monochrome (grayscale) image. The EPS format can be combined with any of the other formats. For example, ``'ef'`` creates both an EPS and a PDF file. - The ``'F'`` creates a multi-page PDF file from the list of input PS - or PDF files. It requires the *F* option. + Using ``'F'`` creates a multi-page PDF file from the list of input + PS or PDF files. It requires the *prefix* option. """ kwargs = self._preprocess(**kwargs) From 718e786cc980a9ddc1c0caa4213f9e440c5e78f0 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 2 Jun 2020 22:54:55 -0400 Subject: [PATCH 16/25] Add U to docstring of grdcontour --- pygmt/base_plotting.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 3e2eceb78cc..abcc20c10ce 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -274,6 +274,7 @@ def grdcontour(self, grid, **kwargs): {R} {B} {G} + {U} {W} """ kwargs = self._preprocess(**kwargs) From b8f7b334daff6d2f535d7eb08f27f2ffa86e738a Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 3 Jun 2020 00:02:29 -0400 Subject: [PATCH 17/25] Remove short aliases for plot --- pygmt/base_plotting.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index abcc20c10ce..927c4c45f94 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -505,12 +505,12 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): ``'[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen]'``. Draw symmetrical error bars. {G} - S : str + style : str Plot symbols (including vectors, pie slices, fronts, decorated or quoted lines). {W} {U} - l : str + label : str Add a legend entry for the symbol or line being plotted. """ kwargs = self._preprocess(**kwargs) From 30136d5c93dac0c6f311741864c2537f17eee172 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 3 Jun 2020 00:09:09 -0400 Subject: [PATCH 18/25] Remove short aliases for contour --- pygmt/base_plotting.py | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 927c4c45f94..e9222ca3cdc 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -590,21 +590,26 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs): By default, geographic line segments are drawn as great circle arcs. To draw them as straight lines, use *A*. {B} - C : Contour file or level(s) - D : Dump contour coordinates - E : Network information - G : Placement of labels - I : Color the triangles using CPT - L : Pen to draw the underlying triangulation (default none) - N : Do not clip contours - Q : Minimum contour length - ``'[p|t]'`` - S : Skip input points outside region - ``'[p|t]'`` + levels : str + Contour file or level(s) + D : str + Dump contour coordinates + E : str + Network information + label_placement : str + Placement of labels + I : book + Color the triangles using CPT + triangular_mesh_pen : str + Pen to draw the underlying triangulation (default none) + N : bool + Do not clip contours + Q : float or str + Do not draw contours with less than cut number of points. + ``'[cut[unit]][+z]'`` + skip : bool or str + Skip input points outside region ``'[p|t]'`` {W} - X : Origin shift x - Y : Origin shift y - """ kwargs = self._preprocess(**kwargs) From c32075681c2afa7d91556a45b9e004d8508bfac7 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Wed, 3 Jun 2020 22:06:37 +1200 Subject: [PATCH 19/25] Improve docstring of text --- pygmt/base_plotting.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index e9222ca3cdc..36787d7373d 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -835,12 +835,12 @@ def text( textfiles : str or list A text data file name, or a list of filenames containing 1 or more records with (x, y[, font, angle, justify], text). - x, y : float or 1d arrays + x/y : float or 1d arrays The x and y coordinates, or an array of x and y coordinates to plot the text text : str or 1d array The text string, or an array of strings to plot on the figure - angle: int/float or bool + angle: int, float or bool Set the angle measured in degrees counter-clockwise from horizontal. E.g. 30 sets the text at 30 degrees. If no angle is given then the input textfile(s) must have this as a column. From d9a329055bc2dc523a667a02e63fb6a275dc0f86 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Wed, 3 Jun 2020 22:14:50 +1200 Subject: [PATCH 20/25] Remove short alias from image Also document the required imagefile parameter that was missing. --- pygmt/base_plotting.py | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 36787d7373d..0392fe3eccc 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -708,7 +708,7 @@ def logo(self, **kwargs): lib.call_module("logo", build_arg_string(kwargs)) @fmt_docstring - @use_alias(R="region", J="projection") + @use_alias(R="region", J="projection", D="position", F="box", M="monochrome") @kwargs_to_strings(R="sequence") def image(self, imagefile, **kwargs): """ @@ -723,17 +723,23 @@ def image(self, imagefile, **kwargs): Parameters ---------- + imagefile : str + This must be an Encapsulated PostScript (EPS) file or a raster + image. An EPS file must contain an appropriate BoundingBox. A + raster file can have a depth of 1, 8, 24, or 32 bits and is read + via GDAL. Note: If GDAL was not configured during GMT installation + then only EPS files are supported. {J} {R} - D: str + position : str ``'[g|j|J|n|x]refpoint+rdpi+w[-]width[/height][+jjustify] [+nnx[/ny]][+odx[/dy]]'`` Sets reference point on the map for the image. - F : bool or str + box : bool or str ``'[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]] [+s[[dx/dy/][shade]]]'`` Without further options, draws a rectangular border around the image using **MAP_FRAME_PEN**. - M : bool + monochrome : bool Convert color image to monochrome grayshades using the (television) YIQ-transformation. """ From d87b7e499da85f97879f3a72b4ac150328508f98 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Wed, 3 Jun 2020 22:53:57 +1200 Subject: [PATCH 21/25] Use frame instead of B for basemap. --- pygmt/base_plotting.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 0392fe3eccc..2ea86578d8f 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -643,7 +643,7 @@ def basemap(self, **kwargs): [optionally] gridlines. A simple map scale or directional rose may also be plotted. - At least one of the options *B*, *L*, or *T* must be specified. + At least one of the options *frame*, *L*, or *T* must be specified. Full option list at :gmt-docs:`basemap.html` From e3b5183ea5951098a3205c98ee9edde1cc26e9ab Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 3 Jun 2020 10:03:02 -0400 Subject: [PATCH 22/25] Fix a typo "book"->"bool" Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> --- pygmt/base_plotting.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 2ea86578d8f..87cb63532a8 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -598,7 +598,7 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs): Network information label_placement : str Placement of labels - I : book + I : bool Color the triangles using CPT triangular_mesh_pen : str Pen to draw the underlying triangulation (default none) From 15b9c6bcbb1eff4aa1ed14534f2b94f2b3777231 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Thu, 4 Jun 2020 09:05:58 +1200 Subject: [PATCH 23/25] Alias map_scale(L), rose(Td), compass(Tm) for basemap --- pygmt/base_plotting.py | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 87cb63532a8..49db1cd98c7 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -632,7 +632,15 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs): lib.call_module("contour", arg_str) @fmt_docstring - @use_alias(R="region", J="projection", B="frame", U="timestamp") + @use_alias( + R="region", + J="projection", + B="frame", + L="map_scale", + Td="rose", + Tm="compass", + U="timestamp", + ) @kwargs_to_strings(R="sequence") def basemap(self, **kwargs): """ @@ -643,7 +651,8 @@ def basemap(self, **kwargs): [optionally] gridlines. A simple map scale or directional rose may also be plotted. - At least one of the options *frame*, *L*, or *T* must be specified. + At least one of the options *frame*, *map_scale*, *rose* or *compass* + must be specified. Full option list at :gmt-docs:`basemap.html` @@ -654,13 +663,13 @@ def basemap(self, **kwargs): {J} {R} {B} - L : str + map_scale : str ``'[g|j|J|n|x]refpoint'`` Draws a simple map scale centered on the reference point specified. - Td : str + rose : str Draws a map directional rose on the map at the location defined by the reference and anchor points. - Tm : str + compass : str Draws a map magnetic rose on the map at the location defined by the reference and anchor points {U} From a1f5839fbafe70173dbfd9b83f8122469fa5fec3 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Thu, 4 Jun 2020 15:37:31 +1200 Subject: [PATCH 24/25] Change x, y to x/y in docstrings to make it look nicer --- pygmt/base_plotting.py | 4 ++-- pygmt/helpers/utils.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 49db1cd98c7..f18b1ffd454 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -475,7 +475,7 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): Parameters ---------- - x, y : float or 1d arrays + x/y : float or 1d arrays The x and y coordinates, or arrays of x and y coordinates of the data points data : str or 2d array @@ -579,7 +579,7 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs): Parameters ---------- - x, y, z : 1d arrays + x/y/z : 1d arrays Arrays of x and y coordinates and values z of the data points. data : str or 2d array Either a data file name or a 2d numpy array with the tabular data. diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 1a98d45682a..cfec19e1a57 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -29,9 +29,9 @@ def data_kind(data, x=None, y=None, z=None): ---------- data : str, 2d array, or None Data file name or numpy array. - x, y : 1d arrays or None + x/y : 1d arrays or None x and y columns as numpy arrays. - z : 1d array or None + z : 1d array or None z column as numpy array. To be used optionally when x and y are given. From 8869feb77dd64ca3a50ea301e7d2e54dbf0489ec Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 3 Jun 2020 23:59:28 -0400 Subject: [PATCH 25/25] Fix string to str in docstrings --- pygmt/base_plotting.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index f18b1ffd454..c7c85813cdf 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -266,9 +266,9 @@ def grdcontour(self, grid, **kwargs): limit : str or list of 2 ints Do no draw contours below `low` or above `high`, specify as string ``'[low]/[high]'`` or list ``[low,high]``. - cut : string or int + cut : str or int Do not draw contours with less than `cut` number of points. - resample : string or int + resample : str or int Resample smoothing factor. {J} {R}