diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 396b0c86d31..37b938c7a79 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -606,47 +606,52 @@ def grdview(self, grid, **kwargs): @fmt_docstring @use_alias( - R="region", - J="projection", + A="straight_line", B="frame", - S="style", + C="cmap", + D="offset", + E="error_bar", + 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", + 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 *style* below) must be present as last column in the + input. If *style* 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` @@ -671,19 +676,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_line : 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_line*. + 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_bar : 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 @@ -703,6 +758,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.