Merge branch 'main' into coast-add-q-alias

michaelgrund · web-flow · commit 79e7a825df2d · 2022-02-08T18:02:30.000+01:00
diff --git a/.github/workflows/ci_tests.yaml b/.github/workflows/ci_tests.yaml
@@ -97,7 +97,7 @@ jobs:
           mamba install gmt=6.3.0 numpy=${{ matrix.numpy-version }} \
                         pandas xarray netCDF4 packaging \
                         ${{ matrix.optional-packages }} \
-                        dvc=2.8.2 make pytest>=6.0 \
+                        dvc make pytest>=6.0 \
                         pytest-cov pytest-mpl sphinx-gallery tomli
 
       # Show installed pkg information for postmortem diagnostic
diff --git a/.github/workflows/ci_tests_dev.yaml b/.github/workflows/ci_tests_dev.yaml
@@ -96,6 +96,12 @@ jobs:
                         dvc ipython 'pytest>=6.0' pytest-cov \
                         pytest-mpl sphinx-gallery tomli
 
+      # Pull baseline image data from dvc remote (DAGsHub)
+      - name: Pull baseline image data from dvc remote
+        run: |
+          dvc pull
+          ls -lhR pygmt/tests/baseline/
+
       # Build and install latest GMT from GitHub
       - name: Install GMT ${{ matrix.gmt_git_ref }} branch (Linux/macOS)
         run: curl https://raw.githubusercontent.com/GenericMappingTools/gmt/master/ci/build-gmt.sh | bash
@@ -126,11 +132,6 @@ jobs:
           touch ~/.gmt/server/gmt_data_server.txt ~/.gmt/server/gmt_hash_server.txt
           ls -lhR ~/.gmt
 
-      # Pull baseline image data from dvc remote (DAGsHub)
-      - name: Pull baseline image data from dvc remote
-        run: |
-          dvc pull
-          ls -lhR pygmt/tests/baseline/
 
       # Install the package that we want to test
       - name: Install the package
diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.yml
@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # Drafts your next Release notes as Pull Requests are merged into "main"
-      - uses: release-drafter/release-drafter@v5.17.5
+      - uses: release-drafter/release-drafter@v5.17.6
         with:
           # (Optional) specify config name to use, relative to .github/. Default: release-drafter.yml
           config-name: release-drafter.yml
diff --git a/README.rst b/README.rst
@@ -77,6 +77,19 @@ Project goals
   ``xarray.DataArray`` for grids.
 
 
+Quickstart
+----------
+
+Installation
+++++++++++++
+
+Simple installation using `conda <https://docs.conda.io/projects/conda/en/latest/user-guide/index.html>`__::
+
+    conda install --channel conda-forge pygmt
+
+For other ways to install ``pygmt``, see `full installation instructions <https://www.pygmt.org/latest/install.html>`__.
+
+
 Contacting Us
 -------------
 
@@ -214,7 +227,7 @@ Compatibility with GMT/Python/NumPy versions
       - Documentation
       - GMT
       - Python
-      - Numpy
+      - NumPy
     * - `Dev <https://github.com/GenericMappingTools/pygmt/milestone/9>`_ (upcoming release)
       - `Dev Documentation <https://www.pygmt.org/dev>`_ (reflects `main branch <https://github.com/GenericMappingTools/pygmt>`_)
       - >=6.3.0
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -126,8 +126,8 @@ Operations on tabular data
     surface
     xyz2grd
 
-Operations on grids
-~~~~~~~~~~~~~~~~~~~
+Operations on raster data
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autosummary::
     :toctree: generated
diff --git a/doc/contributing.md b/doc/contributing.md
@@ -168,7 +168,7 @@ To increase the chances of getting your pull request accepted quickly, try to:
 * Have a good coding style
   - Use readable code, as it is better than clever code (even with comments).
   - Follow the [PEP8](http://pep8.org) style guide for code and the
-    [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html)
+    [NumPy style guide](https://numpydoc.readthedocs.io/en/latest/format.html)
     for docstrings. Please refer to [Code style](#code-style).
 
 Pull requests will automatically have tests run by GitHub Actions.
@@ -367,7 +367,7 @@ the documentation.
 
 The API documentation is built from the docstrings in the Python `*.py` files under
 the `pygmt/src/` and `/pygmt/datasets/` folders. **All docstrings** should follow the
-[numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard).
+[NumPy style guide](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard).
 All functions/classes/methods should have docstrings with a full description of all
 arguments and return values.
 
diff --git a/examples/gallery/3d_plots/grdview_surface.py b/examples/gallery/3d_plots/grdview_surface.py
@@ -23,7 +23,7 @@
 # https://en.wikipedia.org/wiki/Ackley_function
 def ackley(x, y):
     return (
-        -20 * np.exp(-0.2 * np.sqrt(0.5 * (x ** 2 + y ** 2)))
+        -20 * np.exp(-0.2 * np.sqrt(0.5 * (x**2 + y**2)))
         - np.exp(0.5 * (np.cos(2 * np.pi * x) + np.cos(2 * np.pi * y)))
         + np.exp(1)
         + 20
diff --git a/examples/gallery/basemaps/double_y_axes.py b/examples/gallery/basemaps/double_y_axes.py
@@ -23,7 +23,7 @@ class can control which axes should be plotted and optionally show annotations,
 # Generate two sample Y data from one common X data
 x = np.linspace(1.0, 9.0, num=9)
 y1 = x
-y2 = x ** 2 + 110
+y2 = x**2 + 110
 
 fig = pygmt.Figure()
 
diff --git a/examples/gallery/images/contours.py b/examples/gallery/images/contours.py
@@ -25,7 +25,7 @@
 
 # build the contours underlying data with the function z = x^2 + y^2
 X, Y = np.meshgrid(np.linspace(-10, 10, 50), np.linspace(-10, 10, 50))
-Z = X ** 2 + Y ** 2
+Z = X**2 + Y**2
 x, y, z = X.flatten(), Y.flatten(), Z.flatten()
 
 
diff --git a/examples/projections/nongeo/cartesian_logarithmic.py b/examples/projections/nongeo/cartesian_logarithmic.py
@@ -12,11 +12,11 @@
 # Create a list of x values 0-100
 xline = np.arange(0, 101)
 # Create a list of y-values that are the square root of the x-values
-yline = xline ** 0.5
+yline = xline**0.5
 # Create a list of x values for every 10 in 0-100
 xpoints = np.arange(0, 101, 10)
 # Create a list of y-values that are the square root of the x-values
-ypoints = xpoints ** 0.5
+ypoints = xpoints**0.5
 
 fig = pygmt.Figure()
 fig.plot(
diff --git a/examples/projections/nongeo/cartesian_power.py b/examples/projections/nongeo/cartesian_power.py
@@ -13,7 +13,7 @@
 # Create a list of y values 0-10
 yvalues = np.arange(0, 11)
 # Create a list of x-values that are the square of the y-values
-xvalues = yvalues ** 2
+xvalues = yvalues**2
 
 fig = pygmt.Figure()
 fig.plot(
diff --git a/examples/tutorials/basics/plot.py b/examples/tutorials/basics/plot.py
@@ -57,7 +57,7 @@
 fig.plot(
     x=data.longitude,
     y=data.latitude,
-    size=0.02 * (2 ** data.magnitude),
+    size=0.02 * (2**data.magnitude),
     style="cc",
     color="white",
     pen="black",
@@ -85,7 +85,7 @@
 fig.plot(
     x=data.longitude,
     y=data.latitude,
-    size=0.02 * 2 ** data.magnitude,
+    size=0.02 * 2**data.magnitude,
     color=data.depth_km,
     cmap=True,
     style="cc",
diff --git a/pygmt/__init__.py b/pygmt/__init__.py
@@ -94,7 +94,7 @@ def show_versions():
 
     - PyGMT itself
     - System information (Python version, Operating System)
-    - Core dependency versions (Numpy, Pandas, Xarray, etc)
+    - Core dependency versions (NumPy, Pandas, Xarray, etc)
     - GMT library information
     """
 
diff --git a/pygmt/figure.py b/pygmt/figure.py
@@ -181,9 +181,9 @@ def psconvert(self, icc_gray=False, **kwargs):
             adding margins. Append **+m** to specify extra margins to extend
             the bounding box. Give either one (uniform), two (x and y) or four
             (individual sides) margins; append unit [Default is set by
-            :term:`PROJ_LENGTH_UNIT`]. Append **+s**\ *width* to resize the
-            output image to exactly *width* units. The default unit is set
-            by :term:`PROJ_LENGTH_UNIT` but you can append a new unit and/or
+            :gmt-term:`PROJ_LENGTH_UNIT`]. Append **+s**\ *width* to resize the
+            output image to exactly *width* units. The default unit is set by
+            :gmt-term:`PROJ_LENGTH_UNIT` but you can append a new unit and/or
             impose different width and height (**Note**: This may change the
             image aspect ratio). What happens here is that Ghostscript will do
             the re-interpolation work and the final image will retain the DPI
@@ -195,7 +195,7 @@ def psconvert(self, icc_gray=False, **kwargs):
         bb_style : str
             Set optional BoundingBox fill color, fading, or draw the outline
             of the BoundingBox. Append **+f**\ *fade* to fade the entire plot
-            towards black (100%) [no fading, 0]. Append **+g** \*paint* to
+            towards black (100%) [no fading, 0]. Append **+g**\ *paint* to
             paint the BoundingBox behind the illustration and append **+p**\
             [*pen*] to draw the BoundingBox outline (append a pen or accept
             the default pen of 0.25p,black). Note: If both **+g** and **+f**
diff --git a/pygmt/src/grdclip.py b/pygmt/src/grdclip.py
@@ -77,6 +77,26 @@ def grdclip(grid, **kwargs):
         - :class:`xarray.DataArray` if ``outgrid`` is not set
         - None if ``outgrid`` is set (grid output will be stored in file set by
           ``outgrid``)
+
+    Examples
+    --------
+    >>> import pygmt  # doctest: +SKIP
+    >>> # Load a grid of @earth_relief_30m data, with an x-range of 10 to 30,
+    >>> # and a y-range of 15 to 25
+    >>> grid = pygmt.datasets.load_earth_relief(
+    ...     resolution="30m", region=[10, 30, 15, 25]
+    ... )  # doctest: +SKIP
+    >>> # Report the minimum and maximum data values
+    >>> [grid.data.min(), grid.data.max()]  # doctest: +SKIP
+    [179.0, 2103.0]
+    >>> # Create a new grid from an input grid. Set all values below 1,000 to
+    >>> # 0 and all values above 1,500 to 10,000
+    >>> new_grid = pygmt.grdclip(
+    ...     grid=grid, below=[1000, 0], above=[1500, 10000]
+    ... )  # doctest: +SKIP
+    >>> # Report the minimum and maximum data values
+    >>> [new_grid.data.min(), new_grid.data.max()]  # doctest: +SKIP
+    [0.0, 10000.0]
     """
     with GMTTempFile(suffix=".nc") as tmpfile:
         with Session() as lib:
diff --git a/pygmt/src/grdcut.py b/pygmt/src/grdcut.py
@@ -87,6 +87,20 @@ def grdcut(grid, **kwargs):
         - :class:`xarray.DataArray` if ``outgrid`` is not set
         - None if ``outgrid`` is set (grid output will be stored in file set by
           ``outgrid``)
+
+    Examples
+    --------
+    >>> import pygmt  # doctest: +SKIP
+    >>> # Load a grid of @earth_relief_30m data, with an x-range of 10 to 30,
+    >>> # and a y-range of 15 to 25
+    >>> grid = pygmt.datasets.load_earth_relief(
+    ...     resolution="30m", region=[10, 30, 15, 25]
+    ... )  # doctest: +SKIP
+    >>> # Create a new grid from an input grid, with an x-range of 12 to 15,
+    >>> # and a y-range of 21 to 24
+    >>> new_grid = pygmt.grdcut(
+    ...     grid=grid, region=[12, 15, 21, 24]
+    ... )  # doctest: +SKIP
     """
     with GMTTempFile(suffix=".nc") as tmpfile:
         with Session() as lib:
diff --git a/pygmt/tests/test_clib_loading.py b/pygmt/tests/test_clib_loading.py
@@ -142,9 +142,9 @@ def test_two_broken_libraries(self, mock_ctypes):  # pylint: disable=unused-argu
         # pylint: disable=protected-access
         lib_fullnames = [self.faked_libgmt1, self.faked_libgmt2]
         msg_regex = (
-            fr"Error loading GMT shared library at '{self.faked_libgmt1._name}'.\n"
-            fr"Error loading '{self.faked_libgmt1._name}'. Couldn't access.*\n"
-            fr"Error loading GMT shared library at '{self.faked_libgmt2._name}'.\n"
+            rf"Error loading GMT shared library at '{self.faked_libgmt1._name}'.\n"
+            rf"Error loading '{self.faked_libgmt1._name}'. Couldn't access.*\n"
+            rf"Error loading GMT shared library at '{self.faked_libgmt2._name}'.\n"
             f"Error loading '{self.faked_libgmt2._name}'. Couldn't access.*"
         )
         with pytest.raises(GMTCLibNotFoundError, match=msg_regex):
@@ -162,9 +162,9 @@ def test_load_brokenlib_invalidpath(
         # pylint: disable=protected-access
         lib_fullnames = [self.faked_libgmt1, self.invalid_path]
         msg_regex = (
-            fr"Error loading GMT shared library at '{self.faked_libgmt1._name}'.\n"
-            fr"Error loading '{self.faked_libgmt1._name}'. Couldn't access.*\n"
-            fr"Error loading GMT shared library at '{self.invalid_path}'.\n"
+            rf"Error loading GMT shared library at '{self.faked_libgmt1._name}'.\n"
+            rf"Error loading '{self.faked_libgmt1._name}'. Couldn't access.*\n"
+            rf"Error loading GMT shared library at '{self.invalid_path}'.\n"
             f"Unable to find '{self.invalid_path}'"
         )
         with pytest.raises(GMTCLibNotFoundError, match=msg_regex):
diff --git a/pygmt/tests/test_contour.py b/pygmt/tests/test_contour.py
@@ -41,8 +41,8 @@ def test_contour_vec(region):
     )
     x = x.flatten()
     y = y.flatten()
-    z = (x - 0.5 * (region[0] + region[1])) ** 2 + 4 * y ** 2
-    z = np.exp(-z / 10 ** 2 * np.log(2))
+    z = (x - 0.5 * (region[0] + region[1])) ** 2 + 4 * y**2
+    z = np.exp(-z / 10**2 * np.log(2))
     fig.contour(x=x, y=y, z=z, projection="X10c", region=region, frame="a", pen=True)
     return fig
 
@@ -89,8 +89,8 @@ def test_contour_deprecate_columns_to_incols(region):
     )
     x = x.flatten()
     y = y.flatten()
-    z = (x - 0.5 * (region[0] + region[1])) ** 2 + 4 * y ** 2
-    z = np.exp(-z / 10 ** 2 * np.log(2))
+    z = (x - 0.5 * (region[0] + region[1])) ** 2 + 4 * y**2
+    z = np.exp(-z / 10**2 * np.log(2))
 
     # generate dataframe
     # switch x and y from here onwards to simulate different column order
diff --git a/pygmt/tests/test_datasets_earth_relief.py b/pygmt/tests/test_datasets_earth_relief.py
@@ -28,7 +28,7 @@ def test_earth_relief_01d():
     assert data.shape == (181, 361)
     npt.assert_allclose(data.lat, np.arange(-90, 91, 1))
     npt.assert_allclose(data.lon, np.arange(-180, 181, 1))
-    npt.assert_allclose(data.min(), -8592.5)
+    npt.assert_allclose(data.min(), -8600.5)
     npt.assert_allclose(data.max(), 5559.0)
 
 
@@ -42,7 +42,7 @@ def test_earth_relief_01d_with_region():
     assert data.shape == (11, 21)
     npt.assert_allclose(data.lat, np.arange(-5, 6, 1))
     npt.assert_allclose(data.lon, np.arange(-10, 11, 1))
-    npt.assert_allclose(data.min(), -5145)
+    npt.assert_allclose(data.min(), -5147)
     npt.assert_allclose(data.max(), 805.5)
 
 
@@ -54,7 +54,7 @@ def test_earth_relief_30m():
     assert data.shape == (361, 721)
     npt.assert_allclose(data.lat, np.arange(-90, 90.5, 0.5))
     npt.assert_allclose(data.lon, np.arange(-180, 180.5, 0.5))
-    npt.assert_allclose(data.min(), -9460.5)
+    npt.assert_allclose(data.min(), -9454.5)
     npt.assert_allclose(data.max(), 5887.5)
 
 
