collapse sum

Author: davidhassell

cf/field.py

@@ -162,10 +162,11 @@
         "average",
         "sd",
         "standard_deviation",
+        "sum",
         "var",
         "variance",
-        # 'sum_of_weights',
-        # 'sum_of_weights2',
+        "sum_of_weights",
+        "sum_of_weights2",
         "integral",
         "root_mean_square",
     )
@@ -6194,7 +6195,7 @@ def collapse(
         group_span=None,
         group_contiguous=1,
         measure=False,
-        scale=1,
+        scale=None,
         radius="earth",
         great_circle=False,
         verbose=None,
@@ -6719,6 +6720,11 @@ def collapse(
                 .. note:: By default *weights* is `None`, resulting in
                           **unweighted calculations**.
 
+                .. note:: Unless *measure* is True, the units of
+                          weights are ignored default *weights* is
+                          `None`, resulting in **unweighted
+                          calculations**.
+
                 If the alternative form of providing the collapse method
                 and axes combined as a CF cell methods-like string via the
                 *method* parameter has been used, then the *axes*
@@ -6765,7 +6771,7 @@ def collapse(
                 Create weights which are cell measures, i.e. which
                 describe actual cell sizes (e.g. cell area) with
                 appropriate units (e.g. metres squared). By default the
-                weights are normalised and have arbitrary units.
+                weights units are ignored.
 
                 Cell measures can be created for any combination of
                 axes. For example, cell measures for a time axis are the
@@ -6801,18 +6807,17 @@ def collapse(
             scale: number or `None`, optional
                 If set to a positive number then scale the weights so
                 that they are less than or equal to that number. If
-                set to `None` the weights are not scaled. In general
-                the default is for weights to be scaled to lie between
-                0 and 1; however if *measure* is True then the weights
-                are never scaled and the value of *scale* is taken as
-                `None`, regardless of its setting.
+                set to `None`, the default, then the weights are not
+                scaled.
 
                 *Parameter example:*
                   To scale all weights so that they lie between 0 and
-                  10 ``scale=10``.
+                  1 ``scale=1``.
 
                 .. versionadded:: 3.0.2
 
+                .. versionchanged:: 3.16.0 Default changed to `None`
+
             radius: optional
                 Specify the radius used for calculating the areas of
                 cells defined in spherical polar coordinates. The
@@ -7698,6 +7703,12 @@ def collapse(
         # ------------------------------------------------------------
         # Parse the methods and axes
         # ------------------------------------------------------------
+        if measure and scale is not None:
+            raise ValueError(
+                "'scale' must be None when 'measure' is True. "
+                f"Got: scale={scale!r}"
+            )
+
         if ":" in method:
             # Convert a cell methods string (such as 'area: mean dim3:
             # dim2: max T: minimum height: variance') to a CellMethod
@@ -7916,8 +7927,15 @@ def collapse(
                     g_weights = None
                 else:
                     if measure:
-                        # Never scale weights that are cell measures
-                        scale = None
+                        if method not in (
+                            "integral",
+                            "sum_of_weights",
+                            "sum_of_weights2",
+                        ):
+                            raise ValueError(
+                                f"Can't set measure=True for {method!r} "
+                                "collapses"
+                            )
                     elif method == "integral":
                         raise ValueError(
                             f"Must set measure=True for {method!r} collapses"
@@ -8006,8 +8024,14 @@ def collapse(
             d_kwargs = {}
             if weights is not None:
                 if measure:
-                    # Never scale weights that are cell measures
-                    scale = None
+                    if method not in (
+                        "integral",
+                        "sum_of_weights",
+                        "sum_of_weights2",
+                    ):
+                        raise ValueError(
+                            f"Can't set measure=True for {method!r} collapses"
+                        )
                 elif method == "integral":
                     raise ValueError(
                         f"Must set measure=True for {method!r} collapses"

cf/test/test_Field.py

@@ -441,7 +441,6 @@ def test_Field_collapse(self):
 
         for axes in axes_combinations(f):
             for method in (
-                "sum",
                 "min",
                 "max",
                 "minimum_absolute_value",
@@ -451,8 +450,6 @@ def test_Field_collapse(self):
                 "sample_size",
                 "sum_of_squares",
                 "median",
-                "sum_of_weights",
-                "sum_of_weights2",
             ):
                 for weights in (None, "area"):
                     a = f.collapse(method, axes=axes, weights=weights).data
@@ -462,10 +459,13 @@ def test_Field_collapse(self):
                     )
 
             for method in (
+                "sum",
                 "mean",
                 "mean_absolute_value",
                 "mean_of_upper_decile",
                 "root_mean_square",
+                "sum_of_weights",
+                "sum_of_weights2",
             ):
                 for weights in (None, "area"):
                     if weights is not None:

cf/test/test_collapse.py

@@ -1,6 +1,5 @@
 import datetime
 import faulthandler
-import inspect
 import os
 import unittest
 
@@ -17,17 +16,7 @@ def setUp(self):
             os.path.dirname(os.path.abspath(__file__)), "test_file2.nc"
         )
 
-        self.test_only = []
-
-    #        self.test_only = ['nought']
-    #        self.test_only = ['test_Field_collapse']
-    #        self.test_only = ['test_Field_collapse_CLIMATOLOGICAL_TIME']
-    #        self.test_only = ['test_Field_collapse_GROUPS']
-
     def test_Field_collapse_CLIMATOLOGICAL_TIME(self):
-        if self.test_only and inspect.stack()[0][3] not in self.test_only:
-            return
-
         verbose = False
 
         f = cf.example_field(2)
@@ -258,9 +247,6 @@ def test_Field_collapse_CLIMATOLOGICAL_TIME(self):
         self.assertEqual(list(g.shape), expected_shape)
 
     def test_Field_collapse(self):
-        if self.test_only and inspect.stack()[0][3] not in self.test_only:
-            return
-
         verbose = False
 
         f = cf.read(self.filename2)[0]
@@ -380,22 +366,7 @@ def test_Field_collapse(self):
                 f"{bound.day}!={group.offset.day}, group={group}",
             )
 
-    #            for group in (cf.D(30),
-    #                          cf.D(30, month=12),
-    #                          cf.D(30, day=16),
-    #                          cf.D(30, month=11, day=27)):
-    #                g = f.collapse('T: mean', group=group)
-    #                bound = g.coord('T').bounds.datetime_array[0, 1]
-    #                self.assertEqual(
-    #                    bound.day, group.offset.day,
-    #                    "{}!={}, bound={}, group={}".format(
-    #                        bound.day, group.offset.day, bound, group)
-    #                )
-
     def test_Field_collapse_WEIGHTS(self):
-        if self.test_only and inspect.stack()[0][3] not in self.test_only:
-            return
-
         verbose = False
 
         f = cf.example_field(2)
@@ -415,9 +386,6 @@ def test_Field_collapse_WEIGHTS(self):
         i.collapse("area: maximum")
 
     def test_Field_collapse_GROUPS(self):
-        if self.test_only and inspect.stack()[0][3] not in self.test_only:
-            return
-
         verbose = False
 
         f = cf.example_field(2)
@@ -695,15 +663,96 @@ def test_Field_collapse_GROUPS(self):
             print(g.constructs)
         self.assertEqual(list(g.shape), expected_shape, g.shape)
 
-
-#            g = f[::2].collapse('T: mean', group=cf.M(5, month=12),
-#                                group_span=cf.M(5),group_contiguous=1)
-#            g = f.collapse('T: mean', group=cf.M(5, month= 3),
-#                           group_contiguous=1)
-#            g = f.collapse('T: mean', group=cf.M(5, month=12),
-#                           group_contiguous=2)
-#            g = f.collapse('T: mean', group=cf.M(5, month= 3),
-#                           group_contiguous=2)
+    def test_Field_collapse_sum(self):
+        f = cf.example_field(0)
+        w = f.weights("area", measure=True)
+        a = f.array
+        wa = w.array
+        ws = a * wa
+
+        g = f.collapse("area: sum")
+        self.assertTrue((g.array == a.sum()).all())
+
+        g = f.collapse("area: sum", weights=w)
+        self.assertTrue((g.array == ws.sum()).all())
+        self.assertEqual(g.Units, cf.Units("1"))
+
+        g = f.collapse("area: sum", weights=w, scale=1)
+        self.assertTrue((g.array == (ws / wa.max()).sum()).all())
+        self.assertEqual(g.Units, cf.Units("1"))
+
+        g = f.collapse("area: sum", weights=w)
+        self.assertTrue((g.array == ws.sum()).all())
+        self.assertEqual(g.Units, cf.Units("1"))
+
+        # Can't set measure=True for 'sum' collapses
+        with self.assertRaises(ValueError):
+            g = f.collapse("area: sum", weights=w, measure=True)
+
+    def test_Field_collapse_integral(self):
+        f = cf.example_field(0)
+        w = f.weights("area", measure=True)
+        a = f.array
+        wa = w.array
+        ws = a * wa
+
+        g = f.collapse("area: integral", weights=w, measure=True)
+        self.assertTrue((g.array == ws.sum()).all())
+        self.assertEqual(g.Units, cf.Units("m2"))
+
+        # Must set the 'weights' parameter for 'integral' collapses
+        with self.assertRaises(ValueError):
+            g = f.collapse("area: integral")
+
+        # Must set measure=True for 'integral' collapses
+        with self.assertRaises(ValueError):
+            g = f.collapse("area: integral", weights=w)
+
+        # 'scale' must be None when 'measure' is True
+        with self.assertRaises(ValueError):
+            g = f.collapse("area: integral", weights=w, measure=True, scale=1)
+
+    def test_Field_collapse_sum_weights(self):
+        f = cf.example_field(0)
+        w = f.weights("area", measure=True)
+        wa = w.array
+
+        g = f.collapse("area: sum_of_weights")
+        self.assertTrue((g.array == 40).all())
+        self.assertEqual(g.Units, cf.Units())
+
+        g = f.collapse("area: sum_of_weights", weights=w)
+        self.assertTrue((g.array == wa.sum()).all())
+        self.assertEqual(g.Units, cf.Units("m2"))
+
+        g = f.collapse("area: sum_of_weights", weights=w, measure=True)
+        self.assertTrue((g.array == wa.sum()).all())
+        self.assertEqual(g.Units, cf.Units("m2"))
+
+        g = f.collapse("area: sum_of_weights", weights=w, scale=1)
+        self.assertTrue((g.array == (wa / wa.max()).sum()).all())
+        self.assertEqual(g.Units, cf.Units("1"))
+
+    def test_Field_collapse_sum_weights2(self):
+        f = cf.example_field(0)
+        w = f.weights("area", measure=True)
+        wa = w.array**2
+
+        g = f.collapse("area: sum_of_weights2")
+        self.assertTrue((g.array == 40).all())
+        self.assertEqual(g.Units, cf.Units())
+
+        g = f.collapse("area: sum_of_weights2", weights=w)
+        self.assertTrue((g.array == wa.sum()).all())
+        self.assertEqual(g.Units, cf.Units("m4"))
+
+        g = f.collapse("area: sum_of_weights2", weights=w, measure=True)
+        self.assertTrue((g.array == wa.sum()).all())
+        self.assertEqual(g.Units, cf.Units("m4"))
+
+        g = f.collapse("area: sum_of_weights2", weights=w, scale=1)
+        self.assertTrue((g.array == (wa / wa.max()).sum()).all())
+        self.assertEqual(g.Units, cf.Units("1"))
 
 
 if __name__ == "__main__":