supply units to `region` parameter

[mdtanker]

Description of the problem

With the new version v0.17.0, I get an unexpected error raised when I supply units with +ue to the region parameter. It now expects either 4 or 6 inputs, and won't accept 5, as past versions of pygmt have allowed. My temporary fix is to supply a 6th input, as an empty string.

This may be related to these changes: 7567f75#diff-22b2e785b3466f79f86da4ee658ee8b32b4a6b58fe8cfb2505612f07a81ac85cR306

Minimal Complete Verifiable Example

import pygmt

fig = pygmt.Figure()
fig.coast(
    region=(-3500e3, 3500e3, -3500e3, 3500e3, "+ue"),
    # region=(-3500e3, 3500e3, -3500e3, 3500e3, "+ue", ""),
    projection='s0/-90/-71/1:77777777.77777778',
    shorelines="0.5p,black",
    land="skyblue",
)
fig.show()

Full error message

---------------------------------------------------------------------------
GMTInvalidInput                           Traceback (most recent call last)
Cell In[5], line 4
      1 import pygmt
      3 fig = pygmt.Figure()
----> 4 fig.coast(
      5     region=(-3500e3, 3500e3, -3500e3, 3500e3, "+ue"),
      6     # region=(-3500e3, 3500e3, -3500e3, 3500e3, "+ue", ""),
      7     projection='s0/-90/-71/1:77777777.77777778',
      8     shorelines="0.5p,black",
      9     land="skyblue",
     10 )
     11 fig.show()

File ~/miniforge3/envs/polartoolkit/lib/python3.12/site-packages/pygmt/helpers/decorators.py:576, in use_alias.<locals>.alias_decorator.<locals>.new_module(*args, **kwargs)
    570     msg = (
    571         "Parameters 'Y' and 'yshift' are no longer supported since v0.12.0. "
    572         "Use Figure.shift_origin(yshift=...) instead."
    573     )
    574     raise GMTInvalidInput(msg)
--> 576 return module_func(*args, **kwargs)

File ~/miniforge3/envs/polartoolkit/lib/python3.12/site-packages/pygmt/helpers/decorators.py:742, in kwargs_to_strings.<locals>.converter.<locals>.new_module(*args, **kwargs)
    739             bound.arguments["kwargs"][arg] = newvalue
    741 # Execute the original function and return its output
--> 742 return module_func(*bound.args, **bound.kwargs)

File ~/miniforge3/envs/polartoolkit/lib/python3.12/site-packages/pygmt/src/coast.py:225, in coast(self, projection, resolution, box, region, verbose, panel, transparency, **kwargs)
    205     msg = (
    206         "At least one of the following parameters must be specified: "
    207         "lakes, land, water, rivers, borders, dcw, Q, or shorelines."
    208     )
    209     raise GMTInvalidInput(msg)
    211 aliasdict = AliasSystem(
    212     D=Alias(
    213         resolution,
    214         name="resolution",
    215         mapping={
    216             "auto": "a",
    217             "full": "f",
    218             "high": "h",
    219             "intermediate": "i",
    220             "low": "l",
    221             "crude": "c",
    222         },
    223     ),
    224     F=Alias(box, name="box"),
--> 225 ).add_common(
    226     J=projection,
    227     R=region,
    228     V=verbose,
    229     c=panel,
    230     t=transparency,
    231 )
    232 aliasdict.merge(kwargs)
    234 with Session() as lib:

File ~/miniforge3/envs/polartoolkit/lib/python3.12/site-packages/pygmt/alias.py:306, in AliasSystem.add_common(self, **kwargs)
    304     alias = Alias(value, name="projection")
    305 case "R":
--> 306     alias = Alias(value, name="region", sep="/", size=(4, 6))
    307 case "V":
    308     alias = Alias(
    309         value,
    310         name="verbose",
   (...)    319         },
    320     )

File ~/miniforge3/envs/polartoolkit/lib/python3.12/site-packages/pygmt/alias.py:206, in Alias.__init__(self, value, name, prefix, mapping, sep, size, ndim)
    204 self.name = name
    205 self.prefix = prefix
--> 206 self._value = _to_string(
    207     value=value,
    208     name=name,
    209     prefix=prefix,
    210     mapping=mapping,
    211     sep=sep,
    212     size=size,
    213     ndim=ndim,
    214 )

File ~/miniforge3/envs/polartoolkit/lib/python3.12/site-packages/pygmt/alias.py:152, in _to_string(value, prefix, mapping, sep, size, ndim, name)
    149     return [str(item) if item is not True else "" for item in value]
    150 # Join the sequence of values with the separator.
    151 # "prefix" and "mapping" are ignored. We can enable them when needed.
--> 152 _value = sequence_join(value, sep=sep, size=size, ndim=ndim, name=name)
    153 return _value if is_nonstr_iter(_value) else f"{prefix}{_value}"

File ~/miniforge3/envs/polartoolkit/lib/python3.12/site-packages/pygmt/helpers/utils.py:875, in sequence_join(value, sep, separator, size, ndim, name)
    870 if size is not None and len(value) not in size:
    871     msg = (
    872         f"{errmsg['name']}Expected a sequence of {errmsg['sizes']} values, "
    873         f"but got {len(value)} values."
    874     )
--> 875     raise GMTInvalidInput(msg)
    876 # 'str(v)' produces a string like '2024-01-01 00:00:00' for some datetime-like
    877 # objects (e.g., datetime.datetime, pandas.Timestamp), which contains a space.
    878 # If so, use np.datetime_as_string to convert it to ISO 8601 string format
    879 # YYYY-MM-DDThh:mm:ss.ffffff.
    880 _values = [
    881     np.datetime_as_string(np.asarray(item, dtype="datetime64"))
    882     if " " in (s := str(item))
    883     else s
    884     for item in value
    885 ]

GMTInvalidInput: Parameter 'region': Expected a sequence of 4, 6 values, but got 5 values.

System information

mport pygmt; pygmt.show_versions()"
PyGMT information:
  version: v0.17.0
System information:
  python: 3.12.11 | packaged by conda-forge | (main, Jun  4 2025, 14:45:31) [GCC 13.3.0]
  executable: /home/sungw937/miniforge3/envs/polartoolkit/bin/python
  machine: Linux-5.15.167.4-microsoft-standard-WSL2-x86_64-with-glibc2.39
Dependency information:
  numpy: 2.3.3
  pandas: 2.3.3
  xarray: 2025.9.1
  packaging: 25.0
  contextily: None
  geopandas: 1.1.1
  IPython: 9.6.0
  pyarrow: 21.0.0
  rioxarray: 0.19.0
  gdal: 3.10.3
  ghostscript: 10.06.0
GMT library information:
  version: 6.6.0
  padding: 2
  share dir: /home/sungw937/miniforge3/envs/polartoolkit/share/gmt
  plugin dir: /home/sungw937/miniforge3/envs/polartoolkit/lib/gmt/plugins
  library path: /home/sungw937/miniforge3/envs/polartoolkit/lib/libgmt.so
  cores: 8
  grid layout: rows
  image layout: 
  binary version: 6.6.0

[seisman]

In previous versions, an argument like region=(-3500e3, 3500e3, -3500e3, 3500e3, "+ue") is converted to -R-3500e3/3500e3/-3500e3/3500e3/+ue (note the extra / before +ue), which is incorrect and should fail, although GMT can recognize it correctly.

Currently, there is no Pythonic way to supply +ue to the region argument. I would suggest using
region="-3500e3/3500e3/-3500e3/3500e3/+ue" directly as a workaround.

[mdtanker]

Ok great I will use that workaround instead. Thanks! Happy for you to close this if you'd like.

[weiji14]

Currently, there is no Pythonic way to supply +ue to the region argument. I would suggest using
region="-3500e3/3500e3/-3500e3/3500e3/+ue" directly as a workaround.

From reading https://docs.generic-mapping-tools.org/6.6/reference/options.html#data-domain-or-map-region-the-r-option, recommendation should probably be to use region="-3500e3/3500e3/-3500e3/3500e3+ue" (without the fourth slash). But doesn't matter too much I guess if GMT handles either.

[seisman]

Yes, I meant region="-3500e3/3500e3/-3500e3/3500e3+ue". Thanks for catching my typo.