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

Complete documentation for plot #666

Merged
merged 9 commits into from
Oct 25, 2020
121 changes: 93 additions & 28 deletions pygmt/base_plotting.py
Original file line number Diff line number Diff line change
Expand Up @@ -606,47 +606,53 @@ def grdview(self, grid, **kwargs):

@fmt_docstring
@use_alias(
R="region",
J="projection",
A="straight_lines",
weiji14 marked this conversation as resolved.
Show resolved Hide resolved
B="frame",
S="style",
C="cmap",
D="offset",
E="error_bars",
weiji14 marked this conversation as resolved.
Show resolved Hide resolved
F="connection",
G="color",
I="intensity",
J="projection",
L="close",
N="no_clip",
W="pen",
i="columns",
l="label",
C="cmap",
R="region",
S="style",
U="timestamp",
V="verbose",
W="pen",
X="xshift",
Y="yshift",
Z="zvalue",
i="columns",
weiji14 marked this conversation as resolved.
Show resolved Hide resolved
l="label",
p="perspective",
t="transparency",
)
@kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
"""
Plot lines, polygons, and symbols on maps.

Used to be psxy.
Plot lines, polygons, and symbols in 2-D.

Takes a matrix, (x,y) pairs, or a file name as input and plots lines,
polygons, or symbols at those locations on a map.

Must provide either *data* or *x* and *y*.

If providing data through *x* and *y*, *color* (G) can be a 1d array
that will be mapped to a colormap.
If providing data through *x* and *y*, *color* can be a 1d array that
will be mapped to a colormap.

If a symbol is selected and no symbol size given, then psxy will
If a symbol is selected and no symbol size given, then plot will
interpret the third column of the input data as symbol size. Symbols
whose size is <= 0 are skipped. If no symbols are specified then the
symbol code (see *S* below) must be present as last column in the
input. If *S* is not used, a line connecting the data points will be
drawn instead. To explicitly close polygons, use *L*. Select a fill
with *G*. If *G* is set, *W* will control whether the polygon outline
is drawn or not. If a symbol is selected, *G* and *W* determines the
fill and outline/no outline, respectively.
symbol code (see **symbol** below) must be present as last column in
weiji14 marked this conversation as resolved.
Show resolved Hide resolved
the input. If **symbol** is not used, a line connecting the data points
will be drawn instead. To explicitly close polygons, use **close**.
Select a fill with **color**. If **color** is set, **pen** will control
whether the polygon outline is drawn or not. If a symbol is selected,
**color** and **pen** determines the fill and outline/no outline,
respectively.

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

Expand All @@ -671,19 +677,69 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
depending on the style options chosen.
{J}
{R}
A : bool or str
``'[m|p|x|y]'``
straight_lines : bool or str
``[m|p|x|y]``.
By default, geographic line segments are drawn as great circle
arcs. To draw them as straight lines, use *A*.
arcs. To draw them as straight lines, use *straight_lines*.
Alternatively, add **m** to draw the line by first following a
meridian, then a parallel. Or append **p** to start following a
parallel, then a meridian. (This can be practical to draw a line
along parallels, for example). For Cartesian data, points are
simply connected, unless you append **x** or **y** to draw
stair-case curves that whose first move is along *x* or *y*,
respectively.
{B}
{CPT}
D : str
``'dx/dy'``: Offset the plot symbol or line locations by the given
amounts dx/dy.
E : bool or str
``'[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen]'``.
Draw symmetrical error bars.
offset : str
``dx/dy``.
Offset the plot symbol or line locations by the given amounts
*dx/dy* [Default is no offset]. If *dy* is not given it is set
equal to *dx*.
error_bars : bool or str
``[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen]``.
Draw symmetrical error bars. Full documentation is at
:gmt-docs:`plot.html#e`.
connection : str
``[c|n|r][a|f|s|r|refpoint]``.
Alter the way points are connected (by specifying a *scheme*) and
data are grouped (by specifying a *method*). Append one of three
line connection schemes:

- **c** : Draw continuous line segments for each group [Default].
- **r** : Draw line segments from a reference point reset for each
group.
- **n** : Draw networks of line segments between all points in
each group.

Optionally, append the one of four segmentation methods to define
the group:

- **a** : Ignore all segment headers, i.e., let all points belong
to a single group, and set group reference point to the very
first point of the first file.
- **f** : Consider all data in each file to be a single separate
group and reset the group reference point to the first point of
each group.
- **s** : Segment headers are honored so each segment is a group;
the group reference point is reset to the first point of each
incoming segment [Default].
- **r** : Same as **s**, but the group reference point is reset
after each record to the previous point (this method is only
available with the ``connection='r'`` scheme).

Instead of the codes **a**|**f**|**s**|**r** you may append the
coordinates of a *refpoint* which will serve as a fixed external
reference point for all groups.
{G}
intensity : float or bool
Provide an *intens* value (nominally in the -1 to +1 range) to
modulate the fill color by simulating illumination [None]. If
using ``intensity=True``, we will instead read *intens* from the
first data column after the symbol parameters (if given).
close : str
``[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen]``.
Force closed polygons. Full documentation is at
:gmt-docs:`plot.html#l`.
no_clip : bool or str
``'[c|r]'``.
Do NOT clip symbols that fall outside map border [Default plots
Expand All @@ -703,6 +759,15 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
{U}
{V}
{XY}
zvalue : str
``value|file``.
Instead of specifying a symbol or polygon fill and outline color
via **color** and **pen**, give both a *value* via **zvalue** and a
color lookup table via **cmap**. Alternatively, give the name of a
*file* with one z-value (read from the last column) for each
polygon in the input data. To apply it to the fill color, use
``color='+z'``. To apply it to the pen color, append **+z** to
**pen**.
label : str
Add a legend entry for the symbol or line being plotted.

Expand Down