From 0267dd15c7626f5903cdb5a3e12ca545d70c884a Mon Sep 17 00:00:00 2001 From: Wei Ji <23487320+weiji14@users.noreply.github.com> Date: Thu, 4 Jun 2020 16:32:22 +1200 Subject: [PATCH] Turn all short aliases into long form (#474) 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, and moving on to all others spread across the API Reference page. Co-authored-by: Dongdong Tian --- pygmt/base_plotting.py | 152 +++++++++++++++++++++--------------- pygmt/figure.py | 41 ++++++---- pygmt/gridding.py | 8 +- pygmt/helpers/decorators.py | 43 ++++++---- pygmt/helpers/utils.py | 4 +- pygmt/mathops.py | 24 +++--- pygmt/modules.py | 17 ++-- pygmt/sampling.py | 28 ++++--- pygmt/tests/test_info.py | 31 ++++---- pygmt/tests/test_which.py | 4 +- 10 files changed, 206 insertions(+), 146 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 06d4dd43bd5..c7c85813cdf 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): @@ -100,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 @@ -108,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. @@ -166,23 +167,24 @@ 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 - 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. - box (F) : bool or str + 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 border around the color scale. Alternatively, specify a different @@ -198,12 +200,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. @@ -223,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") @@ -241,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 @@ -251,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``. @@ -261,17 +263,18 @@ 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 : str or int Do not draw contours with less than `cut` number of points. - S : string or int + resample : str or int Resample smoothing factor. {J} {R} {B} {G} + {U} {W} """ kwargs = self._preprocess(**kwargs) @@ -439,6 +442,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): @@ -471,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 @@ -501,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) @@ -575,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. @@ -586,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 : bool + 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) @@ -623,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") + @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): """ @@ -634,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 *B*, *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` @@ -645,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} @@ -664,7 +682,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", D="position", F="box") @kwargs_to_strings(R="sequence") def logo(self, **kwargs): """ @@ -683,10 +701,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} @@ -699,7 +717,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): """ @@ -714,17 +732,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. """ @@ -758,12 +782,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 @@ -826,12 +850,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. 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) 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. diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 391a1af2c35..0e7933ea36c 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -14,31 +14,41 @@ 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 + timestamp : 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.""", + "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""", } @@ -55,13 +65,14 @@ 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}``: timestamp (insert time stamp logo) + * ``{CPT}``: cmap (the color palette table) + * ``{G}``: color + * ``{W}``: pen + * ``{n}``: interpolation Parameters ---------- @@ -96,11 +107,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. 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. 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: diff --git a/pygmt/modules.py b/pygmt/modules.py index 02bcb3ba299..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*. @@ -117,7 +120,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/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 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" 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