From 6ea53ee341aa2f832af1869546373c7a7853814e Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Fri, 23 Oct 2020 15:49:24 +1300 Subject: [PATCH 1/7] Alias straight_lines(A), error_bars(E), close(L), position(D) for plot --- pygmt/base_plotting.py | 72 ++++++++++++++++++++++++++---------------- 1 file changed, 44 insertions(+), 28 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 396b0c86d31..9a886a74f48 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -606,47 +606,49 @@ def grdview(self, grid, **kwargs): @fmt_docstring @use_alias( - R="region", - J="projection", + A="straight_lines", B="frame", - S="style", + C="cmap", + D="position", + E="error_bars", G="color", + 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", + 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 *symbol* below) must be present as last column in 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` @@ -671,19 +673,33 @@ 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. + position : 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`. {G} + 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 From 5039540aa42405faffd0ec487a3b1b48b1788dd6 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Sat, 24 Oct 2020 09:02:36 +1300 Subject: [PATCH 2/7] Alias as offset (D) and fix indentation on close (L) --- pygmt/base_plotting.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 9a886a74f48..c5fe847f063 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -609,7 +609,7 @@ def grdview(self, grid, **kwargs): A="straight_lines", B="frame", C="cmap", - D="position", + D="offset", E="error_bars", G="color", J="projection", @@ -686,7 +686,7 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): respectively. {B} {CPT} - position : str + 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 @@ -697,9 +697,9 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): :gmt-docs:`plot.html#e`. {G} close : str - ``[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen]``. - Force closed polygons. Full documentation is at - :gmt-docs:`plot.html#l`. + ``[+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 From 0f60edf2728ccb40994ebb797a977595dbebc369 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Sat, 24 Oct 2020 09:35:53 +1300 Subject: [PATCH 3/7] Change some italicized arguments to bold in description of plot --- pygmt/base_plotting.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index c5fe847f063..286127a04a1 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -643,12 +643,13 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): 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 *symbol* below) must be present as last column in 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. + symbol code (see **symbol** below) must be present as last column in + 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` From d6dca1da7a7ab57abc21f71764b97a61ed3ad249 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Sat, 24 Oct 2020 09:48:03 +1300 Subject: [PATCH 4/7] Alias connection (F), intensity (I) and zvalue (Z) for plot --- pygmt/base_plotting.py | 48 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 286127a04a1..166cbd7293f 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -611,7 +611,9 @@ def grdview(self, grid, **kwargs): C="cmap", D="offset", E="error_bars", + F="connection", G="color", + I="intensity", J="projection", L="close", N="no_clip", @@ -622,6 +624,7 @@ def grdview(self, grid, **kwargs): W="pen", X="xshift", Y="yshift", + Z="zvalue", i="columns", l="label", p="perspective", @@ -696,7 +699,43 @@ 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. 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 @@ -720,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. From 173587ebf744b6854c83726d72174c2bb3614fd3 Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Sun, 25 Oct 2020 10:20:05 +1300 Subject: [PATCH 5/7] Fix typo symbol to style Co-Authored-By: Dongdong Tian --- pygmt/base_plotting.py | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 166cbd7293f..81c66d19ecf 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -646,13 +646,12 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): 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 **symbol** below) must be present as last column in - 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. + 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` From c06bc1355e71240813c4eeaf5c1cf116a447e3fa Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Sun, 25 Oct 2020 16:03:38 +1300 Subject: [PATCH 6/7] Change some args to italics instead of bold, and use singular aliases Also remove columns (i) alias for now. Co-Authored-By: Dongdong Tian --- pygmt/base_plotting.py | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 81c66d19ecf..fbcbc9fada1 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -606,11 +606,11 @@ def grdview(self, grid, **kwargs): @fmt_docstring @use_alias( - A="straight_lines", + A="straight_line", B="frame", C="cmap", D="offset", - E="error_bars", + E="error_bar", F="connection", G="color", I="intensity", @@ -625,7 +625,6 @@ def grdview(self, grid, **kwargs): X="xshift", Y="yshift", Z="zvalue", - i="columns", l="label", p="perspective", t="transparency", @@ -646,12 +645,12 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): 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 **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. + 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` @@ -676,10 +675,10 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): depending on the style options chosen. {J} {R} - straight_lines : bool or str + 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 *straight_lines*. + 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 @@ -694,7 +693,7 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs): 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 + 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`. From f4f35962ce0ae63bc5c4f8678c23f935a666c73d Mon Sep 17 00:00:00 2001 From: Wei Ji Date: Sun, 25 Oct 2020 16:08:25 +1300 Subject: [PATCH 7/7] Revert removal of columns (i) alias --- pygmt/base_plotting.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index fbcbc9fada1..37b938c7a79 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -625,6 +625,7 @@ def grdview(self, grid, **kwargs): X="xshift", Y="yshift", Z="zvalue", + i="columns", l="label", p="perspective", t="transparency",