diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index d13cb911091..9c442be7a04 100644 --- a/pygmt/clib/session.py +++ b/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,12 +1396,12 @@ 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( @@ -1408,7 +1409,7 @@ def virtualfile_from_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()) ... : N = 3 <7/9> <4/6> <1/3> diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index e020f010d3b..f3cc66876bb 100644 --- a/pygmt/helpers/decorators.py +++ b/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): 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 diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 36a957e83f9..ec970df26a4 100644 --- a/pygmt/helpers/utils.py +++ b/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 diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index 366506a5922..df1fef1c6d3 100644 --- a/pygmt/src/grdtrack.py +++ b/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 diff --git a/pygmt/src/histogram.py b/pygmt/src/histogram.py index 52f5c923907..1db34831bb6 100644 --- a/pygmt/src/histogram.py +++ b/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} diff --git a/pygmt/src/info.py b/pygmt/src/info.py index 76ed7ea9d5e..b1c9fe715bd 100644 --- a/pygmt/src/info.py +++ 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 diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py index deac3f833ae..ca975c4c967 100644 --- a/pygmt/src/plot.py +++ b/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``. diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py index 42687165787..5b256ddbc38 100644 --- a/pygmt/src/plot3d.py +++ b/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``. diff --git a/pygmt/src/rose.py b/pygmt/src/rose.py index cd91b3d0799..dd67db6f721 100644 --- a/pygmt/src/rose.py +++ b/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 diff --git a/pygmt/src/velo.py b/pygmt/src/velo.py index 5db2544e83b..6196713b17b 100644 --- a/pygmt/src/velo.py +++ b/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 diff --git a/pygmt/src/wiggle.py b/pygmt/src/wiggle.py index 2e3235e9b64..fafa34f42e9 100644 --- a/pygmt/src/wiggle.py +++ b/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}