Correct and consistent usage of 'function, 'method', and 'class' (GenericMappingTools#2043)

yvonnefroehlich · Josh Sixsmith · commit a4e557add5c1 · 2022-12-21T17:22:17.000+11:00
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -84,7 +84,7 @@ Saving and displaying the figure
 Configuring the display settings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following module is provided directly through the :mod:`pygmt` top level
+The following function is provided directly through the :mod:`pygmt` top level
 package.
 
 .. autosummary::
@@ -95,7 +95,7 @@ package.
 Color palette table generation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following modules are provided directly through the :mod:`pygmt` top level
+The following functions are provided directly through the :mod:`pygmt` top level
 package.
 
 .. autosummary::
diff --git a/doc/contributing.md b/doc/contributing.md
@@ -392,7 +392,7 @@ Guidelines for a good tutorial:
   concise examples while the tutorials are detailed and full of text.
 * SI units should be used in the example code for tutorial plots.
 
-Note that the `Figure.show()` function needs to be called for a plot to be inserted into
+Note that the `Figure.show()` method needs to be called for a plot to be inserted into
 the documentation.
 
 ### Editing the API Documentation
@@ -576,7 +576,7 @@ returning the `pygmt.Figure` object:
 ```python
 @pytest.mark.mpl_image_compare
 def test_my_plotting_case():
-    "Test that my plotting function works"
+    "Test that my plotting method works"
     fig = Figure()
     fig.basemap(region=[0, 360, -90, 90], projection='W7i', frame=True)
     return fig
@@ -682,7 +682,7 @@ Here's an example:
 ```python
 @check_figures_equal()
 def test_my_plotting_case():
-  "Test that my plotting function works"
+  "Test that my plotting method works"
   fig_ref, fig_test = Figure(), Figure()
   fig_ref.grdimage("@earth_relief_01d_g", projection="W120/15c", cmap="geo")
   fig_test.grdimage(grid, projection="W120/15c", cmap="geo")
diff --git a/examples/gallery/3d_plots/scatter3d.py b/examples/gallery/3d_plots/scatter3d.py
@@ -8,7 +8,7 @@
 can be visualized using a perspective 3D plot. The ``region``
 parameter has to include the :math:`x`, :math:`y`, :math:`z` axis limits in the
 form of (xmin, xmax, ymin, ymax, zmin, zmax), which can be done automatically
-using :meth:`pygmt.info`. To plot the z-axis frame, set ``frame`` as a
+using :func:`pygmt.info`. To plot the z-axis frame, set ``frame`` as a
 minimum to something like ``frame=["WsNeZ", "zaf"]``. Use ``perspective`` to
 control the azimuth and elevation angle of the view, and ``zscale`` to adjust
 the vertical exaggeration factor.
diff --git a/examples/gallery/embellishments/colorbars_multiple.py b/examples/gallery/embellishments/colorbars_multiple.py
@@ -23,15 +23,15 @@
     nrows=1, ncols=2, figsize=("15c", "8c"), autolabel=True, margins="0.5c"
 ):
     # Activate the first panel so that the colormap created by the makecpt
-    # method is a panel-level CPT
+    # function is a panel-level CPT
     with fig.set_panel(panel=0):
         pygmt.makecpt(cmap="geo", series=[-8000, 8000])
         # "R?" means Winkel Tripel projection with map width automatically
         # determined from the subplot width.
         fig.grdimage(grid=grid_globe, projection="R?", region="g", frame="a")
         fig.colorbar(frame=["a4000f2000", "x+lElevation", "y+lm"])
     # Activate the second panel so that the colormap created by the makecpt
-    # method is a panel-level CPT
+    # function is a panel-level CPT
     with fig.set_panel(panel=1):
         pygmt.makecpt(cmap="globe", series=[-6000, 3000])
         # "M?" means Mercator projection with map width also automatically
diff --git a/examples/gallery/embellishments/inset.py b/examples/gallery/embellishments/inset.py
@@ -3,7 +3,7 @@
 -----
 
 The :meth:`pygmt.Figure.inset` method adds an inset figure inside a larger
-figure. The function is called using a ``with`` statement, and its
+figure. The method is called using a ``with`` statement, and its
 ``position``, ``box``, ``offset``, and ``margin`` parameters are set. Plotting
 methods called within the ``with`` statement are applied to the inset figure.
 """
diff --git a/examples/gallery/embellishments/inset_rectangle_region.py b/examples/gallery/embellishments/inset_rectangle_region.py
@@ -3,7 +3,7 @@
 --------------------------------------
 
 The :meth:`pygmt.Figure.inset` method adds an inset figure inside a larger
-figure. The function is called using a ``with`` statement, and its
+figure. The method is called using a ``with`` statement, and its
 ``position``, ``box``, ``offset``, and ``margin`` can be customized. Plotting
 methods called within the ``with`` statement plot into the inset figure.
 """
diff --git a/examples/gallery/histograms/blockm.py b/examples/gallery/histograms/blockm.py
@@ -1,7 +1,7 @@
 """
 Blockmean
 ---------
-The :meth:`pygmt.blockmean` method calculates different quantities
+The :func:`pygmt.blockmean` function calculates different quantities
 inside blocks/bins whose dimensions are defined via the ``spacing`` parameter.
 The following examples show how to calculate the averages of the given values
 inside each bin and how to report the number of points inside each bin.
diff --git a/examples/gallery/images/grdclip.py b/examples/gallery/images/grdclip.py
@@ -1,10 +1,10 @@
 """
 Clipping grid values
 --------------------
-The :meth:`pygmt.grdclip` method allows to clip defined ranges of grid values.
-In the example shown below we set all elevation values (grid points) smaller
-than 0 m (in general the bathymetric part of the grid) to a common value of
--2000 m via the ``below`` parameter.
+The :func:`pygmt.grdclip` function allows to clip defined ranges of grid
+values. In the example shown below we set all elevation values (grid points)
+smaller than 0 m (in general the bathymetric part of the grid) to a common
+value of -2000 m via the ``below`` parameter.
 """
 
 import pygmt
diff --git a/examples/gallery/images/grdgradient.py b/examples/gallery/images/grdgradient.py
@@ -1,9 +1,9 @@
 """
 Calculating grid gradient and radiance
 --------------------------------------
-The :meth:`pygmt.grdgradient` method calculates the gradient of a grid file.
+The :func:`pygmt.grdgradient` function calculates the gradient of a grid file.
 In the example shown below we will see how to calculate a hillshade map based
-on a Data Elevation Model (DEM). As input :meth:`pygmt.grdgradient` gets
+on a Data Elevation Model (DEM). As input :func:`pygmt.grdgradient` gets
 a :class:`xarray.DataArray` object or a path string to a grid file, calculates
 the respective gradient and returns it as an :class:`xarray.DataArray` object.
 We will use the ``radiance`` parameter in order to set the illumination source
diff --git a/examples/gallery/images/grdlandmask.py b/examples/gallery/images/grdlandmask.py
@@ -1,7 +1,7 @@
 """
 Create 'wet-dry' mask grid
 --------------------------
-The :meth:`pygmt.grdlandmask` method allows setting
+The :func:`pygmt.grdlandmask` function allows setting
 all nodes on land or water to a specified value using
 the ``maskvalues`` parameter.
 """
diff --git a/examples/gallery/lines/great_circles.py b/examples/gallery/lines/great_circles.py
@@ -2,7 +2,7 @@
 Generate points along great circles
 -----------------------------------
 
-The :meth:`pygmt.project` method can generate points along a great circle
+The :func:`pygmt.project` function can generate points along a great circle
 whose center and end points can be defined via the ``center`` and ``endpoint``
 parameters, respectively. Using the ``generate`` parameter allows to generate
 (*r*, *s*, *p*) points every *dist* units of *p* along a profile as
diff --git a/examples/gallery/symbols/points_categorical.py b/examples/gallery/symbols/points_categorical.py
@@ -7,8 +7,8 @@
 can be visualized. Here, we can pass the individual categories included in
 the "species" column directly to the ``color`` parameter via
 ``color=df.species.cat.codes.astype(int)``. Additionally, we have to set
-``cmap=True``. A desired colormap can be selected via the :meth:`pygmt.makecpt`
-method.
+``cmap=True``. A desired colormap can be selected via the :func:`pygmt.makecpt`
+function.
 """
 
 import pandas as pd
diff --git a/examples/get-started/first_figure.py b/examples/get-started/first_figure.py
@@ -37,10 +37,10 @@
 fig = pygmt.Figure()
 
 ###############################################################################
-# To add to a plot object (``fig`` in this example), the PyGMT module is used
-# as a method on the class. This example will use the
+# To add elements to the figure instance or object (``fig`` in this example)
+# different methods can be called on it. This example will use the
 # :meth:`pygmt.Figure.coast` method, which can be used to create a map without
-# any other methods, modules or external data. The :meth:`pygmt.Figure.coast`
+# any other methods or external data. The :meth:`pygmt.Figure.coast`
 # method plots the coastlines, borders, and bodies of water using a database
 # that is included in GMT.
 #
diff --git a/examples/tutorials/advanced/configuration.py b/examples/tutorials/advanced/configuration.py
@@ -14,10 +14,10 @@
 # ----------------------------------
 #
 # Users can override default parameters either temporarily (locally) or
-# permanently (globally) using :meth:`pygmt.config`. The full list of default
+# permanently (globally) using :class:`pygmt.config`. The full list of default
 # parameters that can be changed can be found at :gmt-docs:`gmt.conf.html`.
 #
-# We demonstrate the usage of :meth:`pygmt.config` by configuring a map plot.
+# We demonstrate the usage of :class:`pygmt.config` by configuring a map plot.
 
 # Start with a basic figure with the default style
 fig = pygmt.Figure()
diff --git a/examples/tutorials/advanced/date_time_charts.py b/examples/tutorials/advanced/date_time_charts.py
@@ -237,7 +237,7 @@
 #
 # Another way of creating charts involving datetime data can be done
 # by automatically generating the region of the plot. This can be done
-# by passing the dataframe to :meth:`pygmt.info`, which will find
+# by passing the dataframe to :func:`pygmt.info`, which will find
 # maximum and minimum values for each column and create a list
 # that could be passed as region. Additionally, the ``spacing`` argument
 # can be passed to increase the range past the maximum and minimum
diff --git a/examples/tutorials/advanced/earth_relief.py b/examples/tutorials/advanced/earth_relief.py
@@ -3,8 +3,8 @@
 =====================
 
 Plotting a map of Earth relief can use the data accessed by the
-:meth:`pygmt.datasets.load_earth_relief` method. The data can then be plotted
-using the :meth:`pygmt.Figure.grdimage` method.
+:func:`pygmt.datasets.load_earth_relief` function. The data can then be
+plotted using the :meth:`pygmt.Figure.grdimage` method.
 """
 # sphinx_gallery_thumbnail_number = 5
 
@@ -86,7 +86,7 @@
 # -------------------
 #
 # In addition to providing global data, the ``region`` parameter for
-# :meth:`pygmt.datasets.load_earth_relief` can be used to provide data for a
+# :func:`pygmt.datasets.load_earth_relief` can be used to provide data for a
 # specific area. The ``region`` parameter is required for resolutions at 5 arc
 # minutes or higher, and accepts a list (as in the example below) or a string.
 # The geographic ranges are passed as *xmin*/*xmax*/*ymin*/*ymax*.
diff --git a/examples/tutorials/advanced/grid_equalization.py b/examples/tutorials/advanced/grid_equalization.py
@@ -1,7 +1,7 @@
 """
 Performing grid histogram equalization
 ======================================
-The :meth:`pygmt.grdhisteq.equalize_grid` function creates a grid using
+The :meth:`pygmt.grdhisteq.equalize_grid` method creates a grid using
 statistics based on a cumulative distribution function.
 """
 # sphinx_gallery_thumbnail_number = 3
@@ -12,7 +12,7 @@
 # Load sample data
 # ----------------
 # Load the sample Earth relief data for a region around Yosemite valley
-# and use :meth:`pygmt.grd2xyz` to create a :class:`pandas.Series` with the
+# and use :func:`pygmt.grd2xyz` to create a :class:`pandas.Series` with the
 # z-values.
 
 grid = pygmt.datasets.load_earth_relief(
diff --git a/examples/tutorials/advanced/insets.py b/examples/tutorials/advanced/insets.py
@@ -51,7 +51,7 @@
     frame="a",
 )
 with fig.inset(position="jBL+w3c", box="+pblack+glightred"):
-    # pass is used to exit the with statement as no plotting functions are
+    # pass is used to exit the with statement as no plotting methods are
     # called
     pass
 fig.show()
@@ -81,7 +81,7 @@
 
 ###############################################################################
 #
-# Standard plotting functions can be called from within the ``inset`` context
+# Standard plotting methods can be called from within the ``inset`` context
 # manager. The example below uses :meth:`pygmt.Figure.coast` to plot a zoomed
 # out map that selectively paints the state of Massachusetts to shows its
 # location relative to other states.
@@ -105,7 +105,7 @@
     region=[-80, -65, 35, 50],
     projection="M3c",
 ):
-    # Use a plotting function to create a figure inside the inset.
+    # Use a plotting method to create a figure inside the inset.
     fig.coast(
         land="gray",
         borders=[1, 2],
diff --git a/examples/tutorials/advanced/subplots.py b/examples/tutorials/advanced/subplots.py
@@ -31,7 +31,7 @@
 # Define subplot layout
 # ---------------------
 #
-# The :meth:`pygmt.Figure.subplot` function is used to set up the layout, size,
+# The :meth:`pygmt.Figure.subplot` method is used to set up the layout, size,
 # and other attributes of the figure. It divides the whole canvas into regular
 # grid areas with *n* rows and *m* columns. Each grid area can contain an
 # individual subplot. For example:
@@ -62,8 +62,8 @@
 fig.show()
 
 ###############################################################################
-# The :meth:`pygmt.Figure.set_panel` function activates a specified subplot,
-# and all subsequent plotting functions will take place in that subplot panel.
+# The :meth:`pygmt.Figure.set_panel` method activates a specified subplot,
+# and all subsequent plotting methods will take place in that subplot panel.
 # This is similar to matplotlib's ``plt.sca`` method. In order to specify a
 # subplot, you will need to provide the identifier for that subplot via the
 # ``panel`` parameter. Pass in either the *index* number, or a tuple/list like
@@ -145,7 +145,7 @@
 ###############################################################################
 # .. note::
 #
-#     All plotting functions (e.g. :meth:`pygmt.Figure.coast`,
+#     All plotting methods (e.g. :meth:`pygmt.Figure.coast`,
 #     :meth:`pygmt.Figure.text`, etc) are able to use ``panel`` parameter when
 #     in subplot mode. Once a panel is activated using ``panel`` or
 #     :meth:`pygmt.Figure.set_panel`, subsequent plotting commands that don't
diff --git a/examples/tutorials/advanced/vectors.py b/examples/tutorials/advanced/vectors.py
@@ -22,7 +22,7 @@
 # The angle is measured in degrees and moves counter-clockwise from the
 # horizontal.
 # The length of the vector uses centimeters by default but
-# could be changed using :meth:`pygmt.config`
+# could be changed using :class:`pygmt.config`
 # (Check the next examples for unit changes).
 #
 # Notice that the ``v`` in the ``style`` parameter stands for
diff --git a/examples/tutorials/basics/plot.py b/examples/tutorials/basics/plot.py
@@ -74,7 +74,7 @@
 # even use the new matplotlib colormap "viridis". Here, we first create a
 # continuous colormap ranging from the minimum depth to the maximum depth of
 # the earthquakes using :func:`pygmt.makecpt`, then set ``cmap=True`` in
-# :func:`pygmt.Figure.plot` to use the colormap. At the end of the plot, we
+# :meth:`pygmt.Figure.plot` to use the colormap. At the end of the plot, we
 # also plot a colorbar showing the colormap used in the plot.
 #
 
diff --git a/examples/tutorials/basics/regions.py b/examples/tutorials/basics/regions.py
@@ -2,7 +2,7 @@
 Setting the region
 ==================
 
-Many of the plotting functions take the ``region`` parameter, which sets the
+Many of the plotting methods take the ``region`` parameter, which sets the
 area that will be shown in the figure. This tutorial covers the different types
 of inputs that it can accept.
 """
diff --git a/pygmt/figure.py b/pygmt/figure.py
@@ -146,7 +146,7 @@ def psconvert(self, icc_gray=False, **kwargs):
         PDF, PNG, PPM, SVG, TIFF) using Ghostscript.
 
         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
+        (see :class:`pygmt.Figure`). In this case, an output name must be given
         using parameter *prefix*.
 
         Full option list at :gmt-docs:`psconvert.html`
diff --git a/pygmt/src/grd2cpt.py b/pygmt/src/grd2cpt.py
@@ -33,7 +33,7 @@ def grd2cpt(grid, **kwargs):
     r"""
     Make GMT color palette tables from a grid file.
 
-    This is a method that will help you make static color palette tables
+    This is a function that will help you make static color palette tables
     (CPTs). By default, the CPT will simply be saved to the current session,
     but you can use ``output`` to save it to a file. The CPT is based on an
     existing dynamic master CPT of your choice, and the mapping from data value
@@ -61,7 +61,7 @@ def grd2cpt(grid, **kwargs):
     ``overrule_bg`` or ``no_bg``.
 
     The color model (RGB, HSV or CMYK) of the palette created by
-    :meth:`pygmt.grd2cpt` will be the same as specified in the header of the
+    :func:`pygmt.grd2cpt` will be the same as specified in the header of the
     master CPT. When there is no :gmt-term:`COLOR_MODEL` entry in the master
     CPT, the :gmt-term:`COLOR_MODEL` specified in the
     :gmt-docs:`gmt.conf <gmt.conf>` file or the ``color_model`` option will be
diff --git a/pygmt/src/grdcut.py b/pygmt/src/grdcut.py
@@ -34,7 +34,7 @@ def grdcut(grid, **kwargs):
     Produce a new ``outgrid`` file which is a subregion of ``grid``. The
     subregion is specified with ``region``; the specified range must not exceed
     the range of ``grid`` (but see ``extend``). If in doubt, run
-    :meth:`pygmt.grdinfo` to check range. Alternatively, define the subregion
+    :func:`pygmt.grdinfo` to check range. Alternatively, define the subregion
     indirectly via a range check on the node values or via distances from a
     given point. Finally, you can give ``projection`` for oblique projections
     to determine the corresponding rectangular ``region`` that will give a grid
diff --git a/pygmt/src/grdhisteq.py b/pygmt/src/grdhisteq.py
diff --git a/pygmt/src/grdimage.py b/pygmt/src/grdimage.py
diff --git a/pygmt/src/grdinfo.py b/pygmt/src/grdinfo.py
diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py
diff --git a/pygmt/src/inset.py b/pygmt/src/inset.py
diff --git a/pygmt/src/makecpt.py b/pygmt/src/makecpt.py
diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
diff --git a/pygmt/src/x2sys_cross.py b/pygmt/src/x2sys_cross.py
diff --git a/pygmt/src/x2sys_init.py b/pygmt/src/x2sys_init.py
