Skip to content

Commit

Permalink
Update docstrings links for return classes (GenericMappingTools#954)
Browse files Browse the repository at this point in the history
This PR adds links to xarray, pandas, and numpy classes in the Returns 
section of the docstrings. It also includes a few small fixes according 
to the conventions set in GenericMappingTools#631.

Co-authored-by: Dongdong Tian <[email protected]>
  • Loading branch information
2 people authored and Josh Sixsmith committed Dec 21, 2022
1 parent 122f8c7 commit c7ec319
Show file tree
Hide file tree
Showing 5 changed files with 32 additions and 26 deletions.
8 changes: 5 additions & 3 deletions pygmt/src/blockmedian.py
Original file line number Diff line number Diff line change
Expand Up @@ -56,10 +56,12 @@ def blockmedian(table, outfile=None, **kwargs):
Returns
-------
output : pandas.DataFrame or None
Return type depends on whether the outfile parameter is set:
Return type depends on whether the ``outfile`` parameter is set:
- pandas.DataFrame table with (x, y, z) columns if outfile is not set
- None if outfile is set (filtered output will be stored in outfile)
- :class:`pandas.DataFrame` table with (x, y, z) columns if ``outfile``
is not set
- None if ``outfile`` is set (filtered output will be stored in file
set by ``outfile``)
"""
kind = data_kind(table)
with GMTTempFile(suffix=".csv") as tmpfile:
Expand Down
17 changes: 9 additions & 8 deletions pygmt/src/grdcut.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,13 @@ def grdcut(grid, **kwargs):
Extract subregion from a grid.
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
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
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* setting that will give a
grid that fully covers the oblique domain.
given point. Finally, you can give ``projection`` for oblique projections
to determine the corresponding rectangular ``region`` that will give a grid
that fully covers the oblique domain.
Full option list at :gmt-docs:`grdcut.html`
Expand Down Expand Up @@ -83,10 +83,11 @@ def grdcut(grid, **kwargs):
Returns
-------
ret: xarray.DataArray or None
Return type depends on whether the *outgrid* parameter is set:
Return type depends on whether the ``outgrid`` parameter is set:
- xarray.DataArray if *outgrid* is not set
- None if *outgrid* is set (grid output will be stored in *outgrid*)
- :class:`xarray.DataArray` if ``outgrid`` is not set
- None if ``outgrid`` is set (grid output will be stored in file set by
``outgrid``)
"""
kind = data_kind(grid)

Expand Down
8 changes: 5 additions & 3 deletions pygmt/src/grdfilter.py
Original file line number Diff line number Diff line change
Expand Up @@ -115,9 +115,11 @@ def grdfilter(grid, **kwargs):
Returns
-------
ret: xarray.DataArray or None
Return type depends on whether the *outgrid* parameter is set:
- xarray.DataArray if *outgrid* is not set
- None if *outgrid* is set (grid output will be stored in *outgrid*)
Return type depends on whether the ``outgrid`` parameter is set:
- :class:`xarray.DataArray` if ``outgrid`` is not set
- None if ``outgrid`` is set (grid output will be stored in file set by
``outgrid``)
Examples
--------
Expand Down
19 changes: 10 additions & 9 deletions pygmt/src/grdtrack.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs):
table with the interpolated values added as (one or more) new columns. A
bicubic [Default], bilinear, B-spline or nearest-neighbor interpolation is
used, requiring boundary conditions at the limits of the region (see
*interpolation*; Default uses “natural” conditions (second partial
``interpolation``; Default uses “natural” conditions (second partial
derivative normal to edge is zero) unless the grid is automatically
recognized as periodic.)
Expand All @@ -46,12 +46,12 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs):
format).
newcolname : str
Required if 'points' is a pandas.DataFrame. The name for the new column
in the track pandas.DataFrame table where the sampled values will be
placed.
Required if ``points`` is a :class:`pandas.DataFrame`. The name for the
new column in the track :class:`pandas.DataFrame` table where the
sampled values will be placed.
outfile : str
Required if 'points' is a file. The file name for the output ASCII
Required if ``points`` is a file. The file name for the output ASCII
file.
{V}
Expand All @@ -61,11 +61,12 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs):
Returns
-------
track: pandas.DataFrame or None
Return type depends on whether the outfile parameter is set:
Return type depends on whether the ``outfile`` parameter is set:
- pandas.DataFrame table with (x, y, ..., newcolname) if outfile is not
set
- None if outfile is set (track output will be stored in outfile)
- :class:`pandas.DataFrame` table with (x, y, ..., newcolname) if
``outfile`` is not set
- None if ``outfile`` is set (track output will be stored in file set
by ``outfile``)
"""

with GMTTempFile(suffix=".csv") as tmpfile:
Expand Down
6 changes: 3 additions & 3 deletions pygmt/src/info.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,8 @@ def info(table, **kwargs):
and *dy* are needed). If the ``per_column`` parameter is combined with
``spacing``, then the numpy.ndarray output will be rounded up/down for as
many columns as there are increments provided in ``spacing``. A similar
parameter ``nearest_multiple`` option will provide a numpy.ndarray in the
form of [*zmin*, *zmax*, *dz*]`` for makecpt.
parameter ``nearest_multiple`` will provide a numpy.ndarray in the form
of [*zmin*, *zmax*, *dz*] for makecpt.
Full option list at :gmt-docs:`gmtinfo.html`
Expand Down Expand Up @@ -63,7 +63,7 @@ def info(table, **kwargs):
Return type depends on whether any of the ``per_column``,
``spacing``, or ``nearest_multiple`` parameters are set.
- np.ndarray if either of the above parameters are used.
- :class:`numpy.ndarray` if either of the above parameters are used.
- str if none of the above parameters are used.
"""
kind = data_kind(table)
Expand Down

0 comments on commit c7ec319

Please sign in to comment.