Merge branch 'main' into refactor/image

Author: seisman

pygmt/src/grdfilter.py

@@ -15,16 +15,17 @@
 
 
 @fmt_docstring
-@use_alias(D="distance", F="filter", N="nans", f="coltypes")
+@use_alias(D="distance", F="filter", f="coltypes")
 def grdfilter(
     grid: PathLike | xr.DataArray,
     outgrid: PathLike | None = None,
-    toggle: bool = False,
     spacing: Sequence[float | str] | None = None,
+    nans: Literal["ignore", "replace", "preserve"] | None = None,
+    toggle: bool = False,
     region: Sequence[float | str] | str | None = None,
-    registration: Literal["gridline", "pixel"] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
+    registration: Literal["gridline", "pixel"] | bool = False,
     cores: int | bool = False,
     **kwargs,
 ) -> xr.DataArray | None:
@@ -45,6 +46,7 @@ def grdfilter(
 
     $aliases
        - I = spacing
+       - N = nans
        - R = region
        - T = toggle
        - V = verbose
@@ -89,21 +91,22 @@ def grdfilter(
           calculation.
         - ``"5"``: grid (x,y) in Mercator ``projection="m1"`` img units,
           *width* in km, Spherical distance calculation.
-
     $spacing
-    nans : str or float
-        **i**\|\ **p**\|\ **r**.
-        Determine how NaN-values in the input grid affect the filtered output.
-        Use **i** to ignore all NaNs in the calculation of the filtered value
-        [Default]. **r** is same as **i** except if the input node was NaN then
-        the output node will be set to NaN (only applies if both grids are
-        co-registered). **p** will force the filtered value to be NaN if any
-        grid nodes with NaN-values are found inside the filter circle.
-    $region
+    nans
+        Determine how NaN-values in the input grid affect the filtered output grid.
+        Choose one of:
+
+        - ``"ignore"``: Ignore all NaNs in the calculation of filtered value [Default].
+        - ``"replace"``: Similar to ``"ignore"`` except if the input node was NaN then
+          the output node will be set to NaN (only applied if both grids are
+          co-registered).
+        - ``"preserve"``: Force the filtered value to be NaN if any grid nodes with
+          NaN-values are found inside the filter circle.
     toggle
         Toggle the node registration for the output grid so as to become the opposite of
         the input grid [Default gives the same registration as the input grid].
         Alternatively, use ``registration`` to set the registration explicitly.
+    $region
     $verbose
     $coltypes
     $registration
@@ -122,8 +125,8 @@ def grdfilter(
     --------
     >>> from pathlib import Path
     >>> import pygmt
-    >>> # Apply a filter of 600 km (full width) to the @earth_relief_30m_g file
-    >>> # and return a filtered field (saved as netCDF)
+    >>> # Apply a median filter of 600 km (full width) to the @earth_relief_30m_g grid
+    >>> # and return a filtered grid (saved as netCDF file).
     >>> pygmt.grdfilter(
     ...     grid="@earth_relief_30m_g",
     ...     filter="m600",
@@ -133,13 +136,16 @@ def grdfilter(
     ...     outgrid="filtered_pacific.nc",
     ... )
     >>> Path("filtered_pacific.nc").unlink()  # Cleanup file
-    >>> # Apply a Gaussian smoothing filter of 600 km to the input DataArray
-    >>> # and return a filtered DataArray with the smoothed field
+    >>> # Apply a Gaussian smoothing filter of 600 km to the input DataArray and return
+    >>> # a filtered DataArray with the smoothed grid.
     >>> grid = pygmt.datasets.load_earth_relief()
     >>> smooth_field = pygmt.grdfilter(grid=grid, filter="g600", distance="4")
     """
     aliasdict = AliasSystem(
         I=Alias(spacing, name="spacing", sep="/", size=2),
+        N=Alias(
+            nans, name="nans", mapping={"ignore": "i", "replace": "r", "preserve": "p"}
+        ),
         T=Alias(toggle, name="toggle"),
     ).add_common(
         R=region,

pygmt/src/inset.py

@@ -74,8 +74,8 @@ def inset(
         If not specified, defaults to the Bottom Left corner of the plot.
     width
     height
-        Width and height of the inset. Width must be specified and height is set to be
-        equal to width if not specified.
+        Width and height of the inset. Width must be specified unless ``projection`` and
+        ``region`` are given, and height is set to be equal to width if not specified.
     box
         Draw a background box behind the inset. If set to ``True``, a simple rectangular
         box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box appearance,
@@ -132,8 +132,12 @@ def inset(
         default=Position((0, 0), cstype="plotcoords"),  # Default to (0,0) in plotcoords
     )
 
-    # width is mandatory.
-    if width is None and not isinstance(position, str):
+    # width is mandatory unless both projection and region are given.
+    if (
+        not isinstance(position, str)
+        and width is None
+        and (projection is None or region is None)
+    ):
         msg = "Parameter 'width' must be specified."
         raise GMTInvalidInput(msg)
 

pygmt/tests/test_inset.py

@@ -54,6 +54,18 @@ def test_inset_default_position():
     return fig
 
 
+@pytest.mark.mpl_image_compare(filename="test_inset_default_position.png")
+def test_inset_width_from_projection_region():
+    """
+    Test that the inset can infer width from projection and region.
+    """
+    fig = Figure()
+    fig.basemap(region="MG+r2", frame="afg")
+    with fig.inset(projection="G47/-20/3.5c", region="g", box=True):
+        fig.basemap(region="g", projection="G47/-20/?", frame="afg")
+    return fig
+
+
 @pytest.mark.mpl_image_compare(filename="test_inset_aliases.png")
 def test_inset_deprecated_position():
     """