Add 'to_size' keyword parameter

Author: davidhassell

cf/data/data.py

@@ -2181,7 +2181,7 @@ def mean_of_upper_decile(
         return d
 
     @_inplace_enabled(default=False)
-    def pad_missing(self, axis, pad_width, inplace=False):
+    def pad_missing(self, axis, pad_width=None, to_size=None, inplace=False):
         """Pad an axis with missing data.
 
         :Parameters:
@@ -2196,7 +2196,9 @@ def pad_missing(self, axis, pad_width, inplace=False):
                 *Parameter example:*
                   Pad the last axis: ``axis=-1``.
 
-            {{pad_width: sequence of `int`}}
+            {{pad_width: sequence of `int`, optional}}
+
+            {{to_size: `int`, optional}}
 
             {{inplace: `bool`, optional}}
 
@@ -2222,11 +2224,44 @@ def pad_missing(self, axis, pad_width, inplace=False):
          [--  3  4  5 -- --]
          [-- -- -- -- -- --]]
 
+        >>> g = d.pad_missing(1, to_size=5)
+        >>> print(g.array)
+        [[0 1 2 -- --]
+         [3 4 5 -- --]]
+
         """
-        try:
-            pad_width0, pad_width1 = pad_width
-        except (TypeError, ValueError):
-            raise ValueError("'pad_width' must be a sequence of two integers")
+        if not 0 <= axis < self.ndim:
+            raise ValueError(
+                f"'axis' must be a valid dimension position. Got {axis}"
+            )
+
+        if to_size is not None:
+            # Set pad_width from to_size
+            if pad_width is not None:
+                raise ValueError("Can't set both 'pad_width' and 'to_size'")
+
+            pad_width = (0, to_size - self.shape[axis])
+        elif pad_width is None:
+            raise ValueError("Must set either 'pad_width' or 'to_size'")
+
+        pad_width = np.asarray(pad_width)
+        if pad_width.shape != (2,) or not pad_width.dtype.kind == "i":
+            raise ValueError(
+                "'pad_width' must be a sequence of two integers. "
+                f"Got: {pad_width}"
+            )
+
+        pad_width = tuple(pad_width)
+        if any(n < 0 for n in pad_width):
+            if to_size is not None:
+                raise ValueError(
+                    f"'to_size' ({to_size}) must not be smaller than the "
+                    f"original axis size ({self.shape[axis]})"
+                )
+
+            raise ValueError(
+                f"Can't set a negative number of pad values. Got: {pad_width}"
+            )
 
         d = _inplace_enabled_define_and_cleanup(self)
 

cf/docstring/docstring.py

@@ -588,9 +588,13 @@
                 If True then return `False` if weights can't be found,
                 rather than raising an exception.""",
     # pad_width
-    "{{pad_width: sequence of `int`}}": """pad_width: sequence of `int`
+    "{{pad_width: sequence of `int`, optional}}": """pad_width: sequence of `int`, optional
                 Number of values to pad before and after the edges of
                 the axis.""",
+    # to_size
+    "{{to_size: `int`, optional}}": """to_size: `int`, optional
+                Pad the axis after so that the new axis has the given
+                size.""",
     # ----------------------------------------------------------------
     # Method description substitutions (4 levels of indentation)
     # ----------------------------------------------------------------

cf/field.py

@@ -11954,7 +11954,7 @@ def halo(
         return f
 
     @_inplace_enabled(default=False)
-    def pad_missing(self, axis, pad_width, inplace=False):
+    def pad_missing(self, axis, pad_width=None, to_size=None, inplace=False):
         """Pad an axis with missing data.
 
          The field's data and all metadata constructs that span the
@@ -11972,7 +11972,9 @@ def pad_missing(self, axis, pad_width, inplace=False):
                  ``'X'``, the domain axis construct returned by
                  ``f.domain_axis('X')`` is selected.
 
-             {{pad_width: sequence of `int`}}
+             {{pad_width: sequence of `int`, optional}}
+
+             {{to_size: `int`, optional}}
 
              {{inplace: `bool`, optional}}
 
@@ -11984,7 +11986,7 @@ def pad_missing(self, axis, pad_width, inplace=False):
 
         **Examples*
 
-        >>>  f = cf.example_field(6)
+        >>> f = cf.example_field(6)
         >>> print(f)
         Field: precipitation_amount (ncvar%pr)
         --------------------------------------
@@ -12028,6 +12030,17 @@ def pad_missing(self, axis, pad_width, inplace=False):
          [5.0 6.0 7.0 8.0 -- -- -- -- --]
          [ --  --  --  -- -- -- -- -- --]]
 
+        >>> print(f.pad_missing('time', to_size=6))
+        Field: precipitation_amount (ncvar%pr)
+        --------------------------------------
+        Data            : precipitation_amount(cf_role=timeseries_id(2), time(6))
+        Dimension coords: time(6) = [2000-01-16 12:00:00, ..., --] gregorian
+        Auxiliary coords: latitude(cf_role=timeseries_id(2)) = [25.0, 7.0] degrees_north
+                        : longitude(cf_role=timeseries_id(2)) = [10.0, 40.0] degrees_east
+                        : cf_role=timeseries_id(cf_role=timeseries_id(2)) = [x1, y2]
+                        : altitude(cf_role=timeseries_id(2), 3, 4) = [[[1.0, ..., --]]] m
+        Coord references: grid_mapping_name:latitude_longitude
+
         """
         f = _inplace_enabled_define_and_cleanup(self)
 
@@ -12048,7 +12061,9 @@ def pad_missing(self, axis, pad_width, inplace=False):
         iaxis = data_axes.index(axis)
 
         # Pad the field
-        super(Field, f).pad_missing(iaxis, pad_width, inplace=True)
+        super(Field, f).pad_missing(
+            iaxis, pad_width=pad_width, to_size=to_size, inplace=True
+        )
 
         # Set new domain axis size
         domain_axis = f.domain_axis(axis)
@@ -12062,7 +12077,9 @@ def pad_missing(self, axis, pad_width, inplace=False):
 
             # Pad the construct
             iaxis = construct_axes.index(axis)
-            construct.pad_missing(iaxis, pad_width, inplace=True)
+            construct.pad_missing(
+                iaxis, pad_width=pad_width, to_size=to_size, inplace=True
+            )
 
         return f
 

cf/mixin/propertiesdata.py

@@ -1889,7 +1889,7 @@ def minimum(self):
         )
 
     @_inplace_enabled(default=False)
-    def pad_missing(self, axis, pad_width, inplace=False):
+    def pad_missing(self, axis, pad_width=None, to_size=None, inplace=False):
         """Pad an axis with missing data.
 
         :Parameters:
@@ -1898,7 +1898,9 @@ def pad_missing(self, axis, pad_width, inplace=False):
                 Select the axis for which the padding is to be
                 applied.
 
-            {{pad_width: sequence of `int`}}
+            {{pad_width: sequence of `int`, optional}}
+
+            {{to_size: `int`, optional}}
 
             {{inplace: `bool`, optional}}
 
@@ -1914,6 +1916,7 @@ def pad_missing(self, axis, pad_width, inplace=False):
             "pad_missing",
             axis=axis,
             pad_width=pad_width,
+            to_size=to_size,
             inplace=inplace,
         )
 

cf/mixin/propertiesdatabounds.py

@@ -3875,7 +3875,7 @@ def inspect(self):
         print(cf_inspect(self))  # pragma: no cover
 
     @_inplace_enabled(default=False)
-    def pad_missing(self, axis, pad_width, inplace=False):
+    def pad_missing(self, axis, pad_width=None, to_size=None, inplace=False):
         """Pad an axis with missing data.
 
         :Parameters:
@@ -3884,7 +3884,9 @@ def pad_missing(self, axis, pad_width, inplace=False):
                 Select the axis for which the padding is to be
                 applied.
 
-            {{pad_width: sequence of `int`}}
+            {{pad_width: sequence of `int`, optional}}
+
+            {{to_size: `int`, optional}}
 
             {{inplace: `bool`, optional}}
 
@@ -3902,6 +3904,7 @@ def pad_missing(self, axis, pad_width, inplace=False):
             interior_ring=True,
             axis=axis,
             pad_width=pad_width,
+            to_size=to_size,
             inplace=inplace,
         )
 

cf/test/test_Data.py

@@ -4735,15 +4735,27 @@ def test_Data_pad_missing(self):
         """Test Data.pad_missing."""
         d = cf.Data(np.arange(6).reshape(2, 3))
 
-        self.assertIsNone(d.pad_missing(1, (1, 2), inplace=True))
+        g = d.pad_missing(1, to_size=5)
+        self.assertEqual(g.shape, (2, 5))
+        self.assertTrue(g[:, 3:].mask.all())
+
+        self.assertIsNone(d.pad_missing(1, pad_width=(1, 2), inplace=True))
         self.assertEqual(d.shape, (2, 6))
         self.assertTrue(d[:, 0].mask.all())
         self.assertTrue(d[:, 4:].mask.all())
 
-        e = d.pad_missing(0, (0, 1))
+        e = d.pad_missing(0, pad_width=(0, 1))
         self.assertEqual(e.shape, (3, 6))
         self.assertTrue(e[2, :].mask.all())
 
+        # Can't set both pad_width and to_size
+        with self.assertRaises(ValueError):
+            d.pad_missing(0, pad_width=(0, 1), to_size=99)
+
+        # Axis out of bounds
+        with self.assertRaises(ValueError):
+            d.pad_missing(99, to_size=99)
+
 
 if __name__ == "__main__":
     print("Run date:", datetime.datetime.now())

cf/test/test_Field.py

@@ -2669,16 +2669,20 @@ def test_Field_file_location(self):
         f.del_file_location("/invalid")
         self.assertEqual(f.file_locations(), set((location,)))
 
-    def test_Data_pad_missing(self):
+    def test_Field_pad_missing(self):
         """Test Field.pad_missing."""
         f = cf.example_field(0)
 
-        self.assertIsNone(f.pad_missing("X", (1, 2), inplace=True))
+        g = f.pad_missing("X", to_size=10)
+        self.assertEqual(g.shape, (5, 10))
+        self.assertTrue(g[:, 8:].mask.all())
+
+        self.assertIsNone(f.pad_missing("X", pad_width=(1, 2), inplace=True))
         self.assertEqual(f.shape, (5, 11))
         self.assertTrue(f[:, 0].mask.all())
         self.assertTrue(f[:, 9:].mask.all())
 
-        g = f.pad_missing("Y", (0, 1))
+        g = f.pad_missing("Y", pad_width=(0, 1))
         self.assertEqual(g.shape, (6, 11))
         self.assertTrue(g[5, :].mask.all())