Impl: ignore_missing option on get_flag, v0.3.1

Request from @A-Mahon:

    Add a method to ncflag that combines the functionality of find_flag
    and get_flag, flattening the arrays as in get_flag, but not raising
    an exception if any of the flags are not present.

Author: 5tefan

ncflag/flag_wrapper.py

@@ -87,15 +87,15 @@ def init_from_netcdf(cls, nc_var, shape=None, fill=None):
                 nc_var.flag_meanings,
                 nc_var.flag_values,
                 getattr(nc_var, "flag_masks", None),
-                name=nc_var.name
+                name=nc_var.name,
             )
         else:
             instance = cls(
                 nc_var[:],
                 nc_var.flag_meanings,
                 nc_var.flag_values,
                 getattr(nc_var, "flag_masks", None),
-                name=nc_var.name
+                name=nc_var.name,
             )
 
         instance._nc_var = nc_var
@@ -127,26 +127,31 @@ def write_to_netcdf(self, nc_var=None):
             # only write masks if they aren't the default all bits 1 or somethign existed before
             nc_var.flag_masks = self._flag_masks
 
-    def get_flag(self, flag_meaning):
+    def get_flag(self, flag_meaning, ignore_missing=False):
         """
         Get an array of booleans, same length as flags, at each index indicating if flag_meaning was set.
 
         :type flag_meaning: str | list[str] | tuple[str]
-        :param flag_meaning: flag meaning(s) to be looked up
+        :param flag_meaning: flag meaning(s) to be looked up, bitwise_or reduced across first axis if multiple
+        :type ignore_missing: bool
+        :param ignore_missing: if False, raises exception for missing flags, if True assumes missing
+            flags are not set.
         :rtype: np.array
         :return: array of booleans where flag_meaning(s) is(are) set
         """
 
         def get(meaning):
-            """ Get the meaning of an individual flag_meaning. """
+            """Get the meaning of an individual flag_meaning."""
+            if ignore_missing and meaning not in self.flag_meanings:
+                return np.full_like(self.flags, False, dtype=bool)
             index = self.flag_meanings.index(meaning)
 
             # start by default assuming there are no flags set.
             # Do not return a masked array! All value should be either True or False.
             # A flag is either set or not set. There is no inbetween.
-            default = np.full(self.flags.shape, False, dtype=np.bool)
+            default = np.full(self.flags.shape, False, dtype=bool)
             if not np.ma.is_masked(self.flags):
-                mask = np.full_like(self.flags, True, np.bool)
+                mask = np.full_like(self.flags, True, dtype=bool)
             else:
                 mask = ~np.ma.getmask(self.flags)
 
@@ -156,15 +161,15 @@ def get(meaning):
             ) == self._flag_values[index]
             return default
 
+        any_set = np.zeros(self.flags.shape, dtype=bool)
         if isinstance(flag_meaning, (list, tuple)):
             # if receive a sequence, or them together.
-            any_set = np.zeros(self.flags.shape, dtype=np.bool)
             for each in flag_meaning:
                 any_set |= get(each)
-            return any_set
         else:
             # otherwise just get the one.
-            return get(flag_meaning)
+            any_set |= get(flag_meaning)
+        return any_set
 
     def reduce(self, exclude_mask=0, axis=-1):
         """
@@ -183,7 +188,9 @@ def reduce(self, exclude_mask=0, axis=-1):
         if exclude_mask != 0:
             exclude_mask = self.flags.dtype.type(exclude_mask)
             excluded_flags_not_set = (self.flags & exclude_mask) == 0
-            new_flags = np.ma.bitwise_or.reduce(self.flags * excluded_flags_not_set, axis=axis)
+            new_flags = np.ma.bitwise_or.reduce(
+                self.flags * excluded_flags_not_set, axis=axis
+            )
         else:
             new_flags = np.ma.bitwise_or.reduce(self.flags, axis=axis)
 
@@ -197,7 +204,7 @@ def reduce(self, exclude_mask=0, axis=-1):
     def get_flag_at_index(self, flag_meaning, i):
         """
         Returns True or False if flag_meaning set at index i?
-        
+
         :type flag_meaning: str
         :param flag_meaning: flag meaning intended to be set
         :type i: int
@@ -215,7 +222,7 @@ def get_flag_at_index(self, flag_meaning, i):
     def get_flags_set_at_index(self, i, exit_on_good=False):
         """
         Get a list of the flag_meanings set at a particular index.
-        
+
         :type i: int
         :param i: the index to examine
         :type exit_on_good: bool
@@ -279,7 +286,7 @@ def set_flag(self, flag_meaning, should_be_set, zero_if_unset=False):
         :return: None
         """
         index = self.flag_meanings.index(flag_meaning)
-        bool_flags = np.array(should_be_set).astype(np.bool)
+        bool_flags = np.array(should_be_set).astype(bool)
         if np.ma.is_masked(self.flags):
             # if it's masked, set initial flag to 0 where going to set flags (from bool_flags)
             masked_modify = bool_flags & np.ma.getmaskarray(self.flags) | zero_if_unset
@@ -300,7 +307,7 @@ def set_flag_at_index(self, flag_meaning, i):
         AND the original flag with the NOT mask, to 0 out any bits impacting the target location
         of the flag_meaning within the bit vec while leaving the rest set or unset as they were.
         Then, OR the flag value onto the target, preserves all other independent flags set.
-        
+
         :type flag_meaning: str
         :param flag_meaning: flag meaning intended to be set
         :type i: int
@@ -325,7 +332,7 @@ def get_value_for_meaning(self, flag_meaning):
         eg:
         >>> f = FlagWrap([], "good bad", [0, 1])
         >>> f.flags = np.full(10, f.get_value_for_meaning("bad"), dtype=np.uint)
-        
+
         Note: Raises ValueError if flag_meaning is not found.
 
         :type flag_meaning: str
@@ -347,7 +354,7 @@ def get_mask_for_meaning(self, flag_meaning):
         masks together in order to test if *any* of those flags are set.
 
         Note: Raises ValueError if flag_meaning not found.
-        
+
         :type flag_meaning: str
         :param flag_meaning: string flag name to return corrsponding mask of
         :rtype: int
@@ -369,4 +376,3 @@ def is_valid_meaning(self, flag_meaning):
         :return: if flag_meaning is a valid meaning for the flag.
         """
         return flag_meaning in self.flag_meanings
-

setup.py

@@ -3,7 +3,7 @@
 
 setup(
     name="ncflag",
-    version="0.3.0",
+    version="0.3.1",
     description="Utility and library to interface with CF-Compliant NetCDF flag variables.",
     author="Stefan Codrescu",
     author_email="[email protected]",

test/test_misc_api.py

@@ -4,19 +4,24 @@
 
 
 class TestApi(TestCase):
+    def setUp(self):
+        self.flags = np.array([0, 0, 1, 2, 3], dtype=np.ubyte)
+        self.flag_meanings = "good medium bad extra_bad"
+        self.flag_values = np.array([0, 1, 2, 3])
+        self.f = FlagWrap(self.flags, self.flag_meanings, self.flag_values)
 
     def test_valid_meaning(self):
-        flags = np.array([0, 0, 1, 2, 3], dtype=np.ubyte)
-        flag_meanings = "good medium bad extra_bad"
-        flag_values = np.array([0, 1, 2, 3])
-        f = FlagWrap(flags, flag_meanings, flag_values)
-
-        for flag_meaning in flag_meanings.split():
-            self.assertTrue(f.is_valid_meaning(flag_meaning))
+        for flag_meaning in self.flag_meanings.split():
+            self.assertTrue(self.f.is_valid_meaning(flag_meaning))
 
         for not_a_meaning in ["test", "not", "valid", "good1", "extra"]:
-            self.assertFalse(f.is_valid_meaning(not_a_meaning))
-        
-
+            self.assertFalse(self.f.is_valid_meaning(not_a_meaning))
 
+    def test_get_flag_on_missing_meaning(self):
+        for not_a_meaning in ["test", "not", "valid", "good1", "extra"]:
+            flags = self.f.get_flag(not_a_meaning, ignore_missing=True)
+            self.assertEqual(np.count_nonzero(flags), 0)
 
+            with self.assertRaises(ValueError):
+                # check backwards compat: missing meaning raises
+                self.f.get_flag(not_a_meaning, ignore_missing=False)

test/test_reduce.py

@@ -6,28 +6,17 @@
 class TestReduce(TestCase):
     def test_reduce_axis0(self):
 
-        flags = np.array([
-            [0, 1],
-            [1, 0],
-            [0, 0],
-            [1, 1]
-        ], dtype=np.ubyte)
+        flags = np.array([[0, 1], [1, 0], [0, 0], [1, 1]], dtype=np.ubyte)
 
         f = FlagWrap(flags, "good bad", [0, 1])
 
         f_reduced = f.reduce(axis=0)
         np.testing.assert_array_equal(f_reduced.get_flag("good"), [0, 0])
         np.testing.assert_array_equal(f_reduced.get_flag("bad"), [1, 1])
 
-
     def test_reduce_axis1(self):
 
-        flags = np.array([
-            [0, 1],
-            [1, 0],
-            [0, 0],
-            [1, 1]
-        ], dtype=np.ubyte)
+        flags = np.array([[0, 1], [1, 0], [0, 0], [1, 1]], dtype=np.ubyte)
 
         f = FlagWrap(flags, "good bad", [0, 1])
 
@@ -37,12 +26,15 @@ def test_reduce_axis1(self):
 
     def test_reduce_mask(self):
 
-        flags = np.array([
-            [3, 1],  # red + green, red
-            [0, 4],  # ---, blue
-            [4, 3],  # blue, red + green
-            [2, 1]   # green, red
-        ], dtype=np.ubyte)
+        flags = np.array(
+            [
+                [3, 1],  # red + green, red
+                [0, 4],  # ---, blue
+                [4, 3],  # blue, red + green
+                [2, 1],  # green, red
+            ],
+            dtype=np.ubyte,
+        )
 
         f = FlagWrap(flags, "red green blue", [1, 2, 4], [1, 2, 4])
 
@@ -51,11 +43,8 @@ def test_reduce_mask(self):
         f_reduced = f.reduce(axis=1, exclude_mask=1)
 
         # there should be no red, since we masked it
-        np.testing.assert_array_equal(f_reduced.get_flag("red"), [0, 0, 0, 0]) 
+        np.testing.assert_array_equal(f_reduced.get_flag("red"), [0, 0, 0, 0])
 
         # make sure green and blue got through, when they weren't mixed with red
         np.testing.assert_array_equal(f_reduced.get_flag("green"), [0, 0, 0, 1])
         np.testing.assert_array_equal(f_reduced.get_flag("blue"), [0, 1, 1, 0])
-
-        
-

test/test_theoretical.py

@@ -14,8 +14,8 @@ def test_teject_misformed_flags(self):
             FlagWrap(np.array([]), "flag1 flag2", [1, 2], [-1, -1, -1])
 
     def test_exclusive_flag_type(self):
-        """ A barrage of tests to make sure everything works properly for flag variables defined
-         so that every flag_meaning is mutually exclusive. """
+        """A barrage of tests to make sure everything works properly for flag variables defined
+        so that every flag_meaning is mutually exclusive."""
 
         original_flags = np.array([0, 0, 1, 2, 3, -1], dtype=np.ubyte)
 
@@ -122,9 +122,9 @@ def test_exclusive_flag_type(self):
         # ok, we'll call it good there.
 
     def test_maskedarray_initial_flags(self):
-        """ Similar to the previous test, except start with a masked array and fill...
+        """Similar to the previous test, except start with a masked array and fill...
         This will be what it looks like if someone does init_from_netcdf for an unwritten variable
-        that actually has shape. """
+        that actually has shape."""
 
         original_flags = np.ma.zeros(5, dtype=np.ubyte)
         original_flags.mask = True