Merge branch 'master' into gmt-library

examples/gallery/plot/datetime-inputs.py

@@ -0,0 +1,61 @@
+"""
+Datetime inputs
+---------------
+
+Datetime inputs of the following types are supported in PyGMT:
+
+- :class:`numpy.datetime64`
+- :class:`pandas.DatetimeIndex`
+- :class:`xarray.DataArray`: datetimes included in a *xarray.DataArray*
+- raw datetime strings in `ISO format <https://en.wikipedia.org/wiki/ISO_8601>`__  (e.g. ``"YYYY-MM-DD"``, ``"YYYY-MM-DDTHH"``, and ``"YYYY-MM-DDTHH:MM:SS"``)
+- Python built-in :class:`datetime.datetime` and :class:`datetime.date`
+
+We can pass datetime inputs based on one of the types listed above directly to the ``x`` and ``y`` arguments
+of e.g. the :meth:`pygmt.Figure.plot` method:
+
+The ``region`` argument has to include the :math:`x` and :math:`y` axis limits as *str* in the form 
+*date_min/date_max/ymin/ymax*.
+
+"""
+
+import datetime
+
+import numpy as np
+import pandas as pd
+import pygmt
+import xarray as xr
+
+fig = pygmt.Figure()
+
+# create a basemap with limits of 2010-01-01 to 2020-06-01 on the x axis and
+# 0 to 10 on the y axis
+fig.basemap(
+    projection="X15c/5c", region="2010-01-01/2020-06-01/0/10", frame=["WSen", "af"]
+)
+
+# numpy.datetime64 types
+x = np.array(["2010-06-01", "2011-06-01T12", "2012-01-01T12:34:56"], dtype="datetime64")
+y = [1, 2, 3]
+fig.plot(x, y, style="c0.4c", pen="1p", color="red3")
+
+# pandas.DatetimeIndex
+x = pd.date_range("2013", periods=3, freq="YS")
+y = [4, 5, 6]
+fig.plot(x, y, style="t0.4c", pen="1p", color="gold")
+
+# xarray.DataArray
+x = xr.DataArray(data=pd.date_range(start="2015-03", periods=3, freq="QS"))
+y = [7.5, 6, 4.5]
+fig.plot(x, y, style="s0.4c", pen="1p")
+
+# raw datetime strings
+x = ["2016-02-01", "2016-06-04T14", "2016-10-04T00:00:15"]
+y = [7, 8, 9]
+fig.plot(x, y, style="a0.4c", pen="1p", color="dodgerblue")
+
+# the Python built-in datetime and date
+x = [datetime.date(2018, 1, 1), datetime.datetime(2019, 6, 1, 20, 5, 45)]
+y = [6.5, 4.5]
+fig.plot(x, y, style="i0.4c", pen="1p", color="seagreen")
+
+fig.show()

examples/projections/cyl/cyl_cassini.py

@@ -11,7 +11,10 @@
 meridian, each meridian 90° away, and equator are straight lines; all other meridians
 and parallels are complex curves.
 
-``Clon0/lat0/width``: ``lon0`` and ``lat0`` specifies the projection center.
+**c**\ *lon0/lat0*\ */scale* or **C**\ *lon0/lat0*\ */width*
+
+The projection is set with **c** or **C**. The projection center is set by *lon0/lat0*,
+and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_equal_area.py

@@ -6,8 +6,10 @@
 latitude is selected as the standard parallel. However, they are all equal area and
 hence non-conformal. All meridians and parallels are straight lines.
 
-``Ylon0/lat0/width``: Give central meridian ``lon0``, the standard parallel ``lat0``,
-and the figure ``width``.
+**y**\ *lon0/lat0*\ */scale* or **Y**\ *lon0/lat0*\ */width*
+
+The projection is set with **y** or **Y**. The projection center is set by *lon0/lat0*,
+and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_equidistant.py

@@ -6,7 +6,10 @@
 latitudes. The most common form is the Plate Carrée projection, where the scaling of
 longitudes and latitudes is the same. All meridians and parallels are straight lines.
 
-``Qwidth``: Give the figure ``width``.
+**q**\ *scale* or **Q**\ *width*
+
+The projection is set with **q** or **Q**, and the figure size is set
+with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_mercator.py

@@ -12,8 +12,11 @@
 extensively for world maps in which the distortion towards the polar regions grows
 rather large.
 
-``M[lon0/][lat0/]width``: Give central meridian ``lon0`` (optional) and
-standard parallel ``lat0`` (optional).
+**m**\ [*lon0[/lat0]*]\ */scale* or **M**\ [*lon0*][*/lat0*]\ */width*
+
+The projection is set with **m** or **M**. The central meridian is set with the
+option *lon0* and the standard parallel is set with the option *lat0*.
+The figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_miller.py

@@ -9,7 +9,10 @@
 by using Mercator’s formula with 0.8 times the actual latitude, thus avoiding the
 singular poles; the result was then divided by 0.8.
 
-``J[lon0/]width``: Give the optional central meridian ``lon0`` and the figure ``width``.
+**j**\ [*lon0/*]\ */scale* or **J**\ [*lon0/*]\ */width*
+
+The projection is set with **j** or **J**. The central meridian is set by the
+optional *lon0*, and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_stereographic.py

@@ -10,9 +10,13 @@
 antipodal point on the equator. The cylinder crosses the sphere at two standard
 parallels, equidistant from the equator.
 
-``Cyl_stere/[lon0/][lat0/]width``: Give central meridian ``lon0`` (optional) and
-standard parallel ``lat0`` (optional). The standard parallel is typically one of these
-(but can be any value):
+**cyl_stere/**\ [*lon0/*]\ [*lat0/*]\ *scale*
+or **Cyl_stere/**\ [*lon0/*]\ [*lat0/*]\ *width*
+
+The projection is set with **cyl_stere** or **Cyl_stere**. The central meridian is set
+by the optional *lon0*, and the figure size is set with *scale* or *width*.
+
+The standard parallel is typically one of these (but can be any value):
 
 * 66.159467 - Miller's modified Gall
 * 55 - Kamenetskiy's First

examples/projections/cyl/cyl_transverse_mercator.py

@@ -8,8 +8,11 @@
 center. The central meridian, each meridian 90° away from the center, and equator are
 straight lines; other parallels and meridians are complex curves.
 
-``T[lon0/][lat0/]width``: Give central meridian ``lon0``, the latitude of the
-origin ``lat0`` (optional), and the figure width.
+**t**\ *lon0/*\ [*lat0/*\ ]\ *scale* or **T**\ *lon0/*\ [*lat0/*\ ]\ *width*
+
+The projection is set with **t** or **T**. The central meridian is set
+by  *lon0*, the latitude of the origin is set by the optional *lat0*, and the figure
+size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_universal_transverse_mercator.py

@@ -14,7 +14,10 @@
 1 part in 1,000 from true scale at equator. The ellipsoidal projection expressions are
 accurate for map areas that extend less than 10 away from the central meridian.
 
-``U[UTM Zone/][lat0/]width``: Give UTM Zone ``UTM Zone``, and the figure width.
+**u**\ *zone/scale* or **U**\ *zone/width*
+
+the projection is set with **u** or **U**. *zone* sets the zone for the figure, and
+the figure size is set wtih *scale* or *width*.
 """
 import pygmt
 

examples/projections/misc/misc_eckertIV.py

@@ -7,8 +7,10 @@
 meridian and all parallels are straight lines; other meridians are equally spaced
 elliptical arcs. The scale is true along latitude 40°30’.
 
-``Kf[central meridian]/width``: Give the optional central meridian (default is the
-center of the region) and the map width.
+**kf**\ [*lon0/*]\ *scale* or **Kf**\ [*lon0/*]\ *width*
+
+The projection is set with **kf** or **Kf**. The central meridian is set with the
+optional *lon0*, and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/misc/misc_eckertVI.py

@@ -7,8 +7,11 @@
 Central meridian and all parallels are straight lines; other meridians are equally
 spaced sinusoids. The scale is true along latitude 49°16’.
 
-``Ks[central meridian]/width``: Give the optional central meridian (default is the
-center of the region) and the map width.
+
+**ks**\ [*lon0/*]\ *scale* or **Ks**\ [*lon0/*]\ *width*
+
+The projection is set with **ks** or **Ks**. The central meridian is set with the
+optional *lon0*, and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/misc/misc_hammer.py

@@ -7,8 +7,10 @@
 similar, but is not equal-area). The border is an ellipse, equator and central
 meridian are straight lines, while other parallels and meridians are complex curves.
 
-``H[central meridian]/width``: Give the optional central meridian (default is the center
-of the region) and the map width.
+**h**\ [*lon0/*]\ *scale* or **H**\ [*lon0/*]\ *width*
+
+The projection is set with **h** or **H**. The central meridian is set with the
+optional *lon0*, and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/misc/misc_mollweide.py

@@ -9,8 +9,10 @@
 mainly for global maps showing data distributions. It is occasionally referenced under
 the name homalographic projection.
 
-``W[central meridian]/width``: Give the optional central meridian (default is the center
-of the region) and the map width.
+**w**\ [*lon0/*]\ *scale* or **W**\ [*lon0/*]\ *width*
+
+The projection is set with **w** or **W**. The central meridian is set with the
+optional *lon0*, and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/misc/misc_robinson.py

@@ -10,8 +10,10 @@
 originally developed for use by Rand McNally and is currently used by the
 National Geographic Society.
 
-``N[central meridian]/width``: Give the optional central meridian (default is the center
-of the region) and the map width.
+**n**\ [*lon0/*]\ *scale* or **N**\ [*lon0/*]\ *width*
+
+The projection is set with **n** or **N**. The central meridian is set with the
+optional *lon0*, and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/misc/misc_sinusoidal.py

@@ -8,8 +8,10 @@
 meridians are sinusoidal curves. Parallels are all equally spaced straight lines, with
 scale being true along all parallels (and central meridian).
 
-``I[central meridian]/width``: Give the optional central meridian (default is the center
-of the region) and the map width.
+**i**\ [*lon0/*]\ *scale* or **I**\ [*lon0/*]\ *width*
+
+The projection is set with **i** or **I**. The central meridian is set with the
+optional *lon0*, and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/misc/misc_van_der_grinten.py

@@ -7,8 +7,10 @@
 other meridians are arcs of circles. The scale is true along the Equator only. Its
 main use is to show the entire world enclosed in a circle.
 
-``V[central meridian]/width``: Give the optional central meridian (default is the center
-of the region) and the map width.
+**v**\ [*lon0/*]\ *scale* or **V**\ [*lon0/*]\ *width*
+
+The projection is set with **v** or **V**. The central meridian is set with the
+optional *lon0*, and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/misc/misc_winkel_tripel.py

@@ -16,8 +16,10 @@
 (not Hammer-Aitoff) projections. The poles map into straight lines 0.4 times the
 length of equator.
 
-``R[central meridian]/width``: Give the optional central meridian (default is the center
-of the region) and the map width.
+**r**\ [*lon0/*]\ *scale* or **R**\ [*lon0/*]\ *width*
+
+The projection is set with **r** or **R**. The central meridian is set with the
+optional *lon0*, and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

pygmt/base_plotting.py

@@ -60,6 +60,7 @@ def _preprocess(self, **kwargs):  # pylint: disable=no-self-use
         R="region",
         J="projection",
         A="area_thresh",
+        C="lakes",
         B="frame",
         D="resolution",
         I="rivers",
@@ -77,7 +78,7 @@ def _preprocess(self, **kwargs):  # pylint: disable=no-self-use
     )
     @kwargs_to_strings(R="sequence", p="sequence")
     def coast(self, **kwargs):
-        """
+        r"""
         Plot continents, shorelines, rivers, and borders on maps
 
         Plots grayshaded, colored, or textured land-masses [or water-masses] on
@@ -110,8 +111,13 @@ def coast(self, **kwargs):
             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.
+        lakes : str or list
+            *fill*\ [**+l**\ |**+r**\ ]
+            Set the shade, color, or pattern for lakes and river-lakes. The
+            default is the fill chosen for wet areas set by the ``water``
+            argument. Optionally, specify separate fills by appending
+            **+l** for lakes or **+r** for river-lakes, and passing multiple
+            strings in a list.
         resolution : str
             Selects the resolution of the data set to use ((f)ull, (h)igh,
             (i)ntermediate, (l)ow, and (c)rude).

pygmt/tests/test_coast.py

@@ -57,6 +57,7 @@ def test_coast_aliases():
         Y="a10c",
         p="135/25",
         t=13,
+        C="blue",
     )
     fig_test.coast(
         region=[-30, 30, -40, 40],  # R
@@ -74,6 +75,7 @@ def test_coast_aliases():
         yshift="a10c",  # Y
         perspective=[135, 25],  # p
         transparency=13,  # t
+        lakes="blue",  # C
     )
     return fig_ref, fig_test