Use "general" verb form in docstrings (#2376)

Author: yvonnefroehlich

pygmt/figure.py

@@ -209,10 +209,10 @@ def psconvert(self, **kwargs):
         anti_aliasing : str
             [**g**\|\ **p**\|\ **t**\][**1**\|\ **2**\|\ **4**].
             Set the anti-aliasing options for **g**\ raphics or **t**\ ext.
-            Append the size of the subsample box (1, 2, or 4) [4]. [Default is
-            no anti-aliasing (same as bits = 1)].
+            Append the size of the subsample box (1, 2, or 4) [Default is
+            ``"4"``]. [Default is no anti-aliasing (same as bits = 1).]
         fmt : str
-            Sets the output format, where **b** means BMP, **e** means EPS,
+            Set 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
@@ -273,21 +273,21 @@ def savefig(
             The desired figure file name, including the extension. See the list
             of supported formats and their extensions above.
         transparent : bool
-            If True, will use a transparent background for the figure. Only
-            valid for PNG format.
+            If ``True``, will use a transparent background for the figure.
+            Only valid for PNG format.
         crop : bool
-            If True, will crop the figure canvas (page) to the plot area.
+            If ``True``, will crop the figure canvas (page) to the plot area.
         anti_alias: bool
-            If True, will use anti aliasing when creating raster images (PNG,
-            JPG, TIFF). More specifically, it passes arguments ``t2``
+            If ``True``, will use anti-aliasing when creating raster images
+            (PNG, JPG, TIFF). More specifically, it passes arguments ``t2``
             and ``g2`` to the ``anti_aliasing`` parameter of
             :meth:`pygmt.Figure.psconvert`. Ignored if creating vector
             graphics.
         show: bool
-            If True, will open the figure in an external viewer.
+            If ``True``, will open the figure in an external viewer.
         dpi : int
-            Set raster resolution in dpi. Default is 720 for PDF, 300 for
-            others.
+            Set raster resolution in dpi [Default is ``720`` for PDF, ``300``
+            for others].
         **kwargs : dict
             Additional keyword arguments passed to
             :meth:`pygmt.Figure.psconvert`. Valid parameters are ``gs_path``,

pygmt/helpers/decorators.py

@@ -29,7 +29,7 @@
             [**s**\|\ **S**]][**+l**\|\ **r**][**+p**\ *percent*].
             Features with an area smaller than *min_area* in km\ :sup:`2` or of
             hierarchical level that is lower than *min_level* or higher than
-            *max_level* will not be plotted [Default is 0/0/4 (all
+            *max_level* will not be plotted [Default is ``"0/0/4"`` (all
             features)].""",
     "frame": r"""
         frame : bool or str or list
@@ -305,13 +305,13 @@
             [**x**\|\ **y**\|\ **z**]\ *azim*\[/*elev*\[/*zlevel*]]\
             [**+w**\ *lon0*/*lat0*\[/*z0*]][**+v**\ *x0*/*y0*].
             Select perspective view and set the azimuth and elevation angle of
-            the viewpoint. Default is [180, 90]. Full documentation is at
+            the viewpoint [Default is ``[180, 90]``]. Full documentation is at
             :gmt-docs:`gmt.html#perspective-full`.
         """,
     "registration": r"""
         registration : str
             **g**\|\ **p**.
-            Force gridline (**g**) or pixel (**p**) node registration.
+            Force gridline (**g**) or pixel (**p**) node registration
             [Default is **g**\ (ridline)].
         """,
     "skiprows": r"""
@@ -333,7 +333,7 @@
     "transparency": r"""
         transparency : int or float
             Set transparency level, in [0-100] percent range
-            [Default is 0, i.e., opaque].
+            [Default is ``0``, i.e., opaque].
             Only visible when PDF or raster format output is selected.
             Only the PNG format selection adds a transparency layer
             in the image (for further processing). """,

pygmt/src/basemap.py

@@ -54,11 +54,11 @@ def basemap(self, **kwargs):
     map_scale : str
         [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
         **+w**\ *length*.
-        Draws a simple map scale centered on the reference point specified.
+        Draw a simple map scale centered on the reference point specified.
     box : bool or str
         [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
         [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
-        If set to ``True``, draws a rectangular border around the
+        If set to ``True``, draw a rectangular border around the
         map scale or rose. Alternatively, specify a different pen with
         **+p**\ *pen*. Add **+g**\ *fill* to fill the scale panel [Default is
         no fill]. Append **+c**\ *clearance* where *clearance* is either gap,
@@ -71,14 +71,14 @@ def basemap(self, **kwargs):
         radius. You can override this radius by appending another value.
         Finally, append **+s** to draw an offset background shaded region.
         Here, *dx/dy* indicates the shift relative to the foreground frame
-        [Default is 4p/-4p] and shade sets the fill style to use for shading
-        [Default is gray50].
+        [Default is ``"4p/-4p"``] and shade sets the fill style to use for
+        shading [Default is ``"gray50"``].
     rose : str
-        Draws a map directional rose on the map at the location defined by
+        Draw a map directional rose on the map at the location defined by
         the reference and anchor points.
     compass : str
-        Draws a map magnetic rose on the map at the location defined by the
-        reference and anchor points
+        Draw a map magnetic rose on the map at the location defined by the
+        reference and anchor points.
     {verbose}
     {panel}
     {coltypes}

pygmt/src/binstats.py

@@ -84,7 +84,7 @@ def binstats(data, **kwargs):
         Normalize the resulting grid values by the area represented by the
         search *radius* [no normalization].
     search_radius : float or str
-        Sets the *search_radius* that determines which data points are
+        Set the *search_radius* that determines which data points are
         considered close to a node. Append the distance unit.
         Not compatible with ``tiling``.
     weight : str

pygmt/src/coast.py

@@ -76,7 +76,7 @@ def coast(self, **kwargs):
         strings in a list.
     resolution : str
         **f**\|\ **h**\|\ **i**\|\ **l**\|\ **c**.
-        Selects the resolution of the data set to: (**f**\ )ull,
+        Select the resolution of the data set to: (**f**\ )ull,
         (**h**\ )igh, (**i**\ )ntermediate, (**l**\ )ow,
         and (**c**\ )rude.
     land : str
@@ -127,7 +127,7 @@ def coast(self, **kwargs):
     map_scale : str
         [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
         **+w**\ *length*.
-        Draws a simple map scale centered on the reference point specified.
+        Draw a simple map scale centered on the reference point specified.
     borders : int or str or list
         *border*\ [/*pen*].
         Draw political boundaries. Specify the type of boundary and

pygmt/src/colorbar.py

@@ -54,7 +54,7 @@ def colorbar(self, **kwargs):
         [**+h**\|\ **v**][**+j**\ *justify*]\
         [**+m**\ [**a**\|\ **c**\|\ **l**\|\ **u**]]\
         [**+n**\ [*txt*]][**+o**\ *dx*\ [/*dy*]].
-        Defines the reference point on the map for the color scale using one of
+        Define the reference point on the map for the color scale using one of
         four coordinate systems: (1) Use **g** for map (user) coordinates, (2)
         use **j** or **J** for setting *refpoint* via a 2-character
         justification code that refers to the (invisible) map domain rectangle,
@@ -71,7 +71,7 @@ def colorbar(self, **kwargs):
     box : bool or str
         [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
         [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
-        If set to ``True``, draws a rectangular border around the color scale.
+        If set to ``True``, draw a rectangular border around the color scale.
         Alternatively, specify a different pen with **+p**\ *pen*. Add
         **+g**\ *fill* to fill the scale panel [Default is no fill]. Append
         **+c**\ *clearance* where *clearance* is either gap, xgap/ygap, or

pygmt/src/contour.py

@@ -83,13 +83,13 @@ def contour(self, data=None, x=None, y=None, z=None, **kwargs):
     I : bool
         Color the triangles using CPT.
     triangular_mesh_pen : str
-        Pen to draw the underlying triangulation [Default is None].
+        Pen to draw the underlying triangulation [Default is ``None``].
     no_clip : bool
-        Do NOT clip contours or image at the boundaries [Default will clip
-        to fit inside region].
+        Do **not** clip contours or image at the frame boundaries
+        [Default is ``False`` to fit inside ``region``].
     Q : float or str
         [*cut*][**+z**].
-        Do not draw contours with less than cut number of points.
+        Do not draw contours with less than *cut* number of points.
     skip : bool or str
         [**p**\|\ **t**].
         Skip input points outside region.

pygmt/src/dimfilter.py

@@ -77,7 +77,7 @@ def dimfilter(grid, **kwargs):
           calculation.
     filter : str
         **x**\ *width*\ [**+l**\|\ **u**].
-        Sets the primary filter type. Choose among convolution and
+        Set the primary filter type. Choose among convolution and
         non-convolution filters. Use the filter code **x** followed by
         the full diameter *width*. Available convolution filters are:
 
@@ -94,7 +94,7 @@ def dimfilter(grid, **kwargs):
           to return the smallest or largest of each sector's modal values.
     sectors : str
         **x**\ *sectors*\ [**+l**\|\ **u**]
-        Sets the secondary filter type **x** and the number of bow-tie sectors.
+        Set the secondary filter type **x** and the number of bow-tie sectors.
         *sectors* must be integer and larger than 0. When *sectors* is
         set to 1, the secondary filter is not effective. Available secondary
         filters **x** are:
@@ -108,14 +108,14 @@ def dimfilter(grid, **kwargs):
           value. Append **+l** or **+h** to the sectors if you rather want to
           return the smallest or largest of the modal values.
     spacing : str or list
-        *x_inc* [and optionally *y_inc*] is the output Increment. Append
+        *x_inc* [and optionally *y_inc*] is the output increment. Append
         **m** to indicate minutes, or **c** to indicate seconds. If the new
         *x_inc*, *y_inc* are NOT integer multiples of the old ones (in the
-        input data), filtering will be considerably slower. [Default: Same
+        input data), filtering will be considerably slower. [Default is same
         as input.]
     region : str or list
         [*xmin*, *xmax*, *ymin*, *ymax*].
-        Defines the region of the output points. [Default: Same as input.]
+        Define the region of the output points [Default is same as input].
     {verbose}
 
     Returns

pygmt/src/filter1d.py

@@ -35,7 +35,7 @@ def filter1d(data, output_type="pandas", outfile=None, **kwargs):
     ----------
     filter_type : str
         **type**\ *width*\ [**+h**].
-        Sets the filter **type**. Choose among convolution and non-convolution
+        Set the filter **type**. Choose among convolution and non-convolution
         filters. Append the filter code followed by the full filter
         *width* in same units as time column. By default, this
         performs a low-pass filtering; append **+h** to select high-pass
@@ -82,9 +82,9 @@ def filter1d(data, output_type="pandas", outfile=None, **kwargs):
         half the filter-width of data at each end.
 
     time_col : int
-        Indicates which column contains the independent variable (time). The
+        Indicate which column contains the independent variable (time). The
         left-most column is 0, while the right-most is (*n_cols* - 1)
-        [Default is 0].
+        [Default is ``0``].
 
     output_type : str
         Determine the format the xyz data will be returned in [Default is

pygmt/src/grd2cpt.py

@@ -78,11 +78,11 @@ def grd2cpt(grid, **kwargs):
     grid : str or xarray.DataArray
         The file name of the input grid or the grid loaded as a DataArray.
     transparency : int or float or str
-        Sets a constant level of transparency (0-100) for all color slices.
+        Set a constant level of transparency (0-100) for all color slices.
         Append **+a** to also affect the foreground, background, and NaN
-        colors [Default is no transparency, i.e., 0 (opaque)].
+        colors [Default is no transparency, i.e., ``0`` (opaque)].
     cmap : str
-        Selects the master color palette table (CPT) to use in the
+        Select 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
@@ -111,10 +111,10 @@ def grd2cpt(grid, **kwargs):
         to resample the color table into *nlevels* equidistant slices.
     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
+        Define 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
+        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`.

pygmt/src/grdgradient.py

@@ -125,15 +125,15 @@ def grdgradient(grid, **kwargs):
         all nodes after gradient calculations are completed.
     tiles : str
         **c**\|\ **r**\|\ **R**.
-        Controls how normalization via ``normalize`` is carried out.  When
-        multiple  grids should be normalized the same way (i.e., with the same
-        *offset*  and/or *sigma*),
-        we must pass these values via ``normalize``.  However, this is
-        inconvenient if we compute these values from a grid.  Use **c** to
-        save  the results  of *offset* and *sigma* to a statistics file; if
-        grid output is not  needed for this run then do not specify
-        ``outgrid``. For  subsequent runs,  just use **r** to read these
-        values.  Using **R**  will read then delete the statistics file.
+        Control how normalization via ``normalize`` is carried out. When
+        multiple grids should be normalized the same way (i.e., with the same
+        *offset* and/or *sigma*),
+        we must pass these values via ``normalize``. However, this is
+        inconvenient if we compute these values from a grid. Use **c** to
+        save the results of *offset* and *sigma* to a statistics file; if
+        grid output is not needed for this run then do not specify
+        ``outgrid``. For subsequent runs, just use **r** to read these
+        values. Using **R** will read then delete the statistics file.
     {region}
     slope_file : str
         Name of output grid file with scalar magnitudes of gradient vectors.

pygmt/src/grdhisteq.py

@@ -84,10 +84,10 @@ def _grdhisteq(grid, output_type, **kwargs):
             The name of the output ASCII file to store the results of the
             histogram equalization in.
         output_type: str
-            Determines the output type. Use "file", "xarray", "pandas", or
+            Determine the output type. Use "file", "xarray", "pandas", or
             "numpy".
         divisions : int
-            Set the number of divisions of the data range [Default is 16].
+            Set the number of divisions of the data range [Default is ``16``].
 
         {region}
         {verbose}

pygmt/src/grdimage.py

@@ -112,11 +112,12 @@ def grdimage(self, grid, **kwargs):
         to project a raw image (an image without referencing coordinates).
     dpi : int
         [**i**\|\ *dpi*].
-        Sets the resolution of the projected grid that will be created if a
-        map projection other than Linear or Mercator was selected [100]. By
-        default, the projected grid will be of the same size (rows and
-        columns) as the input file. Specify **i** to use the PostScript
-        image operator to interpolate the image at the device resolution.
+        Set the resolution of the projected grid that will be created if a
+        map projection other than Linear or Mercator was selected [Default
+        is ``100`` dpi]. By default, the projected grid will be of the
+        same size (rows and columns) as the input file. Specify **i** to
+        use the PostScript image operator to interpolate the image at the
+        device resolution.
     bit_color : str
         *color*\ [**+b**\|\ **f**\].
         This parameter only applies when a resulting 1-bit image otherwise
@@ -145,8 +146,8 @@ def grdimage(self, grid, **kwargs):
         Force conversion to monochrome image using the (television) YIQ
         transformation. Cannot be used with ``nan_transparent``.
     no_clip : bool
-        Do not clip the image at the map boundary (only relevant for
-        non-rectangular maps).
+        Do **not** clip the image at the frame boundaries (only relevant
+        for non-rectangular maps) [Default is ``False``].
     nan_transparent : bool
         Make grid nodes with z = NaN transparent, using the color-masking
         feature in PostScript Level 3 (the PS device must support PS Level

pygmt/src/grdinfo.py

@@ -43,7 +43,7 @@ def grdinfo(grid, **kwargs):
     {region}
     per_column : str or bool
         **n**\|\ **t**.
-        Formats the report using tab-separated fields on a single line. The
+        Format the report using tab-separated fields on a single line. The
         output is name *w e s n z0 z1 dx dy nx ny* [ *x0 y0 x1 y1* ]
         [ *med scale* ] [ *mean std rms* ] [ *n_nan* ] *registration gtype*.
         The data in brackets are outputted depending on the ``force_scan``

pygmt/src/grdlandmask.py

@@ -52,7 +52,7 @@ def grdlandmask(**kwargs):
     {region}
     {area_thresh}
     resolution : str
-        *res*\[\ **+f**\]. Selects the resolution of the data set to use
+        *res*\[\ **+f**\]. Select the resolution of the data set to use
         ((**f**)ull, (**h**)igh, (**i**)ntermediate, (**l**)ow, or
         (**c**)rude). The resolution drops off by ~80% between data sets.
         [Default is **l**]. Append **+f** to automatically select a lower
@@ -77,7 +77,7 @@ def grdlandmask(**kwargs):
         ponds-in-islands-in-lakes outlines [Default is no line tracing].
     maskvalues : str or list
         [*wet*, *dry*] or [*ocean*, *land*, *lake*, *island*, *pond*].
-        Sets the values that will be assigned to nodes. Values can
+        Set the values that will be assigned to nodes. Values can
         be any number, including the textstring NaN
         [Default is [0, 1, 0, 1, 0] (i.e., [0, 1])]. Also select
         ``bordervalues`` to let nodes exactly on feature boundaries be