Merge branch 'main' into alias-system

Author: seisman

.github/workflows/ci_tests.yaml

@@ -142,7 +142,6 @@ jobs:
             pytest-doctestplus
             pytest-mpl
             pytest-rerunfailures
-            pytest-xdist
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
@@ -165,7 +164,7 @@ jobs:
 
       # Run the regular tests
       - name: Run tests
-        run: make test PYTEST_EXTRA="-r P -n auto --reruns 2"
+        run: make test PYTEST_EXTRA="-r P --reruns 2"
 
       # Upload diff images on test failure
       - name: Upload diff images if any test fails

.github/workflows/ci_tests_dev.yaml

@@ -153,7 +153,7 @@ jobs:
                         --extra-index https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \
                         numpy pandas xarray netCDF4 packaging \
                         build contextily dvc geopandas ipython pyarrow rioxarray \
-                        pytest pytest-cov pytest-doctestplus pytest-mpl pytest-rerunfailures pytest-xdist\
+                        pytest pytest-cov pytest-doctestplus pytest-mpl pytest-rerunfailures \
                         sphinx-gallery
 
       # Show installed pkg information for postmortem diagnostic
@@ -181,7 +181,7 @@ jobs:
 
       # Run the tests
       - name: Test with pytest
-        run: make test PYTEST_EXTRA="-r P -n auto --reruns 2"
+        run: make test PYTEST_EXTRA="-r P --reruns 2"
         env:
           GMT_LIBRARY_PATH: ${{ runner.temp }}/gmt-install-dir/lib
 

doc/Makefile

@@ -55,7 +55,5 @@ server:
 clean:
 	rm -rf $(BUILDDIR)
 	rm -rf api/generated
-	rm -rf intro
-	rm -rf tutorials
-	rm -rf gallery
-	rm -rf projections
+	rm -rf intro tutorials gallery projections
+	rm -rf sg_execution_times.rst

examples/tutorials/basics/polygons.py

@@ -0,0 +1,100 @@
+"""
+Plotting polygons
+=================
+
+Plotting polygons is handled by the :meth:`pygmt.Figure.plot` method.
+
+This tutorial focuses on input data given as NumPy arrays. Besides NumPy arrays,
+array-like objects are supported. Here, a polygon is a closed shape defined by a series
+of data points with x and y coordinates, connected by line segments, with the start and
+end points being identical. For plotting a :class:`geopandas.GeoDataFrame` object with
+polygon geometries, e.g., to create a choropleth map, see the gallery example
+:doc:`Choropleth map </gallery/maps/choropleth_map>`.
+"""
+
+# %%
+import numpy as np
+import pygmt
+
+# %%
+# Plot polygons
+# -------------
+#
+# Set up sample data points as NumPy arrays for the x and y values.
+
+x = np.array([-2, 1, 3, 0, -4, -2])
+y = np.array([-3, -1, 1, 3, 2, -3])
+
+# %%
+# Create a Cartesian plot via the :meth:`pygmt.Figure.basemap` method. Pass arrays to
+# the ``x`` and ``y`` parameters of the :meth:`pygmt.Figure.plot` method. Without
+# further adjustments, lines are drawn between the data points. By default, the lines
+# are 0.25-points thick, black, and solid. In this example, the data points are chosen
+# to make the lines form a polygon.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+fig.plot(x=x, y=y)
+fig.show()
+
+# %%
+# The ``pen`` parameter can be used to adjust the lines or outline of the polygon. The
+# argument passed to ``pen`` is one string with the comma-separated optional values
+# *width*,\ *color*,\ *style*.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+# Use a 2-points thick, darkred, dashed outline
+fig.plot(x=x, y=y, pen="2p,darkred,dashed")
+fig.show()
+
+# %%
+# Use the ``fill`` parameter to fill the polygon with a color or
+# :doc:`pattern </techref/patterns>`. Note, that there are no lines drawn between the
+# data points by default if ``fill`` is used. Use the ``pen`` parameter to add an
+# outline around the polygon.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+# Fill the polygon with color "orange"
+fig.plot(x=x, y=y, fill="orange")
+fig.show()
+
+
+# %%
+# Close polygons
+# --------------
+#
+# Set up sample data points as NumPy array for the x and y values. Now, the data points
+# do not form a polygon.
+
+x = np.array([-2, 1, 3, 0, -4])
+y = np.array([-3, -1, 1, 3, 2])
+
+# %%
+# The ``close`` parameter can be used to force the polygon to be closed.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+fig.plot(x=x, y=y, pen=True)
+
+fig.shift_origin(xshift="w+1c")
+
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+fig.plot(x=x, y=y, pen=True, close=True)
+fig.show()
+
+# %%
+# When using the ``fill`` parameter, the polygon is automatically closed.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+fig.plot(x=x, y=y, pen=True)
+
+fig.shift_origin(xshift="w+1c")
+
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+fig.plot(x=x, y=y, pen=True, fill="orange")
+fig.show()
+
+# sphinx_gallery_thumbnail_number = 5

pygmt/helpers/utils.py

@@ -12,6 +12,7 @@
 import time
 import webbrowser
 from collections.abc import Iterable, Mapping, Sequence
+from pathlib import Path
 from typing import Any, Literal
 
 import xarray as xr
@@ -187,7 +188,8 @@ def _check_encoding(argstr: str) -> Encoding:
         charset["ZapfDingbats"].values()
     )
     for encoding in ["ISOLatin1+"] + [f"ISO-8859-{i}" for i in range(1, 17) if i != 12]:
-        if all(c in (set(charset[encoding].values()) | adobe_chars) for c in argstr):
+        chars = set(charset[encoding].values()) | adobe_chars
+        if all(c in chars for c in argstr):
             return encoding  # type: ignore[return-value]
     # Return the "ISOLatin1+" encoding if the string contains characters from multiple
     # charset encodings or contains characters that are not in any charset encoding.
@@ -580,7 +582,7 @@ def launch_external_viewer(fname: str, waiting: float = 0):
         case "win32":  # Windows
             os.startfile(fname)  # type:ignore[attr-defined] # noqa: S606
         case _:  # Fall back to the browser if can't recognize the operating system.
-            webbrowser.open_new_tab(f"file://{fname}")
+            webbrowser.open_new_tab(f"file://{Path(fname).resolve()}")
     if waiting > 0:
         # Preview images will be deleted when a GMT modern-mode session ends, but the
         # external viewer program may take a few seconds to open the images.

pygmt/src/binstats.py

@@ -80,7 +80,7 @@ def binstats(
         Set the value assigned to empty nodes [Default is NaN].
     normalize : bool
         Normalize the resulting grid values by the area represented by the
-        search *radius* [no normalization].
+        search *radius* [Default is no normalization].
     search_radius : float or str
         Set the *search_radius* that determines which data points are
         considered close to a node. Append the distance unit.
@@ -106,7 +106,7 @@ def binstats(
         Return type depends on whether the ``outgrid`` parameter is set:
 
         - :class:`xarray.DataArray` if ``outgrid`` is not set
-        - None if ``outgrid`` is set (grid output will be stored in file set by
+        - ``None`` if ``outgrid`` is set (grid output will be stored in the file set by
           ``outgrid``)
     """
     alias = AliasSystem(

pygmt/src/blockm.py

@@ -244,7 +244,7 @@ def blockmedian(
     ret
         Return type depends on ``outfile`` and ``output_type``:
 
-        - ``None`` if ``outfile`` is set (output will be stored in file set by
+        - ``None`` if ``outfile`` is set (output will be stored in the file set by
           ``outfile``)
         - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set
           (depends on ``output_type``)
@@ -342,7 +342,7 @@ def blockmode(
     ret
         Return type depends on ``outfile`` and ``output_type``:
 
-        - ``None`` if ``outfile`` is set (output will be stored in file set by
+        - ``None`` if ``outfile`` is set (output will be stored in the file set by
           ``outfile``)
         - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set
           (depends on ``output_type``)

pygmt/src/dimfilter.py

@@ -88,12 +88,12 @@ def dimfilter(grid, outgrid: str | None = None, **kwargs) -> xr.DataArray | None
     spacing : str or list
         *x_inc* [and optionally *y_inc*] is the output increment. Append
         **m** to indicate minutes, or **c** to indicate seconds. If the new
-        *x_inc*, *y_inc* are NOT integer multiples of the old ones (in the
+        *x_inc*, *y_inc* are **not** integer multiples of the old ones (in the
         input data), filtering will be considerably slower. [Default is same
-        as input.]
+        as the input.]
     region : str or list
         [*xmin*, *xmax*, *ymin*, *ymax*].
-        Define the region of the output points [Default is same as input].
+        Define the region of the output points [Default is the same as the input].
     {verbose}
 
     Returns
@@ -102,7 +102,7 @@ def dimfilter(grid, outgrid: str | None = None, **kwargs) -> xr.DataArray | None
         Return type depends on whether the ``outgrid`` parameter is set:
 
         - :class:`xarray.DataArray` if ``outgrid`` is not set
-        - None if ``outgrid`` is set (grid output will be stored in file set by
+        - ``None`` if ``outgrid`` is set (grid output will be stored in the file set by
           ``outgrid``)
 
     Example

pygmt/src/filter1d.py

@@ -105,7 +105,8 @@ def filter1d(
     ret
         Return type depends on ``outfile`` and ``output_type``:
 
-        - None if ``outfile`` is set (output will be stored in file set by ``outfile``)
+        - ``None`` if ``outfile`` is set (output will be stored in the file set by
+          ``outfile``)
         - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set
           (depends on ``output_type``)
     """

pygmt/src/grd2xyz.py

@@ -121,7 +121,8 @@ def grd2xyz(
     ret
         Return type depends on ``outfile`` and ``output_type``:
 
-        - None if ``outfile`` is set (output will be stored in file set by ``outfile``)
+        - ``None`` if ``outfile`` is set (output will be stored in the file set by
+          ``outfile``)
         - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set
           (depends on ``output_type``)
 
@@ -133,7 +134,7 @@ def grd2xyz(
     >>> grid = pygmt.datasets.load_earth_relief(
     ...     resolution="30m", region=[10, 30, 15, 25]
     ... )
-    >>> # Create a pandas DataFrame with the xyz data from an input grid
+    >>> # Create a pandas.DataFrame with the xyz data from an input grid
     >>> xyz_dataframe = pygmt.grd2xyz(grid=grid, output_type="pandas")
     >>> xyz_dataframe.head(n=2)
         lon   lat          z