Merge branch 'main' into python-3.13

Author: weiji14

.dvcignore

@@ -1,3 +1,2 @@
-# Add patterns of files dvc should ignore, which could improve
-# the performance. Learn more at
-# https://dvc.org/doc/user-guide/dvcignore
+# Add patterns of files dvc should ignore, which could improve the performance.
+# Learn more at https://dvc.org/doc/user-guide/project-structure/dvcignore-files

.github/ISSUE_TEMPLATE/4-release_checklist.md

@@ -19,7 +19,8 @@ assignees: ''
 
 **Before release**:
 
-- [ ] Check [SPEC 0](https://scientific-python.org/specs/spec-0000/) to see if we need to bump the minimum supported versions of GMT, Python and core package dependencies (NumPy/Pandas/Xarray)
+- [ ] Check [SPEC 0](https://scientific-python.org/specs/spec-0000/) to see if we need to bump the minimum supported versions of GMT, Python and
+      core package dependencies (NumPy, pandas, Xarray)
 - [ ] Review the ["PyGMT Team" page](https://www.pygmt.org/dev/team.html)
 - [ ] Check to ensure that:
   - [ ] Deprecations and related tests are removed for this version by running `grep --include="*.py" -r vX.Y.Z` from the base of the repository

.github/PULL_REQUEST_TEMPLATE.md

@@ -8,6 +8,10 @@
 Fixes #
 
 
+<!-- If significant changes to the documentation are made, please insert the link to the documentation page after it has been built. -->
+**Preview**:
+
+
 **Reminders**
 
 - [ ] Run `make format` and `make check` to make sure the code follows the style guide.

.github/release-drafter.yml

@@ -24,6 +24,8 @@ exclude-contributors:
   - 'actions-bot'
   - 'dependabot'
   - 'dependabot[bot]'
+  - 'pre-commit-ci'
+  - 'pre-commit-ci[bot]'
 category-template: '### $TITLE'
 change-template: '* $TITLE ([#$NUMBER]($URL))'
 sort-by: 'title'

.github/workflows/benchmarks.yml

@@ -88,7 +88,7 @@ jobs:
 
       # Run the benchmark tests
       - name: Run benchmarks
-        uses: CodSpeedHQ/[email protected].0
+        uses: CodSpeedHQ/[email protected].1
         with:
           # 'bash -el -c' is needed to use the custom shell.
           # See https://github.com/CodSpeedHQ/action/issues/65.

.github/workflows/check-links.yml

@@ -35,32 +35,29 @@ jobs:
 
     - name: Link Checker
       id: lychee
-      uses: lycheeverse/lychee-action@v1.10.0
+      uses: lycheeverse/lychee-action@v2.0.2
       with:
+        fail: false  # Don't fail action on broken links
         output: /tmp/lychee-out.md
         # 429: Too many requests
         args: >
           --accept 429
-          --exclude "^https://doi.org/10.5281/zenodo$"
-          --exclude "^https://zenodo.org/badge/DOI/$"
-          --exclude "^https://zenodo.org/badge/DOI/10.5281/zenodo$"
-          --exclude "^https://github.com/GenericMappingTools/pygmt/pull/[0-9]*$"
-          --exclude "^https://github.com/GenericMappingTools/pygmt/issues/[0-9]*$"
+          --exclude "^https://docs.generic-mapping-tools.org/6.[0-9]?/%s$"
+          --exclude "^https://docs.generic-mapping-tools.org/6.[0-9]?/%3Cmodule-name%3E.html$"
+          --exclude "^https://doi.org"
           --exclude "^https://github.com/GenericMappingTools/gmt/releases/tag/X.Y.Z$"
           --exclude "^https://github.com/GenericMappingTools/pygmt/edit"
           --exclude "^https://github.com/GenericMappingTools/pygmt/issues/new"
+          --exclude "^https://github.com/GenericMappingTools/pygmt/pull/[0-9]*$"
+          --exclude "^https://github.com/GenericMappingTools/pygmt/issues/[0-9]*$"
           --exclude "^https://github.com/GenericMappingTools/pygmt/releases/tag/%7B%7Bpath%7D%7D"
-          --exclude "^https://www.pygmt.org/%7B%7Bpath%7D%7D"
-          --exclude "^git"
-          --exclude "^file://"
-          --exclude "https://www.adobe.com/jp/print/postscript/pdfs/PLRM.pdf"
-          --exclude "^https://docs.generic-mapping-tools.org/6.5/%s$"
-          --exclude "^https://docs.generic-mapping-tools.org/6.5/%3Cmodule-name%3E.html$"
-          --exclude "^https://www.generic-mapping-tools.org/remote-datasets/%s$"
           --exclude "^https://hackmd.io/@pygmt"
-          --exclude "^https://doi.org"
-          --exclude "^https://www.researchgate.net/"
           --exclude "^https://test.pypi.org/simple/"
+          --exclude "^https://www.adobe.com/jp/print/postscript/pdfs/PLRM.pdf"
+          --exclude "^https://www.generic-mapping-tools.org/remote-datasets/%s$"
+          --exclude "^https://www.pygmt.org/%7B%7Bpath%7D%7D"
+          --exclude "^https://www.researchgate.net/"
+          --exclude "^https://zenodo.org/badge/DOI/"
           --verbose
           "repository/**/*.rst"
           "repository/**/*.md"

.github/workflows/ci_tests.yaml

@@ -17,8 +17,8 @@
 # In draft pull request, only two jobs on Linux are triggered to save on
 # Continuous Integration resources:
 #
-# - Minimum supported Python/NumPy/Pandas/Xarray versions following [SPEC 0](https://scientific-python.org/specs/spec-0000/)
-# - Latest Python/NumPy versions + optional packages (e.g. GeoPandas)
+# - Minimum supported Python, NumPy, pandas, Xarray versions following [SPEC 0](https://scientific-python.org/specs/spec-0000/)
+# - Latest Python, NumPy versions + optional packages (e.g. GeoPandas)
 #
 name: Tests
 
@@ -65,8 +65,8 @@ jobs:
             isDraft: true
           - os: windows-latest
             isDraft: true
-        # Pair Python 3.10 with the minimum supported versions of NumPy/Pandas/Xarray
-        # and Python 3.13 with the latest versions of NumPy/Pandas/Xarray
+        # Pair Python 3.10 with the minimum supported versions of NumPy, pandas, Xarray
+        # and Python 3.13 with the latest versions of NumPy, pandas, Xarray
         # Only install optional packages on Python 3.13
         include:
           - python-version: '3.10'
@@ -79,7 +79,7 @@ jobs:
             pandas-version: ''
             xarray-version: ''
             optional-packages: ' contextily geopandas ipython pyarrow rioxarray sphinx-gallery'
-          # The job below is for testing geopandas v0.x on Ubuntu.
+          # The job below is for testing GeoPandas v0.x on Ubuntu.
           # The python-version here can't be the versions in the matrix.python-version
           # defined above. Otherwise, other jobs will be overridden by this one.
           - os: 'ubuntu-latest'

.github/workflows/ci_tests_dev.yaml

@@ -1,7 +1,7 @@
 # Test PyGMT with GMT dev version on Linux/macOS/Windows
 #
 # 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,
+# versions of several dependencies like NumPy, pandas, Xarray, etc. If any tests fail,
 # it also uploads the diff images as workflow artifacts. The GMT dev version is
 # installed by fetching the latest source codes from the GMT master branch and
 # compiling.

.github/workflows/ci_tests_legacy.yaml

@@ -1,8 +1,8 @@
 # Test PyGMT with GMT legacy versions on Linux/macOS/Windows
 #
-# This workflow runs regular PyGMT tests with GMT legacy versions. Due to the
-# minor baseline image changes between GMT versions, the workflow only runs
-# the tests but doesn't do image comparisons.
+# This workflow runs regular PyGMT tests with GMT legacy versions. Due to the minor
+# baseline image changes between GMT versions, the workflow only runs the tests but
+# doesn't do image comparisons.
 #
 # It is scheduled to run every Tuesday on the main branch.
 #
@@ -34,7 +34,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-20.04, macos-12, windows-2019]
+        os: [ubuntu-20.04, macos-13, windows-2019]
         gmt_version: ['6.4']
     timeout-minutes: 30
     defaults:
@@ -63,7 +63,7 @@ jobs:
             gmt=${{ matrix.gmt_version }}
             ghostscript<10
             numpy
-            pandas<2
+            pandas
             xarray
             netCDF4
             packaging
@@ -85,9 +85,9 @@ jobs:
         run: |
           # Download cached files to ~/.gmt directory and list them
           gh run download --name gmt-cache --dir ~/.gmt/
-          # Change modification times of the two files, so GMT won't refresh it
-          # The two files are in the `~/.gmt/server` directory for GMT<=6.4, and
-          # in the `~/.gmt` directory for GMT>=6.5.
+          # Change modification times of the two files, so GMT won't refresh it.
+          # The two files are in the `~/.gmt/server` directory for GMT<=6.4, and in the
+          # `~/.gmt` directory for GMT>=6.5.
           mkdir -p ~/.gmt/server/
           mv ~/.gmt/gmt_data_server.txt ~/.gmt/gmt_hash_server.txt ~/.gmt/server/
           touch ~/.gmt/server/gmt_data_server.txt ~/.gmt/server/gmt_hash_server.txt

README.md

@@ -194,7 +194,7 @@ PyGMT has adopted [SPEC 0](https://scientific-python.org/specs/spec-0000/) along
 rest of the Scientific Python ecosystem, and therefore:
 
 - Support for Python versions be dropped 3 years after their initial release.
-- Support for core package dependencies (NumPy/Pandas/Xarray) be dropped 2 years after
+- Support for core package dependencies (NumPy, pandas, Xarray) be dropped 2 years after
   their initial release.
 
 Similarly, the PyGMT team has decided to discontinue support for GMT versions 3 years

doc/ecosystem.md

@@ -0,0 +1,127 @@
+# Ecosystem
+
+PyGMT provides a Python interface to the Generic Mapping Tools (GMT), which is a command
+line program that provides a wide range of tools for manipulating geospatial data and
+making publication-quality maps and figures. PyGMT integrates well with the
+[scientific Python ecosystem](https://scientific-python.org/), with [NumPy][] for its
+fundamental array data structure, [pandas][] for tabular data I/O and [Xarray][] for
+raster grids/images/cubes I/O.
+
+In addition to these core dependencies, PyGMT also relies on several optional packages to
+provide additional functionality for users.
+
+*This page was adapted from [GeoPandas's Ecosystem](https://geopandas.org/en/latest/community/ecosystem.html) page.*
+
+## PyGMT dependencies
+
+_Asterisk (*) after the package name indicates the package is a required dependency of PyGMT._
+
+### NumPy*
+
+[NumPy][] is the fundamental package for scientific computing in Python. It is a Python
+library that provides a multidimensional array object, various derived objects (such as
+masked arrays and matrices), and an assortment of routines for fast operations on arrays,
+including mathematical, logical, shape manipulation, sorting, selecting, I/O, discrete
+Fourier transforms, basic linear algebra, basic statistical operations, random simulation
+and much more.
+
+### pandas*
+
+[pandas][] is a Python package providing fast, flexible, and expressive data structures
+designed to make working with "relational" or "labeled" data both easy and intuitive.
+It aims to be the fundamental high-level building block for doing practical, real-world
+data analysis in Python.
+
+### Xarray*
+
+[Xarray][] is an open source project and Python package that introduces labels in the
+form of dimensions, coordinates, and attributes on top of raw NumPy-like arrays, which
+allows for more intuitive, more concise, and less error-prone user experience.
+
+### IPython
+
+[IPython][] provides a rich toolkit to help you make the most of using Python
+interactively. Its main components are a powerful interactive Python shell and a Jupyter
+kernel to work with Python code in Jupyter notebooks and other interactive frontends.
+
+PyGMT relies on IPython to provide a rich interactive experience in Jupyter notebooks.
+
+### GeoPandas
+
+[GeoPandas][] is an open source project to make working with geospatial data in Python
+easier. GeoPandas extends the datatypes used by [pandas][] to allow spatial operations
+on geometric types. Geometric operations are performed by [Shapely][]. GeoPandas further
+depends on [pyogrio][] for file access and [Matplotlib][] for plotting.
+
+PyGMT doesn't directly rely on GeoPandas, but provides support of GeoPandas's two main
+data structure, {class}`geopandas.GeoDataFrame` and {class}`geopandas.GeoSeries`, which
+can be directly used in data processing and plotting functions/methods of PyGMT.
+
+### contextily
+
+[contextily][] is a small Python package to retrieve tile maps from the internet. It can
+add those tiles as basemap to matplotlib figures or write tile maps to disk into
+geospatial raster files.
+
+In PyGMT, {func}`pygmt.datasets.load_tile_map` and {class}`pygmt.Figure.tilemap` rely
+on it.
+
+### rioxarray
+
+[rioxarray][] is a geospatial [Xarray][] extension powered by [rasterio][]. Built on top
+of rasterio, it enables seamless reading, writing, and manipulation of multi-dimensional
+arrays with geospatial attributes such as coordinate reference systems (CRS) and spatial
+extent (bounds).
+
+Currently, PyGMT relies on [rioxarray][] to save multi-band rasters to temporary files
+in GeoTIFF format, to support processing and plotting 3-D {class}`xarray.DataArray`
+images.
+
+```{note}
+We're working towards removing the dependency of the [rioxarray][] package in
+[PR #3468](https://github.com/GenericMappingTools/pygmt/pull/3468).
+```
+
+### PyArrow
+
+[Apache Arrow][] is a development platform for in-memory analytics. It contains a set of
+technologies that enable big data systems to process and move data fast. It specifies a
+standardized language-independent columnar memory format for flat and hierarchical data,
+organized for efficient analytic operations on modern hardware. The Arrow Python bindings
+(also named "[PyArrow][]") have first-class integration with NumPy, pandas, and built-in
+Python objects. They are based on the C++ implementation of Arrow.
+
+```{note}
+If you have [PyArrow][] installed, PyGMT does have some initial support for
+`pandas.Series` and `pandas.DataFrame` objects with Apache Arrow-backed arrays.
+Specifically, only uint/int/float and date32/date64 are supported for now.
+Support for string Array dtypes, Duration types and GeoArrow geometry types is still a work in progress.
+For more details, see
+[issue #2800](https://github.com/GenericMappingTools/pygmt/issues/2800).
+```
+
+## PyGMT ecosystem
+
+Various packages rely on PyGMT for geospatial data processing, analysis, and visualization.
+Below is an incomplete list (in no particular order) of tools which form the PyGMT-related
+ecosystem.
+
+```{note}
+If your package relies on PyGMT, please
+[let us know](https://github.com/GenericMappingTools/pygmt/issues/new) or
+[add it by yourself](contributing.md).
+```
+
+[apache arrow]: https://arrow.apache.org/
+[contextily]: https://contextily.readthedocs.io/
+[geopandas]: https://geopandas.org/
+[ipython]: https://ipython.org/
+[matplotlib]: https://matplotlib.org/
+[numpy]: https://numpy.org/
+[pandas]: https://pandas.pydata.org/
+[pyarrow]: https://arrow.apache.org/docs/python/
+[pyogrio]: https://pyogrio.readthedocs.io/
+[rasterio]: https://rasterio.readthedocs.io/
+[rioxarray]: https://corteva.github.io/rioxarray/
+[shapely]: https://shapely.readthedocs.io/
+[xarray]: https://xarray.pydata.org/

doc/external_resources.md

@@ -107,7 +107,7 @@ Andre Belem
 :text-align: center
 :margin: 0 3 0 0
 
-![](https://github.com/tktmyd/pygmt-howto-jp/raw/main/docs/_images/01aed847a81445c7a002cce113d95886793f6236fbcccb233862486589f17ed1.png)
+![](https://github.com/tktmyd/pygmt-howto-jp/raw/main/docs/_images/inf_on_map_12_0.png)
 +++
 Takuto Maeda
 ::::

doc/index.md

@@ -45,6 +45,7 @@ api/index.rst
 techref/index.md
 changes.md
 minversions.md
+ecosystem.md
 ```
 
 ```{toctree}

doc/install.md

@@ -94,7 +94,7 @@ PyGMT requires the following libraries to be installed:
 - [packaging](https://packaging.pypa.io)
 
 :::{note}
-For the minimum supported versions of the dependencies, please see {doc}`minversions`.
+For the minimum supported versions of the dependencies, please see [](minversions.md).
 :::
 
 The following are optional dependencies:

doc/maintenance.md

@@ -3,7 +3,7 @@
 This page contains instructions for project maintainers about how our setup works,
 making releases, creating packages, etc.
 
-If you want to make a contribution to the project, see the {doc}`contributing` instead.
+If you want to make a contribution to the project, see the [](contributing.md) instead.
 
 ## Onboarding/Offboarding Access Checklist
 
@@ -22,7 +22,7 @@ communication tools we use.
 ### As a Maintainer
 
 - Add to the [pygmt-maintainers team](https://github.com/orgs/GenericMappingTools/teams/pygmt-maintainers) (gives 'maintain' permission to the repository)
-- Add to "Active Maintainers" on the {doc}`Team Gallery page <team>`
+- Add to "Active Maintainers" on the [Team Gallery page](team.md)
 - Add as a moderator on the [GMT forum](https://forum.generic-mapping-tools.org) (to see mod-only discussions) [optional]
 - Add as a maintainer on [ReadtheDocs](https://readthedocs.org/projects/pygmt-dev) [optional]
 - Add as a curator to the [GMT community](https://zenodo.org/communities/generic-mapping-tools/) on Zenodo (for making releases) [optional]
@@ -38,7 +38,7 @@ the onboarding access checklist:
 
 - Move from the [pygmt-maintainers team](https://github.com/orgs/GenericMappingTools/teams/pygmt-maintainers)
   to the [pygmt-contributors team](https://github.com/orgs/GenericMappingTools/teams/pygmt-contributors)
-- Move from "Active Maintainers" to "Distinguished Contributors" on the {doc}`Team Gallery page <team>`
+- Move from "Active Maintainers" to "Distinguished Contributors" on the [Team Gallery page](team.md)
 - Remove 'maintain' permission from GMT forum, ReadTheDocs, Zenodo
 
 ## Branches
@@ -127,7 +127,7 @@ PyGMT has adopted [SPEC 0](https://scientific-python.org/specs/spec-0000/) along
 rest of the Scientific Python ecosystem, and therefore:
 
 * Support for Python versions be dropped 3 years after their initial release.
-* Support for core package dependencies (NumPy/Pandas/Xarray) be dropped 2 years after
+* Support for core package dependencies (NumPy, pandas, Xarray) be dropped 2 years after
   their initial release.
 
 Similarly, the PyGMT team has decided to discontinue support for GMT versions 3 years
@@ -201,7 +201,7 @@ at `.github/release-drafter.yml`. Configuration settings can be found at
 <https://github.com/release-drafter/release-drafter>.
 
 The drafted release notes are not perfect, so we will need to tidy it prior to
-publishing the actual release notes at {doc}`changes`.
+publishing the actual release notes at [](changes.md).
 
 1. Go to <https://github.com/GenericMappingTools/pygmt/releases> and click on the
    'Edit' button next to the current draft release note. Copy the text of the
@@ -229,7 +229,7 @@ publishing the actual release notes at {doc}`changes`.
    last release (e.g., use `git shortlog HEAD...v0.4.0 -sne`).
 8. Update `doc/minversions.md` with new information on the new release version,
    including a vX.Y.Z documentation link, and minimum required versions of GMT, Python
-   and core package dependencies (NumPy/Pandas/Xarray). Follow
+   and core package dependencies (NumPy, pandas, Xarray). Follow
    [SPEC 0](https://scientific-python.org/specs/spec-0000/) for updates.
 9. Refresh citation information. Specifically, the BibTeX in `README.md` and
    `CITATION.cff` needs to be updated with any metadata changes, including the