Merge branch 'master' into inject-aliases

.github/workflows/cache_data.yaml

@@ -17,34 +17,36 @@ jobs:
  shell: bash -l {0}
 
  steps:
+ # Checkout current git repository
+ - name: Checkout
+ uses: actions/[email protected]
+ with:
+ # fecth all history so that setuptools-scm works
+ fetch-depth: 0
+
  # Setup Miniconda
  - name: Setup Miniconda
  uses: conda-incubator/[email protected]
  with:
  channels: conda-forge
  miniconda-version: "latest"
 
- # Install GMT
- - name: Install GMT
- run: conda install -c conda-forge gmt=6.1.1
+ # Install GMT and other required dependencies from conda-forge
+ - name: Install dependencies
+ run: |
+ conda install conda-forge/label/dev::gmt=6.2.0rc2 \
+ numpy pandas xarray netCDF4 packaging matplotlib
+
+ # Install the package that we want to test
+ - name: Install the package
+ run: |
+ python setup.py sdist --formats=zip
+ pip install dist/*
 
  # Download remote files
  - name: Download remote data
  run: |
- gmt which -Ga @earth_relief_10m_p @earth_relief_10m_g \
- @earth_relief_30m_p @earth_relief_30m_g \
- @earth_relief_01d_p @earth_relief_01d_g \
- @earth_relief_05m_p @earth_relief_05m_g
- # Download one tile of the 03s srtm data.
- # @N35E135.earth_relief_03s_g.nc is for internal use only.
- # The naming scheme may change.
- # DO NOT USE IT IN SCRIPTS.
- gmt which -Ga @N35E135.earth_relief_03s_g.nc
- # @srtm_tiles.nc is needed for 03s and 01s relief data
- gmt which -Ga @srtm_tiles.nc
- gmt which -Ga @ridge.txt @Table_5_11.txt @test.dat.nc \
- @tut_bathy.nc @tut_quakes.ngdc @tut_ship.xyz \
- @usgs_quakes_22.txt @fractures_06.txt
+ python -c "from pygmt.helpers.testing import download_test_data; download_test_data()"
 
  # Upload the downloaded files as artifacts to GitHub
  - name: Upload artifacts to GitHub

.github/workflows/ci_docs.yml

@@ -66,7 +66,7 @@ jobs:
  # Install GMT and other required dependencies from conda-forge
  - name: Install dependencies
  run: |
- conda install conda-forge/label/dev::gmt=6.2.0rc1 \
+ conda install conda-forge/label/dev::gmt=6.2.0rc2 \
  numpy pandas xarray netCDF4 packaging \
  ipython make myst-parser \
  sphinx sphinx-copybutton sphinx-gallery sphinx_rtd_theme

.github/workflows/ci_tests.yaml

@@ -52,7 +52,7 @@ jobs:
  optional-packages: ''
  - python-version: 3.9
  numpy-version: '1.20'
- optional-packages: 'geopandas'
+ optional-packages: '' # 'geopandas'
  defaults:
  run:
  shell: bash -l {0}
@@ -89,7 +89,7 @@ jobs:
  # Install GMT and other required dependencies from conda-forge
  - name: Install dependencies
  run: |
- conda install conda-forge/label/dev::gmt=6.2.0rc1 \
+ conda install conda-forge/label/dev::gmt=6.2.0rc2 \
  numpy=${{ matrix.numpy-version }} \
  pandas xarray netCDF4 packaging \
  ${{ matrix.optional-packages }} \

.github/workflows/ci_tests_dev.yaml

@@ -83,7 +83,7 @@ jobs:
  # Install dependencies from conda-forge
  - name: Install dependencies
  run: |
- conda install ninja cmake libblas libcblas liblapack fftw gdal \
+ conda install ninja cmake libblas libcblas liblapack fftw gdal=3.2 geopandas \
  ghostscript libnetcdf hdf5 zlib curl pcre make dvc
  pip install --pre numpy pandas xarray netCDF4 packaging \
  ipython pytest-cov pytest-mpl pytest>=6.0 sphinx-gallery

doc/api/index.rst

@@ -92,6 +92,8 @@ Operations on grids:
  grdcut
  grdfill
  grdfilter
+ grdlandmask
+ grdgradient
  grdtrack
 
 Crossover analysis with x2sys:

doc/maintenance.md

@@ -24,6 +24,21 @@ instead.
  branch are in the `dev` folder. Pages for each release are in their own folders.
  **Automatically updated by GitHub Actions** so you shouldn't have to make commits here.
 
+## Managing GitHub issues
+
+A few guidelines for managing GitHub issues:
+
+* Assign [labels](https://github.com/GenericMappingTools/pygmt/labels) and the expected
+ [milestone](https://github.com/GenericMappingTools/pygmt/milestones) to issues as
+ appropriate.
+* When people request to work on an open issue, either assign the issue to that person
+ and post a comment about the assignment or explain why you are not assigning the 
+ issue to them and, if possible, recommend other issues for them to work on.
+* People with write access should self-assign issues and/or comment on the issues that
+ they will address.
+* For upstream bugs, close the issue after an upstream release fixes the bug. If
+ possible, post a comment when an upstream PR is merged that fixes the problem, and
+ consider adding a regression test for serious bugs.
 
 ## Reviewing and merging pull requests
 
@@ -173,21 +188,21 @@ When making incompatible changes, we should follow the process:
  3-12 months.
 - Remove the old usage and warning when reaching the declared version.
 
-To rename a function parameter, add the `@deprecated_parameter` decorator
-before the function definition (but after the `@use_alias` decorator if it exists).
-Here is an example:
+To rename a function parameter, add the `@deprecate_parameter` decorator near
+the top after the `@fmt_docstring` decorator but before the `@use_alias`
+decorator (if those two exists). Here is an example:
 
 ```
 @fmt_docstring
-@use_alias(J="projection", R="region", V="verbose")
-@kwargs_to_strings(R="sequence")
-@deprecate_parameter("sizes", "size", "v0.4.0", remove_version="v0.6.0")
+@deprecate_parameter("columns", "incols", "v0.4.0", remove_version="v0.6.0")
+@use_alias(J="projection", R="region", V="verbose", i="incols")
+@kwargs_to_strings(R="sequence", i='sequence_comma')
 def plot(self, x=None, y=None, data=None, size=None, direction=None, **kwargs):
  pass
 ```
 
-In this case, the old parameter name `sizes` is deprecated since v0.4.0, and will be
-fully removed in v0.6.0. The new parameter name is `size`.
+In this case, the old parameter name `columns` is deprecated since v0.4.0, and
+will be fully removed in v0.6.0. The new parameter name is `incols`.
 
 
 ## Making a Release

environment.yml

@@ -6,7 +6,7 @@ channels:
 dependencies:
  # Required dependencies
  - pip
- - gmt=6.2.0rc1
+ - gmt=6.2.0rc2
  - numpy>=1.17
  - pandas
  - xarray

examples/gallery/embellishments/inset.py

@@ -14,12 +14,17 @@
 # "brown", the water to "lightblue", the shorelines width to "thin", and adding a frame
 fig.coast(region="MG+r2", land="brown", water="lightblue", shorelines="thin", frame="a")
 # Create an inset, setting the position to top left, the width to 3.5 centimeters, and
-# the x- and y-offsets to 0.2 centimeters. The margin is set to 0, and the border is "gold".
-with fig.inset(position="jTL+w3.5c+o0.2c", margin=0, box="+pgold"):
+# the x- and y-offsets to 0.2 centimeters. The margin is set to 0, and the border is "gold"
+# with a pen size of 1.5p.
+with fig.inset(position="jTL+w3.5c+o0.2c", margin=0, box="+p1.5p,gold"):
  # Create a figure in the inset using coast. This example uses the azimuthal
  # orthogonal projection centered at 47E, 20S. The land color is set to "gray" and
- # Madagascar is highlighted in "red".
+ # Madagascar is highlighted in "red3".
  fig.coast(
- region="g", projection="G47/-20/3.5c", land="gray", water="white", dcw="MG+gred"
+ region="g",
+ projection="G47/-20/?",
+ land="gray",
+ water="white",
+ dcw="MG+gred3",
  )
 fig.show()

pygmt/__init__.py

@@ -37,7 +37,9 @@
  grdcut,
  grdfill,
  grdfilter,
+ grdgradient,
  grdinfo,
+ grdlandmask,
  grdtrack,
  info,
  makecpt,

pygmt/figure.py

@@ -237,12 +237,17 @@ def savefig(
  prefix, ext = os.path.splitext(fname)
  ext = ext[1:] # Remove the .
  if ext not in fmts:
- raise GMTInvalidInput("Unknown extension '.{}'".format(ext))
+ if ext == "ps":
+ raise GMTInvalidInput(
+ "Extension '.ps' is not supported. "
+ "Please use '.eps' or '.pdf' instead."
+ )
+ raise GMTInvalidInput(f"Unknown extension '.{ext}'.")
  fmt = fmts[ext]
  if transparent:
  if fmt != "g":
  raise GMTInvalidInput(
- "Transparency unavailable for '{}', only for png.".format(ext)
+ f"Transparency unavailable for '{ext}', only for png."
  )
  fmt = fmt.upper()
  if anti_alias:

pygmt/helpers/decorators.py

@@ -41,6 +41,37 @@
  color : str or 1d array
  Select color or pattern for filling of symbols or polygons. Default
  is no fill.""",
+ "I": r"""
+ spacing : str
+ *xinc*\ [**+e**\|\ **n**][/\ *yinc*\ [**+e**\|\ **n**]].
+ *x_inc* [and optionally *y_inc*] is the grid spacing.
+
+ - **Geographical (degrees) coordinates**: Optionally, append an
+ increment unit. Choose among **m** to indicate arc minutes or
+ **s** to indicate arc seconds. If one of the units **e**, **f**,
+ **k**, **M**, **n** or **u** is appended instead, the increment
+ is assumed to be given in meter, foot, km, mile, nautical mile or
+ US survey foot, respectively, and will be converted to the
+ equivalent degrees longitude at the middle latitude of the region
+ (the conversion depends on :gmt-term:`PROJ_ELLIPSOID`). If
+ *y_inc* is given but set to 0 it will be reset equal to *x_inc*;
+ otherwise it will be converted to degrees latitude.
+
+ - **All coordinates**: If **+e** is appended then the corresponding
+ max *x* (*east*) or *y* (*north*) may be slightly adjusted to fit
+ exactly the given increment [by default the increment may be
+ adjusted slightly to fit the given domain]. Finally, instead of
+ giving an increment you may specify the *number of nodes* desired
+ by appending **+n** to the supplied integer argument; the
+ increment is then recalculated from the number of nodes, the
+ *registration*, and the domain. The resulting increment value
+ depends on whether you have selected a gridline-registered or
+ pixel-registered grid; see :gmt-docs:`GMT File Formats
+ <cookbook/file-formats.html#gmt-file-formats>` for details.
+
+ **Note**: If ``region=grdfile`` is used then the grid spacing and
+ the registration have already been initialized; use ``spacing`` and
+ ``registration`` to override these values.""",
  "V": """\
  verbose : bool or str
  Select verbosity level [Default is **w**], which modulates the messages
@@ -88,6 +119,36 @@
  geographical data). Full documentation is at
  :gmt-docs:`gmt.html#f-full`.
  """,
+ "i": r"""
+ incols : str or 1d array
+ Specify data columns for primary input in arbitrary order. Columns
+ can be repeated and columns not listed will be skipped [Default
+ reads all columns in order, starting with the first (i.e., column
+ 0)].
+
+ - For *1d array*: specify individual columns in input order (e.g.,
+ ``incols=[1,0]`` for the 2nd column followed by the 1st column).
+ - For :py:class:`str`: specify individual columns or column
+ ranges in the format *start*\ [:*inc*]:*stop*, where *inc*
+ defaults to 1 if not specified, with columns and/or column ranges
+ separated by commas (e.g., ``incols='0:2,4+l'`` to input the
+ first three columns followed by the log-transformed 5th column).
+ To read from a given column until the end of the record, leave
+ off *stop* when specifying the column range. To read trailing
+ text, add the column **t**. Append the word number to **t** to
+ ingest only a single word from the trailing text. Instead of
+ specifying columns, use ``incols='n'`` to simply read numerical
+ input and skip trailing text. Optionally, append one of the
+ following modifiers to any column or column range to transform
+ the input columns:
+
+ - **+l** to take the *log10* of the input values.
+ - **+d** to divide the input values by the factor *divisor*
+ [default is 1].
+ - **+s** to multiple the input values by the factor *scale*
+ [default is 1].
+ - **+o** to add the given *offset* to the input values [default
+ is 0].""",
  "j": r"""
  distcalc : str
  **e**\|\ **f**\|\ **g**.
@@ -501,7 +562,7 @@ def deprecate_parameter(oldname, newname, deprecate_version, remove_version):
  name, and users will receive a FutureWarning to inform them of the pending
  deprecation.
 
- Use this decorator below the ``use_alias`` decorator.
+ Use this decorator above the ``use_alias`` decorator.
 
  Parameters
  ----------

pygmt/helpers/testing.py

@@ -7,6 +7,7 @@
 
 from matplotlib.testing.compare import compare_images
 from pygmt.exceptions import GMTImageComparisonFailure
+from pygmt.src import which
 
 
 def check_figures_equal(*, extensions=("png",), tol=0.0, result_dir="result_images"):
@@ -139,3 +140,36 @@ def wrapper(*args, ext="png", request=None, **kwargs):
  return wrapper
 
  return decorator
+
+
+def download_test_data():
+ """
+ Convenience function to download remote data files used in PyGMT tests and
+ docs.
+ """
+ # List of datasets to download
+ datasets = [
+ # Earth relief grids
+ "@earth_relief_01d_p",
+ "@earth_relief_01d_g",
+ "@earth_relief_30m_p",
+ "@earth_relief_30m_g",
+ "@earth_relief_10m_p",
+ "@earth_relief_05m_p",
+ "@earth_relief_05m_g",
+ # List of tiles of 03s srtm data.
+ # Names like @N35E135.earth_relief_03s_g.nc is for internal use only.
+ # The naming scheme may change. DO NOT USE IT IN YOUR SCRIPTS.
+ "@N35E135.earth_relief_03s_g.nc",
+ # Other cache files
+ "@fractures_06.txt",
+ "@ridge.txt",
+ "@srtm_tiles.nc", # needed for 03s and 01s relief data
+ "@Table_5_11.txt",
+ "@test.dat.nc",
+ "@tut_bathy.nc",
+ "@tut_quakes.ngdc",
+ "@tut_ship.xyz",
+ "@usgs_quakes_22.txt",
+ ]
+ which(fname=datasets, download="a")

pygmt/src/__init__.py

@@ -15,8 +15,10 @@
 from pygmt.src.grdcut import grdcut
 from pygmt.src.grdfill import grdfill
 from pygmt.src.grdfilter import grdfilter
+from pygmt.src.grdgradient import grdgradient
 from pygmt.src.grdimage import grdimage
 from pygmt.src.grdinfo import grdinfo
+from pygmt.src.grdlandmask import grdlandmask
 from pygmt.src.grdtrack import grdtrack
 from pygmt.src.grdview import grdview
 from pygmt.src.histogram import histogram