Standardize docstrings for table-like inputs

pygmt/clib/session.py

@@ -1375,7 +1375,7 @@ def virtualfile_from_data(
         check_kind : str
             Used to validate the type of data that can be passed in. Choose
             from 'raster', 'vector' or None. Default is None (no validation).
-        data : str, xarray.DataArray, 2d array, or None
+        data : str or xarray.DataArray or {table-like} or None
             Any raster or vector data format. This could be a file name, a
             raster grid, a vector matrix/arrays, or other supported data input.
         x/y/z : 1d arrays or None

pygmt/helpers/decorators.py

@@ -188,6 +188,7 @@ def fmt_docstring(module_func):
     ...
     ...     Parameters
     ...     ----------
+    ...     data : {table-like}
     ...     {R}
     ...     {J}
     ...
@@ -200,6 +201,7 @@ def fmt_docstring(module_func):
     <BLANKLINE>
     Parameters
     ----------
+    data : numpy.ndarray or pandas.DataFrame or xarray.Dataset
     region : str or list
         *Required if this is the first plot command*.
         *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*].
@@ -224,6 +226,18 @@ def fmt_docstring(module_func):
             aliases.append("- {} = {}".format(arg, alias))
         filler_text["aliases"] = "\n".join(aliases)
 
+    filler_text["table-like"] = (
+        "numpy.ndarray or "
+        "pandas.DataFrame or "
+        "xarray.Dataset"
+        # "geopandas.GeoDataFrame"
+    )
+    filler_text["table-classes"] = (
+        ":class:`numpy.ndarray`, a :class:`pandas.DataFrame`, or an \n"
+        "    :class:`xarray.Dataset` made up of 1D :class:`xarray.DataArray` \n"
+        "    data variables containing the tabular data."
+    )
+
     for marker, text in COMMON_OPTIONS.items():
         # Remove the indentation and the first line break from the multiline
         # strings so that it doesn't mess up the original docstring

pygmt/helpers/utils.py

@@ -30,8 +30,10 @@ def data_kind(data, x=None, y=None, z=None):
 
     Parameters
     ----------
-    data : str, xarray.DataArray, 2d array, or None
-       Data file name, xarray.DataArray or numpy array.
+    data : str or xarray.DataArray or {table-like} or None
+        Pass in either a file name to an ASCII data table, an
+        :class:`xarray.DataArray`, a 1D/2D
+        {table-classes}.
     x/y : 1d arrays or None
         x and y columns as numpy arrays.
     z : 1d array or None

pygmt/src/grdtrack.py

@@ -35,10 +35,9 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs):
 
     Parameters
     ----------
-    points : pandas.DataFrame or str
-        Either a table with (x, y) or (lon, lat) values in the first two
-        columns, or a filename (e.g. csv, txt format). More columns may be
-        present.
+    points : str or {table-like}
+        Pass in either a file name to an ASCII data table, a 2D
+        {table-classes}.
 
     grid : xarray.DataArray or str
         Gridded array from which to sample values from, or a filename (netcdf

pygmt/src/histogram.py

@@ -44,8 +44,10 @@ def histogram(self, table, **kwargs):
 
     Parameters
     ----------
-    table : str, list, or 1d array
-        A data file name, list, or 1d numpy array. This is a required argument.
+    table : str or list or {table-like}
+        Pass in either a file name to an ASCII data table, a Python list, a 2D
+        {table-classes}.
+        This is a required argument.
     {J}
     {R}
     {B}

pygmt/src/info.py

@@ -46,10 +46,9 @@ def info(table, **kwargs):
 
     Parameters
     ----------
-    table : str or np.ndarray or pandas.DataFrame or xarray.Dataset
-        Pass in either a file name to an ASCII data table, a 1D/2D numpy array,
-        a pandas dataframe, or an xarray dataset made up of 1D xarray.DataArray
-        data variables.
+    table : str or {table-like}
+        Pass in either a file name to an ASCII data table, a 1D/2D
+        {table-classes}.
     per_column : bool
         Report the min/max values per column in separate columns.
     spacing : str

pygmt/src/plot.py

@@ -76,10 +76,11 @@ def plot(self, x=None, y=None, data=None, size=None, direction=None, **kwargs):
     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
-        Either a data file name or a 2d numpy array with the tabular data.
-        Use parameter ``columns`` to choose which columns are x, y, color,
-        and size, respectively.
+    data : str or {table-like}
+        Pass in either a file name to an ASCII data table, a 2D
+        {table-classes}.
+        Use parameter ``columns`` to choose which columns are x, y, color, and
+        size, respectively.
     size : 1d array
         The size of the data points in units specified using ``style``.
         Only valid if using ``x``/``y``.

pygmt/src/plot3d.py

@@ -78,10 +78,11 @@ def plot3d(
     x/y/z : float or 1d arrays
         The x, y, and z coordinates, or arrays of x, y and z coordinates of
         the data points
-    data : str or 2d array
-        Either a data file name or a 2d numpy array with the tabular data.
-        Use parameter ``columns`` to choose which columns are x, y, z,
-        color, and size, respectively.
+    data : str or {table-like}
+        Pass in either a file name to an ASCII data table, a 2D
+        {table-classes}.
+        Use parameter ``columns`` to choose which columns are x, y, z, color,
+        and size, respectively.
     size : 1d array
         The size of the data points in units specified in ``style``.
         Only valid if using ``x``/``y``/``z``.

pygmt/src/rose.py

@@ -59,13 +59,13 @@ def rose(self, length=None, azimuth=None, data=None, **kwargs):
         Length and azimuth values, or arrays of length and azimuth
         values
 
-    data : str or 2d array
-        Either a data file name or a 2d numpy array with the tabular data.
-        Use option ``columns`` to choose which columns are length and
-        azimuth, respectively. If a file with only azimuths is given,
-        use ``columns`` to indicate the single column with azimuths; then
-        all lengths are set to unity (see ``scale = 'u'`` to set actual
-        lengths to unity as well).
+    data : str or {table-like}
+        Pass in either a file name to an ASCII data table, a 2D
+        {table-classes}.
+        Use option ``columns`` to choose which columns are length and azimuth,
+        respectively. If a file with only azimuths is given, use ``columns`` to
+        indicate the single column with azimuths; then all lengths are set to
+        unity (see ``scale = 'u'`` to set actual lengths to unity as well).
 
     orientation : bool
         Specifies that the input data are orientation data (i.e., have a

pygmt/src/velo.py

@@ -53,10 +53,11 @@ def velo(self, data=None, **kwargs):
 
     Parameters
     ----------
-    data : str or numpy.ndarray or pandas.DataFrame
-        Either a file name, a 2D :class:`numpy.ndarray` or a
-        :class:`pandas.DataFrame` with the tabular data. Note that text columns
-        are only supported with file or pandas DataFrame inputs.
+    data : str or {table-like}
+        Pass in either a file name to an ASCII data table, a 2D
+        {table-classes}.
+        Note that text columns are only supported with file or pandas DataFrame
+        inputs.
 
     spec: str
         Selects the meaning of the columns in the data file and the figure to

pygmt/src/wiggle.py

@@ -41,8 +41,9 @@ def wiggle(self, x=None, y=None, z=None, data=None, **kwargs):
     ----------
     x/y/z : 1d arrays
         The arrays of x and y coordinates and z data points.
-    data : str or 2d array
-        Either a data file name or a 2d numpy array with the tabular data.
+    data : str or {table-like}
+        Pass in either a file name to an ASCII data table, a 2D
+        {table-classes}.
         Use parameter ``columns`` to choose which columns are x, y, z,
         respectively.
     {J}