Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the doc strings in the non-plotting modules #882

Merged
merged 26 commits into from
Feb 14, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
6b79637
Update doc strings for makecpt.py
willschlitzer Feb 13, 2021
9069441
Update doc strings for savefig in figure.py
willschlitzer Feb 13, 2021
b83b210
Update doc strings for psconvert in figure.py
willschlitzer Feb 13, 2021
e612529
Update doc strings in blockmedian.py
willschlitzer Feb 13, 2021
8fc0223
Update doc strings in surface.py
willschlitzer Feb 13, 2021
3ae6d0d
Update doc strings in grdcut.py
willschlitzer Feb 13, 2021
a7764ee
Update doc strings in grdfilter.py
willschlitzer Feb 13, 2021
55965dd
Update doc strings in x2sys.py
willschlitzer Feb 13, 2021
1289884
Update doc strings for x2sys_cross in x2sys.py
willschlitzer Feb 13, 2021
6f9379e
Update doc strings for info.py
willschlitzer Feb 13, 2021
6a2c992
Make changed doc strings raw strings
willschlitzer Feb 13, 2021
6f4f25d
Update fmt docstring
willschlitzer Feb 14, 2021
5f1fd46
Formatting fixes
willschlitzer Feb 14, 2021
0c08776
Update output docstring in info.py
willschlitzer Feb 14, 2021
8bcd2ab
Update formatting in makecpt.py
willschlitzer Feb 14, 2021
de9de6d
Apply suggestions from code review
willschlitzer Feb 14, 2021
a84649e
Formatting fixes
willschlitzer Feb 14, 2021
4e6c6d2
Formatting fix
willschlitzer Feb 14, 2021
3cd7330
Merge branch 'master' into docstring-format-non-plotting
willschlitzer Feb 14, 2021
c57bc9d
Apply suggestions from code review
willschlitzer Feb 14, 2021
62e694d
Format fix
willschlitzer Feb 14, 2021
3edc108
Apply suggestions from code review
willschlitzer Feb 14, 2021
3619286
Format fix
willschlitzer Feb 14, 2021
59808ee
Format fix
willschlitzer Feb 14, 2021
029fd32
Merge branch 'master' into docstring-format-non-plotting
willschlitzer Feb 14, 2021
a836e28
Merge branch 'master' into docstring-format-non-plotting
willschlitzer Feb 14, 2021
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 21 additions & 18 deletions pygmt/figure.py
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ def region(self):
)
@kwargs_to_strings()
def psconvert(self, **kwargs):
"""
r"""
Convert [E]PS file(s) to other formats.

Converts one or more PostScript files to other formats (BMP, EPS, JPEG,
Expand Down Expand Up @@ -149,20 +149,22 @@ def psconvert(self, **kwargs):
icc_gray : bool
Enforce gray-shades by using ICC profiles.
anti_aliasing : str
Set the anti-aliasing options for graphics or text. Append the size
of the subsample box (1, 2, or 4) [4]. Default is no anti-aliasing
(same as bits = 1).
[**g**\|\ **p**\|\ **t**\][**1**\|\ **2**\|\ **4**].
Set the anti-aliasing options for **g**\ raphics or **t**\ ext.
Append the size of the subsample box (1, 2, or 4) [4]. [Default is
no anti-aliasing (same as bits = 1)].
fmt : str
Sets the output format, where *b* means BMP, *e* means EPS, *E*
means EPS with PageSize command, *f* means PDF, *F* means
multi-page PDF, *j* means JPEG, *g* means PNG, *G* means
transparent PNG (untouched regions are transparent), *m* means PPM,
*s* means SVG, and *t* means TIFF [default is JPEG]. To ``'bjgt'``
you can append ``'+m'`` in order to get a monochrome (grayscale)
image. The EPS format can be combined with any of the other
formats. For example, ``'ef'`` creates both an EPS and a PDF file.
Using ``'F'`` creates a multi-page PDF file from the list of input
PS or PDF files. It requires the *prefix* option.
Sets the output format, where **b** means BMP, **e** means EPS,
**E** means EPS with PageSize command, **f** means PDF, **F** means
multi-page PDF, **j** means JPEG, **g** means PNG, **G** means
transparent PNG (untouched regions are transparent), **m** means
PPM, **s** means SVG, and **t** means TIFF [default is JPEG]. To
**b**\|\ **j**\|\ **g**\|\ **t**\ , optionally append **+m** in
order to get a monochrome (grayscale) image. The EPS format can be
combined with any of the other formats. For example, **ef** creates
both an EPS and a PDF file. Using **F** creates a multi-page PDF
file from the list of input PS or PDF files. It requires the
``prefix`` parameter.
"""
kwargs = self._preprocess(**kwargs)
# Default cropping the figure to True
Expand All @@ -178,7 +180,7 @@ def savefig(
Save the figure to a file.

This method implements a matplotlib-like interface for
:meth:`~gmt.Figure.psconvert`.
:meth:`pygmt.Figure.psconvert`.

Supported formats: PNG (``.png``), JPEG (``.jpg``), PDF (``.pdf``),
BMP (``.bmp``), TIFF (``.tif``), EPS (``.eps``), and KML (``.kml``).
Expand All @@ -199,9 +201,10 @@ def savefig(
If True, will crop the figure canvas (page) to the plot area.
anti_alias: bool
If True, will use anti aliasing when creating raster images (PNG,
JPG, TIf). More specifically, uses options ``Qt=2, Qg=2`` in
:meth:`~gmt.Figure.psconvert`. Ignored if creating vector graphics.
Overrides values of ``Qt`` and ``Qg`` passed in through ``kwargs``.
JPG, TIFF). More specifically, it passes arguments ``t2``
and ``g2`` to the ``anti_aliasing`` parameter of
:meth:`pygmt.Figure.psconvert`. Ignored if creating vector
graphics.
show: bool
If True, will open the figure in an external viewer.
dpi : int
Expand Down
12 changes: 7 additions & 5 deletions pygmt/src/blockmedian.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
@use_alias(I="spacing", R="region", V="verbose")
@kwargs_to_strings(R="sequence")
def blockmedian(table, outfile=None, **kwargs):
"""
r"""
Block average (x,y,z) data tables by median estimation.

Reads arbitrarily located (x,y,z) triples [or optionally weighted
Expand All @@ -39,15 +39,17 @@ def blockmedian(table, outfile=None, **kwargs):
ASCII data table.

spacing : str
``'xinc[unit][+e|n][/yinc[unit][+e|n]]'``.
x_inc [and optionally y_inc] is the grid spacing.
*xinc*\[\ *unit*\][**+e**\|\ **n**]
[/*yinc*\ [*unit*][**+e**\|\ **n**]].
*xinc* [and optionally *yinc*] is the grid spacing.

region : str or list
``'xmin/xmax/ymin/ymax[+r][+uunit]'``.
*xmin/xmax/ymin/ymax*\[\ **+r**\][**+u**\ *unit*].
Specify the region of interest.

outfile : str
willschlitzer marked this conversation as resolved.
Show resolved Hide resolved
Required if 'table' is a file. The file name for the output ASCII file.
Required if ``table`` is a file. The file name for the output ASCII
file.

{V}

Expand Down
12 changes: 6 additions & 6 deletions pygmt/src/grdcut.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,10 @@
)
@kwargs_to_strings(R="sequence")
def grdcut(grid, **kwargs):
"""
r"""
Extract subregion from a grid.

Produce a new *outgrid* file which is a subregion of *grid*. The
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
Expand All @@ -54,16 +54,16 @@ def grdcut(grid, **kwargs):
{J}
{R}
extend : bool or int or float
Allow grid to be extended if new *region* exceeds existing boundaries.
Give a value to initialize nodes outside current region.
Allow grid to be extended if new ``region`` exceeds existing
boundaries. Give a value to initialize nodes outside current region.
circ_subregion : str
``'lon/lat/radius[unit][+n]'``.
*lon/lat/radius*\[\ *unit*\][**+n**].
Specify an origin (*lon* and *lat*) and *radius*; append a distance
*unit* and we determine the corresponding rectangular region so that
all grid nodes on or inside the circle are contained in the subset.
If **+n** is appended we set all nodes outside the circle to NaN.
z_subregion : str
``'[min/max][+n|N|r]'``.
[*min/max*\][**+n**\|\ **N**\|\ **r**].
Determine a new rectangular region so that all nodes outside this
region are also outside the given z-range [-inf/+inf]. To indicate no
limit on *min* or *max* only, specify a hyphen (-). Normally, any NaNs
Expand Down
43 changes: 28 additions & 15 deletions pygmt/src/grdfilter.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,18 +29,18 @@
)
@kwargs_to_strings(R="sequence")
def grdfilter(grid, **kwargs):
"""
r"""
Filter a grid in the space (or time) domain.

Filter a grid file in the time domain using one of the selected convolution
willschlitzer marked this conversation as resolved.
Show resolved Hide resolved
or non-convolution isotropic or rectangular filters and compute distances
using Cartesian or Spherical geometries. The output grid file can
optionally be generated as a sub-region of the input (via *region*) and/or
with new increment (via *spacing*) or registration (via *toggle*). In this
way, one may have "extra space" in the input data so that the edges will
not be used and the output can be within one half-width of the input edges.
If the filter is low-pass, then the output may be less frequently sampled
than the input.
optionally be generated as a sub-region of the input (via ``region``)
and/or with new increment (via ``spacing``) or registration
(via ``toggle``). In this way, one may have "extra space" in the input
data so that the edges will not be used and the output can be within one
half-width of the input edges. If the filter is low-pass, then the output
may be less frequently sampled than the input.

Full option list at :gmt-docs:`grdfilter.html`

Expand All @@ -54,11 +54,23 @@ def grdfilter(grid, **kwargs):
The name of the output netCDF file with extension .nc to store the grid
in.
filter : str
``xwidth[/width2][modifiers]``.
Name of filter type you which to apply, followed by the width
b: Box Car; c: Cosine Arch; g: Gaussian; o: Operator; m: Median;
p: Maximum Likelihood probability; h: histogram
Example: F='m600' for a median filter with width of 600
**b**\|\ **c**\|\ **g**\|\ **o**\|\ **m**\|\ **p**\|\ **h**\ *xwidth*\
[/*width2*\][*modifiers*].
Name of filter type you which to apply, followed by the width:

b: Box Car

c: Cosine Arch

g: Gaussian

o: Operator

m: Median

p: Maximum Likelihood probability

h: histogram
willschlitzer marked this conversation as resolved.
Show resolved Hide resolved
distance : str
Distance *flag* tells how grid (x,y) relates to filter width as
follows:
Expand Down Expand Up @@ -87,10 +99,11 @@ def grdfilter(grid, **kwargs):
Spherical distance calculation.

spacing : str
``xinc[+e|n][/yinc[+e|n]]``.
x_inc [and optionally y_inc] is the grid spacing.
*xinc*\[\ *unit*\][**+e**\|\ **n**]
[/*yinc*\ [*unit*][**+e**\|\ **n**]].
*xinc* [and optionally *yinc*] is the grid spacing.
nans : str or float
``i|p|r``.
**i**\|\ **p**\|\ **r**.
Determine how NaN-values in the input grid affects the filtered output.
{R}
toggle : bool
Expand Down
25 changes: 13 additions & 12 deletions pygmt/src/info.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,20 +17,21 @@
@fmt_docstring
@use_alias(C="per_column", I="spacing", T="nearest_multiple", V="verbose")
def info(table, **kwargs):
"""
r"""
Get information about data tables.

Reads from files and finds the extreme values in each of the columns
willschlitzer marked this conversation as resolved.
Show resolved Hide resolved
reported as min/max pairs. It recognizes NaNs and will print warnings if
the number of columns vary from record to record. As an option, it will
find the extent of the first two columns rounded up and down to the nearest
multiple of the supplied increments given by *spacing*. Such output will be
in a numpy.ndarray form ``[w, e, s, n]``, which can be used directly as the
*region* argument for other modules (hence only dx and dy are needed). If
the *per_column* option 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 option *nearest_multiple* option will
provide a numpy.ndarray in the form of ``[zmin, zmax, dz]`` for makecpt.
multiple of the supplied increments given by ``spacing``. Such output will
be in a numpy.ndarray form [*w*, *e*, *s*, *n*], which can be used
directly as the ``region`` parameter for other modules (hence only *dx*
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.

Full option list at :gmt-docs:`gmtinfo.html`

Expand All @@ -45,12 +46,12 @@ def info(table, **kwargs):
per_column : bool
Report the min/max values per column in separate columns.
spacing : str
``'[b|p|f|s]dx[/dy[/dz...]]'``.
[**b**\|\ **p**\|\ **f**\|\ **s**]\ *dx*\[/*dy*\[/*dz*...]].
Report the min/max of the first n columns to the nearest multiple of
the provided increments and output results in the form
``[w, e, s, n]``.
nearest_multiple : str
``'dz[+ccol]'``
**dz**\[\ **+c**\ *col*].
Report the min/max of the first (0'th) column to the nearest multiple
of dz and output this in the form ``[zmin, zmax, dz]``.

Expand All @@ -59,8 +60,8 @@ def info(table, **kwargs):
Returns
-------
output : np.ndarray or str
Return type depends on whether any of the 'per_column', 'spacing', or
'nearest_multiple' parameters are set.
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.
- str if none of the above parameters are used.
Expand Down
25 changes: 13 additions & 12 deletions pygmt/src/makecpt.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,12 +26,12 @@
)
@kwargs_to_strings(T="sequence", G="sequence")
def makecpt(**kwargs):
"""
r"""
Make GMT color palette tables.

This is a module that will help you make static color palette tables
willschlitzer marked this conversation as resolved.
Show resolved Hide resolved
(CPTs). By default, the CPT will simply be saved to the current session,
but you can use *output* to save it to a file. You define an equidistant
but you can use ``output`` to save it to a file. You define an equidistant
set of contour intervals or pass your own z-table or list, and create a new
CPT based on an existing master (dynamic) CPT. The resulting CPT can be
reversed relative to the master cpt, and can be made continuous or
Expand All @@ -49,8 +49,8 @@ def makecpt(**kwargs):
the new master file. If not, the parameters :gmt-term:`COLOR_BACKGROUND`,
:gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` from the
:gmt-docs:`gmt.conf <gmt.conf>` file or the command line will be used. This
default behavior can be overruled using the options *background*,
*overrule_bg* or *no_bg*.
default behavior can be overruled using the parameters ``background``,
``overrule_bg`` or ``no_bg``.

The color model (RGB, HSV or CMYK) of the palette created by **makecpt**
will be the same as specified in the header of the master CPT. When there
Expand Down Expand Up @@ -81,7 +81,7 @@ def makecpt(**kwargs):
``background='i'`` to match the colors for the lowest and highest
values in the input (instead of the output) CPT.
color_model :
``[R|r|h|c][+c[label]]``.
[**R**\|\ **r**\|\ **h**\|\ **c**][**+c**\ [*label*]].
Force output CPT to be written with r/g/b codes, gray-scale values or
color name (**R**, default) or r/g/b codes only (**r**), or h-s-v codes
(**h**), or c/m/y/k codes (**c**). Optionally or alternatively, append
Expand All @@ -93,7 +93,7 @@ def makecpt(**kwargs):
labels from *start* (a single letter or an integer). Append - to build
willschlitzer marked this conversation as resolved.
Show resolved Hide resolved
ranges *start*-*start+1* instead.
series : list or str
``[min/max/inc[+b|l|n]|file|list]``.
[*min/max/inc*\[**+b**\|\ **l**\|\ **n**]\|\ *file*\|\ *list*].
Defines the range of the new CPT by giving the lowest and highest
z-value (and optionally an interval). If this is not given, the
existing range in the master CPT will be used intact. The values
Expand All @@ -102,21 +102,22 @@ def makecpt(**kwargs):
For details on array creation, see
:gmt-docs:`makecpt.html#generate-1d-array`.
truncate : list or str
``zlo/zhi``.
*zlow/zhigh*.
Truncate the incoming CPT so that the lowest and highest z-levels are
to *zlo* and *zhi*. If one of these equal NaN then we leave that end of
the CPT alone. The truncation takes place before any resampling. See
to *zlow* and *zhigh*. If one of these equal NaN then we leave that
end of the CPT alone. The truncation takes place before any
resampling. See
also :gmt-docs:`cookbook/features.html#manipulating-cpts`.
output : str
Optional. The file name with extension .cpt to store the generated CPT
file. If not given or False (default), saves the CPT as the session
current CPT.
reverse : str
Set this to True or c [Default] to reverse the sense of color
Set this to True or **c**\ [Default] to reverse the sense of color
progression in the master CPT. Set this to z to reverse the sign of
z-values in the color table. Note that this change of z-direction
happens before *truncate* and *series* values are used so the latter
must be compatible with the changed *z*-range. See also
happens before ``truncate`` and ``series`` values are used so the
latter must be compatible with the changed *z*-range. See also
:gmt-docs:`cookbook/features.html#manipulating-cpts`.
overrule_bg : str
Overrule background, foreground, and NaN colors specified in the master
Expand Down
9 changes: 5 additions & 4 deletions pygmt/src/surface.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
@use_alias(I="spacing", R="region", G="outfile", V="verbose")
@kwargs_to_strings(R="sequence")
def surface(x=None, y=None, z=None, data=None, **kwargs):
"""
r"""
Grids table data using adjustable tension continuous curvature splines.

Surface reads randomly-spaced (x,y,z) triples and produces gridded values
Expand All @@ -47,11 +47,12 @@ def surface(x=None, y=None, z=None, data=None, **kwargs):
Either a data file name or a 2d numpy array with the tabular data.

spacing : str
``'xinc[unit][+e|n][/yinc[unit][+e|n]]'``.
x_inc [and optionally y_inc] is the grid spacing.
*xinc*\[\ *unit*\][**+e**\|\ **n**]\
[/*yinc*\ [*unit*][**+e**\|\ **n**]].
*xinc* [and optionally *yinc*] is the grid spacing.

region : str or list
``'xmin/xmax/ymin/ymax[+r][+uunit]'``.
*xmin/xmax/ymin/ymax*\[**+r**][**+u**\ *unit*].
Specify the region of interest.

outfile : str
Expand Down
Loading