Standardize docstrings for table-like inputs (#1186)

The virtualfile_from_data function wrapped in #961
allows for a standardized way for inputting data to
PyGMT modules. This change is for standardizing
some of the docstrings, specifically for 'table-like'
vector inputs which can be of several different
PyData object types.

* Reformat pygmt.info docstring to use table-like filler
* Reformat plot and plot3d docstring to use table-like filler
* Reformat data_kind and virtualfile_from_data docstring to use table-like filler
* Reformat rose docstring to use table-like filler
* Reformat grdtrack docstring to use table-like filler
* Reformat velo docstring to use table-like filler
* Reformat wiggle docstring to use table-like filler
* Reformat histogram docstring to use table-like filler
* Add Python list to histogram's table param description
* Use table-classes filler in docstring description
* Use fmt_docstring decorator on virtualfile_from_data function

Also had to remove curly brackets from doctest so that
they are not treated as placeholders to be substituted.

* Add a doctest for the table-classes filler text

Co-authored-by: Meghan Jones <[email protected]>
Co-authored-by: Dongdong Tian <[email protected]>

Author: 3 people

pygmt/clib/session.py

@@ -25,7 +25,7 @@
     GMTInvalidInput,
     GMTVersionError,
 )
-from pygmt.helpers import data_kind, dummy_context
+from pygmt.helpers import data_kind, dummy_context, fmt_docstring
 
 FAMILIES = [
     "GMT_IS_DATASET",
@@ -1360,6 +1360,7 @@ def virtualfile_from_grid(self, grid):
         with self.open_virtual_file(*args) as vfile:
             yield vfile
 
+    @fmt_docstring
     def virtualfile_from_data(
         self, check_kind=None, data=None, x=None, y=None, z=None, extra_arrays=None
     ):
@@ -1375,7 +1376,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
@@ -1395,20 +1396,20 @@ def virtualfile_from_data(
         >>> from pygmt.helpers import GMTTempFile
         >>> import xarray as xr
         >>> data = xr.Dataset(
-        ...     coords={"index": [0, 1, 2]},
-        ...     data_vars={
-        ...         "x": ("index", [9, 8, 7]),
-        ...         "y": ("index", [6, 5, 4]),
-        ...         "z": ("index", [3, 2, 1]),
-        ...     },
+        ...     coords=dict(index=[0, 1, 2]),
+        ...     data_vars=dict(
+        ...         x=("index", [9, 8, 7]),
+        ...         y=("index", [6, 5, 4]),
+        ...         z=("index", [3, 2, 1]),
+        ...     ),
         ... )
         >>> with Session() as ses:
         ...     with ses.virtualfile_from_data(
         ...         check_kind="vector", data=data
         ...     ) as fin:
         ...         # Send the output to a file so that we can read it
         ...         with GMTTempFile() as fout:
-        ...             ses.call_module("info", f"{fin} ->{fout.name}")
+        ...             ses.call_module("info", fin + " ->" + fout.name)
         ...             print(fout.read().strip())
         ...
         <vector memory>: N = 3 <7/9> <4/6> <1/3>

pygmt/helpers/decorators.py

@@ -188,6 +188,9 @@ def fmt_docstring(module_func):
     ...
     ...     Parameters
     ...     ----------
+    ...     data : str or {table-like}
+    ...         Pass in either a file name to an ASCII data table, a 2D
+    ...         {table-classes}.
     ...     {R}
     ...     {J}
     ...
@@ -200,6 +203,11 @@ def fmt_docstring(module_func):
     <BLANKLINE>
     Parameters
     ----------
+    data : str or numpy.ndarray or pandas.DataFrame or xarray.Dataset
+        Pass in either a file name to an ASCII data table, a 2D
+        :class:`numpy.ndarray`, a :class:`pandas.DataFrame`, or an
+        :class:`xarray.Dataset` made up of 1D :class:`xarray.DataArray`
+        data variables containing the tabular data.
     region : str or list
         *Required if this is the first plot command*.
         *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*].
@@ -224,6 +232,20 @@ def fmt_docstring(module_func):
             aliases.append("- {} = {}".format(arg, alias))
         filler_text["aliases"] = "\n".join(aliases)
 
+    filler_text["table-like"] = " or ".join(
+        [
+            "numpy.ndarray",
+            "pandas.DataFrame",
+            "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,9 @@ 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}.
     {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
+        :class:`pandas.DataFrame` inputs.
 
     spec: str
         Selects the meaning of the columns in the data file and the figure to