Merge branch 'main' into python-3.12

Author: weiji14

.github/release-drafter.yml

@@ -27,6 +27,21 @@ exclude-contributors:
 category-template: '### $TITLE'
 change-template: '* $TITLE ([#$NUMBER]($URL))'
 sort-by: 'title'
+replacers:
+  - search: '/@(\w+)?/g'
+    replace: '[@$1](https://github.com/$1)'
+  - search: '@maxrjones'
+    replace: 'Max Jones'
+  - search: '@michaelgrund'
+    replace: 'Michael Grund'
+  - search: '@seisman'
+    replace: 'Dongdong Tian'
+  - search: '@weiji14'
+    replace: 'Wei Ji Leong'
+  - search: '@willschlitzer'
+    replace: 'Will Schlitzer'
+  - search: '@yvonnefroehlich'
+    replace: 'Yvonne Fröhlich'
 template: |
   ## Release v$RESOLVED_VERSION (20YY/MM/DD)
 

.github/workflows/ci_docs.yml

@@ -77,6 +77,7 @@ jobs:
           create-args: >-
             python=3.12
             gmt=6.4.0
+            ghostscript=9.54.0
             numpy
             pandas
             xarray

.github/workflows/ci_tests_dev.yaml

@@ -3,10 +3,8 @@
 # This workflow runs regular PyGMT tests with the GMT dev version, and also
 # pre-release versions of several dependencies like NumPy, Pandas, Xarray, etc.
 # If any tests fail, it also uploads the diff images as workflow artifacts.
-# On Linux/macOS, GMT dev version is installed by fetching the latest source
-# codes from the GMT master branch and compiling.
-# On Windows, GMT dev version is installed from the conda-forge's dev channel
-# due to the complexity of building GMT source codes on Windows.
+# The GMT dev version is installed by fetching the latest source codes from
+# the GMT master branch and compiling.
 #
 # It is triggered when a pull request is marked as "ready as review", or using
 # the slash command `/test-gmt-dev`. It is also scheduled to run on Monday,
@@ -80,7 +78,7 @@ jobs:
           fetch-depth: 0
 
       - name: Show job URL
-        uses: peter-evans/create-or-update-comment@v3.0.2
+        uses: peter-evans/create-or-update-comment@v3.1.0
         if: github.event_name == 'repository_dispatch' && (matrix.os == 'ubuntu-latest')
         with:
           token: ${{ steps.generate-token.outputs.token }}
@@ -116,6 +114,38 @@ jobs:
             pcre
             zlib
 
+      # 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
+        env:
+          GMT_GIT_REF: ${{ matrix.gmt_git_ref }}
+          GMT_INSTALL_DIR: ${{ github.workspace }}/gmt-install-dir
+        if: runner.os != 'Windows'
+
+      - name: Install GMT ${{ matrix.gmt_git_ref }} branch (Windows)
+        shell: cmd
+        run: |
+          git clone --depth=1 --single-branch --branch ${{ env.GMT_GIT_REF }} https://github.com/GenericMappingTools/gmt
+          cd gmt/
+          mkdir build
+          cd build
+          call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat"
+          cmake -G Ninja .. ^
+            -DCMAKE_INSTALL_PREFIX=${{ env.GMT_INSTALL_DIR }} ^
+            -DCMAKE_BUILD_TYPE=Release ^
+            -DCMAKE_PREFIX_PATH=${{ env.MAMBA_ROOT_PREFIX }}\envs\pygmt\Library ^
+            -DGMT_ENABLE_OPENMP=TRUE ^
+            -DGMT_USE_THREADS=TRUE
+          cmake --build .
+          cmake --build . --target install
+        env:
+          GMT_GIT_REF: ${{ matrix.gmt_git_ref }}
+          GMT_INSTALL_DIR: ${{ github.workspace }}/gmt-install-dir
+        if: runner.os == 'Windows'
+
+      - name: Add GMT's bin to PATH
+        run: echo '${{ github.workspace }}/gmt-install-dir/bin' >> $GITHUB_PATH
+
       # Install dependencies from PyPI
       - name: Install dependencies
         run: |
@@ -136,18 +166,6 @@ jobs:
           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
-        env:
-          GMT_GIT_REF: ${{ matrix.gmt_git_ref }}
-          GMT_INSTALL_DIR: ${{ github.workspace }}/gmt-install-dir
-        if: runner.os != 'Windows'
-
-      - name: Install GMT dev version from conda-forge (Windows)
-        run: micromamba install -c conda-forge/label/dev gmt
-        if: runner.os == 'Windows'
-
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
         uses: dawidd6/action-download-artifact@v2.28.0
@@ -170,21 +188,11 @@ jobs:
       - name: Install the package
         run: make install
 
-      - name: Add GMT's bin to PATH (Linux/macOS)
-        run: echo ${GITHUB_WORKSPACE}/gmt-install-dir/bin >> $GITHUB_PATH
-        if: runner.os != 'Windows'
-
       # Run the tests
-      - name: Test with pytest (Linux/macOS)
+      - name: Test with pytest
         run: make test PYTEST_EXTRA="-r P"
         env:
           GMT_LIBRARY_PATH: ${{ github.workspace }}/gmt-install-dir/lib
-        if: runner.os != 'Windows'
-
-      # Run the tests
-      - name: Test with pytest (Windows)
-        run: make test PYTEST_EXTRA="-r P"
-        if: runner.os == 'Windows'
 
       # Upload diff images on test failure
       - name: Upload diff images if any test fails

.github/workflows/dvc-diff.yml

@@ -32,12 +32,6 @@ jobs:
     - name: Setup continuous machine learning (CML)
       uses: iterative/setup-cml@v2.0.0
 
-    # workaround from https://github.com/iterative/cml/issues/1377
-    - name: Setup NodeJS
-      uses: actions/setup-node@v3.8.1
-      with:
-        node-version: '16'
-
     # Produce the markdown diff report, which should look like:
     # ## Summary of changed images
     #
@@ -76,7 +70,7 @@ jobs:
         cp pygmt/tests/baseline/*.png pygmt/tests/baseline-new/
         # Pull images in the main branch from cloud storage
         git checkout main
-        dvc pull --remote upstream
+        dvc pull --remote upstream --force
 
         # Append each image to the markdown report
         echo -e "## Image diff(s)\n" >> report.md

.github/workflows/format-command.yml

@@ -50,7 +50,7 @@ jobs:
           fi
 
       - name: Add reaction
-        uses: peter-evans/create-or-update-comment@v3.0.2
+        uses: peter-evans/create-or-update-comment@v3.1.0
         with:
           token: ${{ steps.generate-token.outputs.token }}
           repository: ${{ github.event.client_payload.github.payload.repository.full_name }}

.github/workflows/release-baseline-images.yml

@@ -37,7 +37,7 @@ jobs:
         shasum -a 256 baseline-images.zip
 
     - name: Upload baseline image as a release asset
-      uses: shogo82148/actions-upload-release-asset@v1.7.0
+      uses: shogo82148/actions-upload-release-asset@v1.7.2
       with:
         upload_url: ${{ github.event.release.upload_url }}
         asset_path: baseline-images.zip

ci/requirements/docs.yml

@@ -5,6 +5,7 @@ channels:
 dependencies:
     # Required dependencies
     - gmt=6.4.0
+    - ghostscript=9.54.0
     - numpy>=1.22
     - pandas
     - xarray

examples/gallery/embellishments/legend.py

@@ -3,32 +3,60 @@
 ======
 
 The :meth:`pygmt.Figure.legend` method can automatically create a legend for
-symbols plotted using :meth:`pygmt.Figure.plot`. Legend entries are only
-created when the ``label`` parameter is used. For more complicated legends,
-including legends with multiple columns, users have to write an ASCII file
-with instructions for the layout of the legend items and pass it
-to the ``spec`` parameter of :meth:`pygmt.Figure.legend`. For details on
-how to set up such a file, please see the GMT documentation at
-:gmt-docs:`legend.html#legend-codes`.
+symbols plotted using :meth:`pygmt.Figure.plot`. A legend entry is only added
+when the ``label`` parameter is used to state the desired text. Optionally,
+to adjust the legend, users can append different modifiers. A list of all
+available modifiers can be found at :gmt-docs:`gmt.html#l-full`. To create a
+multiple-column legend **+N** is used with the desired number of columns.
+For more complicated legends, users may want to write an ASCII file with
+instructions for the layout of the legend items and pass it to the ``spec``
+parameter of :meth:`pygmt.Figure.legend`. For details on how to set up such a
+file, please see the GMT documentation at :gmt-docs:`legend.html#legend-codes`.
 """
 
 # %%
+import numpy as np
 import pygmt
 
-fig = pygmt.Figure()
+# Set up some test data
+x = np.arange(-10, 10.2, 0.2)
+y1 = np.sin(x) + 1.1
+y2 = np.cos(x) + 1.1
+y3 = np.sin(x / 2) - 1.1
+y4 = np.cos(x / 2) - 1.1
 
-fig.basemap(projection="x2c", region=[0, 7, 3, 7], frame=True)
+# Create new Figure() object
+fig = pygmt.Figure()
 
-fig.plot(
-    data="@Table_5_11.txt",
-    style="c0.40c",
-    fill="lightgreen",
-    pen="faint",
-    label="Apples",
+fig.basemap(
+    projection="X10c/7c",
+    region=[-10, 10, -3.5, 3.5],
+    frame=["WSne", "xaf+lx", "ya1f0.5+ly"],
 )
-fig.plot(data="@Table_5_11.txt", pen="1.5p,gray", label="My lines")
-fig.plot(data="@Table_5_11.txt", style="t0.40c", fill="orange", label="Oranges")
 
+# -----------------------------------------------------------------------------
+# Top: Vertical legend (one column, default)
+
+# Use the label parameter to state the text label for the legend entry
+fig.plot(x=x, y=y1, pen="1p,green3", label="sin(x)+1.1")
+
+fig.plot(x=x, y=y2, style="c0.07c", fill="dodgerblue", label="cos(x)+1.1")
+
+# Add a legend to the plot; place it within the plot bounding box with both
+# reference ("J") and anchor ("+j") points being TopRight and with an offset
+# of 0.2 centimeters in x and y directions; surround the legend with a box
 fig.legend(position="JTR+jTR+o0.2c", box=True)
 
+# -----------------------------------------------------------------------------
+# Bottom: Horizontal legend (here two columns)
+
+# +N sets the number of columns corresponding to the given number, here 2
+fig.plot(x=x, y=y3, pen="1p,darkred,-", label="sin(x/2)-1.1+N2")
+
+fig.plot(x=x, y=y4, style="s0.07c", fill="orange", label="cos(x/2)-1.1")
+
+# For a multi-column legend, users have to provide the width via "+w", here it
+# is set to 6 centimeters; reference and anchor points are set to BottomRight
+fig.legend(position="JBR+jBR+o0.2c+w6c", box=True)
+
 fig.show()

examples/gallery/histograms/histogram.py

@@ -12,12 +12,12 @@
 import numpy as np
 import pygmt
 
-np.random.seed(100)
-
 # Generate random elevation data from a normal distribution
+rng = np.random.default_rng(seed=100)
 mean = 100  # mean of distribution
 stddev = 25  # standard deviation of distribution
-data = mean + stddev * np.random.randn(521)
+data = rng.normal(loc=mean, scale=stddev, size=521)
+
 
 fig = pygmt.Figure()
 

examples/gallery/histograms/scatter_and_histograms.py

@@ -13,15 +13,16 @@
 import numpy as np
 import pygmt
 
-np.random.seed(19680801)
-
 # Generate random data from a standard normal distribution centered on 0
-x = np.random.randn(1000)
-y = np.random.randn(1000)
+# with a standard deviation of 1
+rng = np.random.default_rng(seed=19680801)
+x = rng.normal(loc=0, scale=1, size=1000)
+y = rng.normal(loc=0, scale=1, size=1000)
 
 # Get axis limits
 xymax = max(np.max(np.abs(x)), np.max(np.abs(y)))
 
+
 fig = pygmt.Figure()
 fig.basemap(
     region=[-xymax - 0.5, xymax + 0.5, -xymax - 0.5, xymax + 0.5],