Skip to content

Commit

Permalink
Turn all short aliases into long form (#474)
Browse files Browse the repository at this point in the history 
To make things more readable, we'll shift our documentation to use long form arguments by default. Starting from the common aliases R, J, B, U, CPT, G and W, and moving on to all others spread across the API Reference page.

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>
  • Loading branch information
@weiji14 @seisman
weiji14 and seisman committed Jun 4, 2020
1 parent 2bc6828 commit 0267dd1
Show file tree
Hide file tree
Showing 10 changed files with 206 additions and 146 deletions.
152 changes: 88 additions & 64 deletions pygmt/base_plotting.py
View file
Expand Up @@ -70,6 +70,7 @@ def _preprocess(self, **kwargs): # pylint: disable=no-self-use
W="shorelines",
G="land",
S="water",
U="timestamp",
)
@kwargs_to_strings(R="sequence")
def coast(self, **kwargs):
Expand Down Expand Up @@ -100,34 +101,34 @@ def coast(self, **kwargs):
----------
{J}
{R}
A : int, float, or str
area_thresh : int, float, or str
``'min_area[/min_level/max_level][+ag|i|s|S][+r|l][+ppercent]'``
Features with an area smaller than min_area in km^2 or of
hierarchical level that is lower than min_level or higher than
max_level will not be plotted.
{B}
C : str
Set the shade, color, or pattern for lakes and river-lakes.
D : str
resolution : str
Selects the resolution of the data set to use ((f)ull, (h)igh,
(i)ntermediate, (l)ow, and (c)rude).
G : str
land : str
Select filling or clipping of “dry” areas.
I : str
rivers : str
``'river[/pen]'``
Draw rivers. Specify the type of rivers and [optionally] append pen
attributes.
L : str
map_scale : str
``'[g|j|J|n|x]refpoint'``
Draws a simple map scale centered on the reference point specified.
N : str
borders : str
``'border[/pen]'``
Draw political boundaries. Specify the type of boundary and
[optionally] append pen attributes
S : str
water : str
Select filling or clipping of “wet” areas.
{U}
W : str
shorelines : str
``'[level/]pen'``
Draw shorelines [Default is no shorelines]. Append pen attributes.
Expand Down Expand Up @@ -166,23 +167,24 @@ def colorbar(self, **kwargs):
Parameters
----------
position (D) : str
position : str
``[g|j|J|n|x]refpoint[+wlength[/width]][+e[b|f][length]][+h|v]
[+jjustify][+m[a|c|l|u]][+n[txt]][+odx[/dy]]``. Defines the
reference point on the map for the color scale using one of four
coordinate systems: (1) Use -Dg for map (user) coordinates, (2) use
-Dj or -DJ for setting refpoint via a 2-char justification code
that refers to the (invisible) map domain rectangle, (3) use -Dn
for normalized (0-1) coordinates, or (4) use -Dx for plot
coordinates (inches, cm, etc.). All but -Dx requires both -R and
-J to be specified. Append +w followed by the length and width of
the color bar. If width is not specified then it is set to 4% of
the given length. Give a negative length to reverse the scale bar.
Append +h to get a horizontal scale [Default is vertical (+v)]. By
default, the anchor point on the scale is assumed to be the bottom
left corner (BL), but this can be changed by appending +j followed
by a 2-char justification code justify.
box (F) : bool or str
coordinate systems: (1) Use *g* for map (user) coordinates, (2) use
*j* or *J* for setting refpoint via a 2-char justification code
that refers to the (invisible) map domain rectangle, (3) use *n*
for normalized (0-1) coordinates, or (4) use *x* for plot
coordinates (inches, cm, etc.). All but *x* requires both *region*
and *projection* to be specified. Append +w followed by the length
and width of the color bar. If width is not specified then it is
set to 4% of the given length. Give a negative length to reverse
the scale bar. Append +h to get a horizontal scale
[Default is vertical (+v)]. By default, the anchor point on the
scale is assumed to be the bottom left corner (BL), but this can be
changed by appending +j followed by a 2-char justification code
*justify*.
box : bool or str
``[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]]
[+s[[dx/dy/][shade]]]``. If set to True, draws a rectangular
border around the color scale. Alternatively, specify a different
Expand All @@ -198,12 +200,12 @@ def colorbar(self, **kwargs):
offset background shaded region. Here, dx/dy indicates the shift
relative to the foreground frame [4p/-4p] and shade sets the fill
style to use for shading [gray50].
truncate (G) : list or str
truncate : list or str
``zlo/zhi`` 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 the plotting.
scale (W) : float
scale : float
Multiply all z-values in the CPT by the provided scale. By default
the CPT is used as is.
Expand All @@ -223,7 +225,7 @@ def colorbar(self, **kwargs):
Q="cut",
R="region",
S="resample",
U="logo",
U="timestamp",
W="pen",
)
@kwargs_to_strings(R="sequence", L="sequence", A="sequence_plus")
Expand All @@ -241,7 +243,7 @@ def grdcontour(self, grid, **kwargs):
----------
grid : str or xarray.DataArray
The file name of the input grid or the grid loaded as a DataArray.
C : str or int
interval : str or int
Specify the contour lines to generate.
- The filename of a `CPT` file where the color boundaries will
Expand All @@ -251,7 +253,7 @@ def grdcontour(self, grid, **kwargs):
angle (col 3)
- A fixed contour interval ``cont_int`` or a single contour with
``+[cont_int]``
A : str, int, or list
annotation : str, int, or list
Specify or disable annotated contour levels, modifies annotated
contours specified in ``-C``.
Expand All @@ -261,17 +263,18 @@ def grdcontour(self, grid, **kwargs):
- Optional label modifiers can be specified as a single string
``'[annot_int]+e'`` or with a list of options
``([annot_int], 'e', 'f10p', 'gred')``.
L : str or list of 2 ints
limit : str or list of 2 ints
Do no draw contours below `low` or above `high`, specify as string
``'[low]/[high]'`` or list ``[low,high]``.
Q : string or int
cut : str or int
Do not draw contours with less than `cut` number of points.
S : string or int
resample : str or int
Resample smoothing factor.
{J}
{R}
{B}
{G}
{U}
{W}
"""
kwargs = self._preprocess(**kwargs)
Expand Down Expand Up @@ -439,6 +442,7 @@ def grdview(self, grid, **kwargs):
i="columns",
l="label",
C="cmap",
U="timestamp",
)
@kwargs_to_strings(R="sequence", i="sequence_comma")
def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
Expand Down Expand Up @@ -471,7 +475,7 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
Parameters
----------
x, y : float or 1d arrays
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
Expand Down Expand Up @@ -501,12 +505,12 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
``'[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen]'``.
Draw symmetrical error bars.
{G}
S : str
style : str
Plot symbols (including vectors, pie slices, fronts, decorated or
quoted lines).
{W}
{U}
l : str
label : str
Add a legend entry for the symbol or line being plotted.
"""
kwargs = self._preprocess(**kwargs)
Expand Down Expand Up @@ -575,7 +579,7 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
Parameters
----------
x, y, z : 1d arrays
x/y/z : 1d arrays
Arrays of x and y coordinates and values z of the data points.
data : str or 2d array
Either a data file name or a 2d numpy array with the tabular data.
Expand All @@ -586,21 +590,26 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
By default, geographic line segments are drawn as great circle
arcs. To draw them as straight lines, use *A*.
{B}
C : Contour file or level(s)
D : Dump contour coordinates
E : Network information
G : Placement of labels
I : Color the triangles using CPT
L : Pen to draw the underlying triangulation (default none)
N : Do not clip contours
Q : Minimum contour length
``'[p|t]'``
S : Skip input points outside region
``'[p|t]'``
levels : str
Contour file or level(s)
D : str
Dump contour coordinates
E : str
Network information
label_placement : str
Placement of labels
I : bool
Color the triangles using CPT
triangular_mesh_pen : str
Pen to draw the underlying triangulation (default none)
N : bool
Do not clip contours
Q : float or str
Do not draw contours with less than cut number of points.
``'[cut[unit]][+z]'``
skip : bool or str
Skip input points outside region ``'[p|t]'``
{W}
X : Origin shift x
Y : Origin shift y
"""
kwargs = self._preprocess(**kwargs)
Expand All @@ -623,7 +632,15 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
lib.call_module("contour", arg_str)

@fmt_docstring
@use_alias(R="region", J="projection", B="frame")
@use_alias(
R="region",
J="projection",
B="frame",
L="map_scale",
Td="rose",
Tm="compass",
U="timestamp",
)
@kwargs_to_strings(R="sequence")
def basemap(self, **kwargs):
"""
Expand All @@ -634,7 +651,8 @@ def basemap(self, **kwargs):
[optionally] gridlines. A simple map scale or directional rose may also
be plotted.
At least one of the options *B*, *L*, or *T* must be specified.
At least one of the options *frame*, *map_scale*, *rose* or *compass*
must be specified.
Full option list at :gmt-docs:`basemap.html`
Expand All @@ -645,13 +663,13 @@ def basemap(self, **kwargs):
{J}
{R}
{B}
L : str
map_scale : str
``'[g|j|J|n|x]refpoint'``
Draws a simple map scale centered on the reference point specified.
Td : str
rose : str
Draws a map directional rose on the map at the location defined by
the reference and anchor points.
Tm : str
compass : str
Draws a map magnetic rose on the map at the location defined by the
reference and anchor points
{U}
Expand All @@ -664,7 +682,7 @@ def basemap(self, **kwargs):
lib.call_module("basemap", build_arg_string(kwargs))

@fmt_docstring
@use_alias(R="region", J="projection")
@use_alias(R="region", J="projection", U="timestamp", D="position", F="box")
@kwargs_to_strings(R="sequence")
def logo(self, **kwargs):
"""
Expand All @@ -683,10 +701,10 @@ def logo(self, **kwargs):
----------
{J}
{R}
D : str
position : str
``'[g|j|J|n|x]refpoint+wwidth[+jjustify][+odx[/dy]]'``.
Sets reference point on the map for the image.
F : bool or str
box : bool or str
Without further options, draws a rectangular border around the
GMT logo.
{U}
Expand All @@ -699,7 +717,7 @@ def logo(self, **kwargs):
lib.call_module("logo", build_arg_string(kwargs))

@fmt_docstring
@use_alias(R="region", J="projection")
@use_alias(R="region", J="projection", D="position", F="box", M="monochrome")
@kwargs_to_strings(R="sequence")
def image(self, imagefile, **kwargs):
"""
Expand All @@ -714,17 +732,23 @@ def image(self, imagefile, **kwargs):
Parameters
----------
imagefile : str
This must be an Encapsulated PostScript (EPS) file or a raster
image. An EPS file must contain an appropriate BoundingBox. A
raster file can have a depth of 1, 8, 24, or 32 bits and is read
via GDAL. Note: If GDAL was not configured during GMT installation
then only EPS files are supported.
{J}
{R}
D: str
position : str
``'[g|j|J|n|x]refpoint+rdpi+w[-]width[/height][+jjustify]
[+nnx[/ny]][+odx[/dy]]'`` Sets reference point on the map for the
image.
F : bool or str
box : bool or str
``'[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]]
[+s[[dx/dy/][shade]]]'`` Without further options, draws a
rectangular border around the image using **MAP_FRAME_PEN**.
M : bool
monochrome : bool
Convert color image to monochrome grayshades using the (television)
YIQ-transformation.
"""
Expand Down Expand Up @@ -758,12 +782,12 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg
specification file.
{J}
{R}
position (D) : str
position : str
``'[g|j|J|n|x]refpoint+wwidth[/height][+jjustify][+lspacing]
[+odx[/dy]]'`` Defines the reference point on the map for the
legend. By default, uses 'JTR+jTR+o0.2c' which places the legend at
the top-right corner inside the map frame, with a 0.2 cm offset.
box (F) : bool or str
box : bool or str
``'[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]]
[+s[[dx/dy/][shade]]]'`` Without further options, draws a
rectangular border around the legend using **MAP_FRAME_PEN**. By
Expand Down Expand Up @@ -826,12 +850,12 @@ def text(
textfiles : str or list
A text data file name, or a list of filenames containing 1 or more
records with (x, y[, font, angle, justify], text).
x, y : float or 1d arrays
x/y : float or 1d arrays
The x and y coordinates, or an array of x and y coordinates to plot
the text
text : str or 1d array
The text string, or an array of strings to plot on the figure
angle: int/float or bool
angle: int, float or bool
Set the angle measured in degrees counter-clockwise from
horizontal. E.g. 30 sets the text at 30 degrees. If no angle is
given then the input textfile(s) must have this as a column.
Expand Down

0 comments on commit 0267dd1

Please sign in to comment.