Merge branch 'master' into grid_registration

Author: weiji14

.azure-pipelines.yml

@@ -12,6 +12,30 @@ on:
     - cron: '0 0 * * *'
 
 jobs:
+  style_check:
+    name: Style Checks
+    runs-on: ubuntu-latest
+
+    steps:
+      # Checkout current git repository
+      - name: Checkout
+        uses: actions/[email protected]
+
+      # Setup Miniconda
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+
+      - name: Install packages
+        run: pip install black flake8 pylint
+
+      - name: Formatting check (black and flake8)
+        run: make check
+
+      - name: Linting (pylint)
+        run: make lint
+
   test:
     name: ${{ matrix.os }} - Python ${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}

.github/workflows/ci_tests.yaml

@@ -40,10 +40,11 @@ The main advantages of this are:
 
 ## Continuous Integration
 
-We use TravisCI continuous integration (CI) services to build and test the
-project on Linux, and Mac (Windows is still a work in progress).
-The configuration file for this service is `.travis.yml`.
-It relies on the `requirements.txt` file to install the required dependencies using
+We use Github Actions and TravisCI continuous integration (CI) services to
+build and test the project on Linux, macOS and Windows.
+The configuration file for these services are in
+`.github/workflows/ci_tests.yaml` and `.travis.yml`.
+They rely on the `requirements.txt` file to install required dependencies using
 conda and the `Makefile` to run the tests and checks.
 
 Travis also handles all of our deployments automatically:

MAINTENANCE.md

@@ -12,9 +12,6 @@ PyGMT
 .. image:: http://img.shields.io/travis/GenericMappingTools/pygmt/master.svg?style=flat-square&label=Linux
     :alt: Travis CI build status
     :target: https://travis-ci.org/GenericMappingTools/pygmt
-.. image:: https://img.shields.io/azure-devops/build/GenericMappingTools/7682ad4e-76bb-4775-849e-7c4f8dce4e1a/3/master.svg?label=Mac|Windows&style=flat-square
-    :alt: Azure Pipelines build status
-    :target: https://dev.azure.com/GenericMappingTools/PyGMT/_build
 .. image:: https://github.com/GenericMappingTools/pygmt/workflows/Tests/badge.svg
     :alt: GitHub Actions build status
     :target: https://github.com/GenericMappingTools/pygmt/actions

README.rst

@@ -8,7 +8,8 @@
 elevation angle of the view. We provide a list of two arguments to ``frame`` — the
 second argument, prepended with ``"z"``, specifies the :math:`z`-axis frame attributes.
 Specifying the same scale for the ``projection`` and ``zcale`` arguments ensures equal
-axis scaling.
+axis scaling. The ``shading`` argument specifies illumination; here we choose an azimuth of
+45° with ``shading="+a45"``.
 """
 
 import pygmt
@@ -44,7 +45,8 @@ def ackley(x, y):
     zscale=f"{SCALE}i",
     surftype="s",
     cmap="roma",
-    perspective="135/30",
+    perspective=[135, 30],  # Azimuth southeast (135°), at elevation 30°
+    shading="+a45",
 )
 
 fig.show()

examples/gallery/grid/grdview_surface.py

@@ -336,6 +336,7 @@ def grdimage(self, grid, **kwargs):
         Wm="meshpen",
         Wf="facadepen",
         p="perspective",
+        I="shading",
     )
     @kwargs_to_strings(R="sequence", p="sequence")
     def grdview(self, grid, **kwargs):
@@ -403,6 +404,15 @@ def grdview(self, grid, **kwargs):
             ``'[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]'``.
             Select perspective view.
 
+        shading : str
+            Provide the name of a grid file with intensities in the (-1,+1)
+            range, or a constant intensity to apply everywhere (affects the
+            ambient light). Alternatively, derive an intensity grid from the
+            input data grid reliefgrid via a call to ``grdgradient``; append
+            ``+aazimuth``, ``+nargs``, and ``+mambient`` to specify azimuth,
+            intensity, and ambient arguments for that module, or just give
+            ``+d`` to select the default arguments (``+a-45+nt1+m0``).
+
         """
         kwargs = self._preprocess(**kwargs)
         kind = data_kind(grid, None, None)

pygmt/base_plotting.py

@@ -2,6 +2,7 @@
 Functions to convert data types into ctypes friendly formats.
 """
 import numpy as np
+import pandas as pd
 
 from ..exceptions import GMTInvalidInput
 
@@ -242,3 +243,82 @@ def kwargs_to_ctypes_array(argument, kwargs, dtype):
     if argument in kwargs:
         return dtype(*kwargs[argument])
     return None
+
+
+def array_to_datetime(array):
+    """
+    Convert an 1d datetime array from various types into pandas.DatetimeIndex
+    (i.e., numpy.datetime64).
+
+    If the input array is not in legal datetime formats, raise a "ParseError"
+    exception.
+
+    Parameters
+    ----------
+    array : list or 1d array
+        The input datetime array in various formats.
+
+        Supported types:
+
+        - str
+        - numpy.datetime64
+        - pandas.DateTimeIndex
+        - datetime.datetime and datetime.date
+
+    Returns
+    -------
+    array : 1d datetime array in pandas.DatetimeIndex (i.e., numpy.datetime64)
+
+    Examples
+    --------
+    >>> import datetime
+    >>> # numpy.datetime64 array
+    >>> x = np.array(
+    ...     ["2010-06-01", "2011-06-01T12", "2012-01-01T12:34:56"],
+    ...     dtype="datetime64",
+    ... )
+    >>> array_to_datetime(x)
+    DatetimeIndex(['2010-06-01 00:00:00', '2011-06-01 12:00:00',
+                   '2012-01-01 12:34:56'],
+                  dtype='datetime64[ns]', freq=None)
+
+    >>> # pandas.DateTimeIndex array
+    >>> x = pd.date_range("2013", freq="YS", periods=3)
+    >>> array_to_datetime(x)  # doctest: +NORMALIZE_WHITESPACE
+    DatetimeIndex(['2013-01-01', '2014-01-01', '2015-01-01'],
+                  dtype='datetime64[ns]', freq='AS-JAN')
+
+    >>> # Python's built-in date and datetime
+    >>> x = [datetime.date(2018, 1, 1), datetime.datetime(2019, 1, 1)]
+    >>> array_to_datetime(x)  # doctest: +NORMALIZE_WHITESPACE
+    DatetimeIndex(['2018-01-01', '2019-01-01'],
+        dtype='datetime64[ns]', freq=None)
+
+    >>> # Raw datetime strings in various format
+    >>> x = [
+    ...     "2018",
+    ...     "2018-02",
+    ...     "2018-03-01",
+    ...     "2018-04-01T01:02:03",
+    ...     "5/1/2018",
+    ...     "Jun 05, 2018",
+    ...     "2018/07/02",
+    ... ]
+    >>> array_to_datetime(x)
+    DatetimeIndex(['2018-01-01 00:00:00', '2018-02-01 00:00:00',
+                   '2018-03-01 00:00:00', '2018-04-01 01:02:03',
+                   '2018-05-01 00:00:00', '2018-06-05 00:00:00',
+                   '2018-07-02 00:00:00'],
+                  dtype='datetime64[ns]', freq=None)
+
+    >>> # Mixed datetime types
+    >>> x = [
+    ...    "2018-01-01",
+    ...    np.datetime64("2018-01-01"),
+    ...    datetime.datetime(2018, 1, 1),
+    ... ]
+    >>> array_to_datetime(x)  # doctest: +NORMALIZE_WHITESPACE
+    DatetimeIndex(['2018-01-01', '2018-01-01', '2018-01-01'],
+                  dtype='datetime64[ns]', freq=None)
+    """
+    return pd.to_datetime(array)

pygmt/clib/conversion.py

@@ -22,6 +22,7 @@
     vectors_to_arrays,
     dataarray_to_matrix,
     as_c_contiguous,
+    array_to_datetime,
 )
 
 FAMILIES = [
@@ -48,12 +49,13 @@
 REGISTRATIONS = ["GMT_GRID_PIXEL_REG", "GMT_GRID_NODE_REG"]
 
 DTYPES = {
-    "float64": "GMT_DOUBLE",
-    "float32": "GMT_FLOAT",
-    "int64": "GMT_LONG",
-    "int32": "GMT_INT",
-    "uint64": "GMT_ULONG",
-    "uint32": "GMT_UINT",
+    np.float64: "GMT_DOUBLE",
+    np.float32: "GMT_FLOAT",
+    np.int64: "GMT_LONG",
+    np.int32: "GMT_INT",
+    np.uint64: "GMT_ULONG",
+    np.uint32: "GMT_UINT",
+    np.datetime64: "GMT_DATETIME",
 }
 
 
@@ -710,15 +712,22 @@ def _check_dtype_and_dim(self, array, ndim):
         True
 
         """
-        if array.dtype.name not in DTYPES:
-            raise GMTInvalidInput(
-                "Unsupported numpy data type '{}'.".format(array.dtype.name)
-            )
+        # check the array has the given dimension
         if array.ndim != ndim:
             raise GMTInvalidInput(
                 "Expected a numpy 1d array, got {}d.".format(array.ndim)
             )
-        return self[DTYPES[array.dtype.name]]
+
+        # check the array has a valid/known data type
+        if array.dtype.type not in DTYPES:
+            try:
+                # Try to convert any unknown numpy data types to np.datetime64
+                array = np.asarray(array, dtype=np.datetime64)
+            except ValueError:
+                raise GMTInvalidInput(
+                    "Unsupported numpy data type '{}'.".format(array.dtype.type)
+                )
+        return self[DTYPES[array.dtype.type]]
 
     def put_vector(self, dataset, column, vector):
         """
@@ -764,7 +773,13 @@ def put_vector(self, dataset, column, vector):
         )
 
         gmt_type = self._check_dtype_and_dim(vector, ndim=1)
-        vector_pointer = vector.ctypes.data_as(ctp.c_void_p)
+        if gmt_type == self["GMT_DATETIME"]:
+            vector_pointer = (ctp.c_char_p * len(vector))()
+            vector_pointer[:] = np.char.encode(
+                np.datetime_as_string(array_to_datetime(vector))
+            )
+        else:
+            vector_pointer = vector.ctypes.data_as(ctp.c_void_p)
         status = c_put_vector(
             self.session_pointer, dataset, column, gmt_type, vector_pointer
         )

pygmt/clib/session.py

@@ -349,7 +349,7 @@ def test_put_vector_invalid_dtype():
             mode="GMT_CONTAINER_ONLY",
             dim=[2, 3, 1, 0],  # columns, rows, layers, dtype
         )
-        data = np.array([37, 12, 556], dtype="complex128")
+        data = np.array([37, 12, 556], dtype="object")
         with pytest.raises(GMTInvalidInput):
             lib.put_vector(dataset, column=1, vector=data)
 

pygmt/tests/baseline/test_plot_datetime.png

@@ -2,9 +2,13 @@
 """
 Tests plot.
 """
+import datetime
 import os
 
 import numpy as np
+import pandas as pd
+import xarray as xr
+
 import pytest
 
 from .. import Figure
@@ -284,3 +288,38 @@ def test_plot_scalar_xy():
     fig.plot(x=0, y=0, style="t1c")
     fig.plot(x=1.5, y=-1.5, style="s1c")
     return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_plot_datetime():
+    """Test various datetime input data"""
+    fig = Figure()
+    fig.basemap(projection="X15c/5c", region="2010-01-01/2020-01-01/0/10", frame=True)
+
+    # numpy.datetime64 types
+    x = np.array(
+        ["2010-06-01", "2011-06-01T12", "2012-01-01T12:34:56"], dtype="datetime64"
+    )
+    y = [1.0, 2.0, 3.0]
+    fig.plot(x, y, style="c0.2c", pen="1p")
+
+    # pandas.DatetimeIndex
+    x = pd.date_range("2013", freq="YS", periods=3)
+    y = [4, 5, 6]
+    fig.plot(x, y, style="t0.2c", pen="1p")
+
+    # xarray.DataArray
+    x = xr.DataArray(data=pd.date_range(start="2015-03", freq="QS", periods=3))
+    y = [7.5, 6, 4.5]
+    fig.plot(x, y, style="s0.2c", pen="1p")
+
+    # raw datetime strings
+    x = ["2016-02-01", "2017-03-04T00:00"]
+    y = [7, 8]
+    fig.plot(x, y, style="a0.2c", pen="1p")
+
+    # the Python built-in datetime and date
+    x = [datetime.date(2018, 1, 1), datetime.datetime(2019, 1, 1)]
+    y = [8.5, 9.5]
+    fig.plot(x, y, style="i0.2c", pen="1p")
+    return fig