support for "no unit" values (#125)

* add new "no unit" values

* remove the integer "no unit" value

* add tests to check whether overriding a unit works

* add None back

* separate the roles for None

* allow "no unit" values in quantify

* remove obsolete TODO comments

Creating a pint.Unit instance directly will create it from the default registry, so the
first and second TODO comments actually referred to the same issue. We also decided to
have specific packages (i.e. cf-xarray) provide the unit registry.

* update the comment about the type check

* also check the non-dimension coordinate

* docs fix

* document the "no unit" values

* update whats-new.rst

* remove the fill_value parameter again

* override with a different unit

* add tests to make sure "no unit" values on attrs won't override

* only return the attrs' no unit value if units got the default value

* fix the test

* don't use "1" as a no unit value

* use pytest.raises instead of getattr with a default

* add examples demonstrating the use the "no unit" values

* fix the docs [skip-ci]

Author: keewis

docs/whats-new.rst

@@ -5,7 +5,9 @@ What's new
 
 0.3 (*unreleased*)
 ------------------
-
+- allow special "no unit" values in :py:meth:`Dataset.pint.quantify` and
+  :py:meth:`DataArray.pint.quantify` (:pull:`125`)
+  By `Justus Magin <https://github.com/keewis>`_.
 
 0.2 (May 10 2021)
 -----------------

pint_xarray/accessors.py

@@ -8,8 +8,11 @@
 from xarray.core.dtypes import NA
 
 from . import conversion
+from .conversion import no_unit_values
 from .errors import format_error_message
 
+_default = object()
+
 
 def setup_registry(registry):
     """set up the given registry for use with pint_xarray
@@ -91,7 +94,7 @@ def units_to_str_or_none(mapping, unit_format):
 # based on xarray.core.utils.either_dict_or_kwargs
 # https://github.com/pydata/xarray/blob/v0.15.1/xarray/core/utils.py#L249-L268
 def either_dict_or_kwargs(positional, keywords, method_name):
-    if positional is not None:
+    if positional not in (_default, None):
         if not is_dict_like(positional):
             raise ValueError(
                 f"the first argument to .{method_name} must be a dictionary"
@@ -131,17 +134,16 @@ def get_registry(unit_registry, new_units, existing_units):
 
 
 def _decide_units(units, registry, unit_attribute):
-    if units is None and unit_attribute is None:
+    if units is _default and unit_attribute is _default:
         # or warn and return None?
         raise ValueError("no units given")
-    elif units is None:
-        # TODO option to read and decode units according to CF conventions (see MetPy)?
+    elif units in no_unit_values or isinstance(units, Unit):
+        # TODO what happens if they pass in a Unit from a different registry
+        return units
+    elif units is _default:
+        if unit_attribute in no_unit_values:
+            return unit_attribute
         units = registry.parse_units(unit_attribute)
-    elif isinstance(units, Unit):
-        # TODO do we have to check what happens if someone passes a Unit instance
-        # without creating a unit registry?
-        # TODO and what happens if they pass in a Unit from a different registry
-        pass
     else:
         units = registry.parse_units(units)
     return units
@@ -243,7 +245,7 @@ class PintDataArrayAccessor:
     def __init__(self, da):
         self.da = da
 
-    def quantify(self, units=None, unit_registry=None, **unit_kwargs):
+    def quantify(self, units=_default, unit_registry=None, **unit_kwargs):
         """
         Attach units to the DataArray.
 
@@ -269,7 +271,7 @@ def quantify(self, units=None, unit_registry=None, **unit_kwargs):
             pint.Unit, will be used as the DataArray's units. If a
             dict-like, it should map a variable name to the desired
             unit (use the DataArray's name to refer to its data). If
-            not provided, will try to read them from
+            not provided, ``quantify`` will try to read them from
             ``DataArray.attrs['units']`` using pint's parser. The
             ``"units"`` attribute will be removed from all variables
             except from dimension coordinates.
@@ -285,6 +287,11 @@ def quantify(self, units=None, unit_registry=None, **unit_kwargs):
             DataArray whose wrapped array data will now be a Quantity
             array with the specified units.
 
+        Notes
+        -----
+        ``"none"`` and ``None`` can be used to mark variables that should not
+        be quantified.
+
         Examples
         --------
         >>> da = xr.DataArray(
@@ -297,6 +304,18 @@ def quantify(self, units=None, unit_registry=None, **unit_kwargs):
         <Quantity([0.4 0.9 1.7 4.8 3.2 9.1], 'hertz')>
         Coordinates:
           * wavelength  (wavelength) float64 0.0001 0.0002 0.0004 0.0006 0.001 0.002
+
+        Don't quantify the data:
+
+        >>> da = xr.DataArray(
+        ...     data=[0.4, 0.9],
+        ...     dims=["wavelength"],
+        ...     attrs={"units": "Hz"},
+        ... )
+        >>> da.pint.quantify(units=None)
+        <xarray.DataArray (wavelength: 2)>
+        array([0.4, 0.9])
+        Dimensions without coordinates: wavelength
         """
 
         if isinstance(self.da.data, Quantity):
@@ -305,7 +324,7 @@ def quantify(self, units=None, unit_registry=None, **unit_kwargs):
                 f"already has units {self.da.data.units}"
             )
 
-        if isinstance(units, (str, pint.Unit)):
+        if units is None or isinstance(units, (str, pint.Unit)):
             if self.da.name in unit_kwargs:
                 raise ValueError(
                     f"ambiguous values given for {repr(self.da.name)}:"
@@ -320,15 +339,15 @@ def quantify(self, units=None, unit_registry=None, **unit_kwargs):
 
         unit_attrs = conversion.extract_unit_attributes(self.da)
 
-        possible_new_units = zip_mappings(units, unit_attrs)
+        possible_new_units = zip_mappings(units, unit_attrs, fill_value=_default)
         new_units = {}
         invalid_units = {}
         for name, (unit, attr) in possible_new_units.items():
-            if unit is not None or attr is not None:
+            if unit is not _default or attr is not _default:
                 try:
                     new_units[name] = _decide_units(unit, registry, attr)
                 except (ValueError, pint.UndefinedUnitError) as e:
-                    if unit is not None:
+                    if unit is not _default:
                         type = "parameter"
                         reported_unit = unit
                     else:
@@ -880,7 +899,7 @@ class PintDatasetAccessor:
     def __init__(self, ds):
         self.ds = ds
 
-    def quantify(self, units=None, unit_registry=None, **unit_kwargs):
+    def quantify(self, units=_default, unit_registry=None, **unit_kwargs):
         """
         Attach units to the variables of the Dataset.
 
@@ -905,10 +924,10 @@ def quantify(self, units=None, unit_registry=None, **unit_kwargs):
         units : mapping of hashable to unit-like, optional
             Physical units to use for particular DataArrays in this
             Dataset. It should map variable names to units (unit names
-            or ``pint.Unit`` objects). If not provided, will try to
-            read them from ``Dataset[var].attrs['units']`` using
-            pint's parser. The ``"units"`` attribute will be removed
-            from all variables except from dimension coordinates.
+            or ``pint.Unit`` objects). If not provided, ``quantify``
+            will try to read them from ``Dataset[var].attrs['units']``
+            using pint's parser. The ``"units"`` attribute will be
+            removed from all variables except from dimension coordinates.
         unit_registry : pint.UnitRegistry, optional
             Unit registry to be used for the units attached to each
             DataArray in this Dataset. If not given then a default
@@ -922,6 +941,11 @@ def quantify(self, units=None, unit_registry=None, **unit_kwargs):
             Dataset whose variables will now contain Quantity arrays
             with units.
 
+        Notes
+        -----
+        ``"none"`` and ``None`` can be used to mark variables
+        that should not be quantified.
+
         Examples
         --------
         >>> ds = xr.Dataset(
@@ -947,21 +971,33 @@ def quantify(self, units=None, unit_registry=None, **unit_kwargs):
         Data variables:
             a        (x) int64 [m] 0 3 2
             b        (x) int64 [dm] 5 -2 1
+
+        Don't quantify specific variables:
+
+        >>> ds.pint.quantify({"a": None})
+        <xarray.Dataset>
+        Dimensions:  (x: 3)
+        Coordinates:
+          * x        (x) int64 0 1 2
+            u        (x) int64 [s] -1 0 1
+        Data variables:
+            a        (x) int64 0 3 2
+            b        (x) int64 5 -2 1
         """
         units = either_dict_or_kwargs(units, unit_kwargs, "quantify")
         registry = get_registry(unit_registry, units, conversion.extract_units(self.ds))
 
         unit_attrs = conversion.extract_unit_attributes(self.ds)
 
-        possible_new_units = zip_mappings(units, unit_attrs)
+        possible_new_units = zip_mappings(units, unit_attrs, fill_value=_default)
         new_units = {}
         invalid_units = {}
         for name, (unit, attr) in possible_new_units.items():
-            if unit is not None or attr is not None:
+            if unit is not _default or attr is not _default:
                 try:
                     new_units[name] = _decide_units(unit, registry, attr)
                 except (ValueError, pint.UndefinedUnitError) as e:
-                    if unit is not None:
+                    if unit is not _default:
                         type = "parameter"
                         reported_unit = unit
                     else:

pint_xarray/conversion.py

@@ -5,6 +5,7 @@
 
 from .errors import format_error_message
 
+no_unit_values = ("none", None)
 unit_attribute_name = "units"
 slice_attributes = ("start", "stop", "step")
 
@@ -23,8 +24,7 @@ def array_attach_units(data, unit):
     -------
     quantity : pint.Quantity
     """
-
-    if unit is None:
+    if unit in no_unit_values:
         return data
 
     if not isinstance(unit, pint.Unit):

pint_xarray/tests/test_accessors.py

@@ -65,10 +65,10 @@ def example_quantity_da():
 class TestQuantifyDataArray:
     def test_attach_units_from_str(self, example_unitless_da):
         orig = example_unitless_da
-        result = orig.pint.quantify("m")
+        result = orig.pint.quantify("s")
         assert_array_equal(result.data.magnitude, orig.data)
         # TODO better comparisons for when you can't access the unit_registry?
-        assert str(result.data.units) == "meter"
+        assert str(result.data.units) == "second"
 
     def test_attach_units_given_registry(self, example_unitless_da):
         orig = example_unitless_da
@@ -86,13 +86,30 @@ def test_attach_units_from_attrs(self, example_unitless_da):
         remaining_attrs = conversion.extract_unit_attributes(result)
         assert {k: v for k, v in remaining_attrs.items() if v is not None} == {}
 
+    def test_attach_units_from_str_attr_no_unit(self, example_unitless_da):
+        orig = example_unitless_da
+        orig.attrs["units"] = "none"
+        result = orig.pint.quantify("m")
+        assert_array_equal(result.data.magnitude, orig.data)
+        assert str(result.data.units) == "meter"
+
     def test_attach_units_given_unit_objs(self, example_unitless_da):
         orig = example_unitless_da
         ureg = UnitRegistry(force_ndarray=True)
         result = orig.pint.quantify(ureg.Unit("m"), unit_registry=ureg)
         assert_array_equal(result.data.magnitude, orig.data)
         assert result.data.units == ureg.Unit("m")
 
+    @pytest.mark.parametrize("no_unit_value", conversion.no_unit_values)
+    def test_override_units(self, example_unitless_da, no_unit_value):
+        orig = example_unitless_da
+        result = orig.pint.quantify(no_unit_value, u=no_unit_value)
+
+        with pytest.raises(AttributeError):
+            result.data.units
+        with pytest.raises(AttributeError):
+            result["u"].data.units
+
     def test_error_when_already_units(self, example_quantity_da):
         da = example_quantity_da
         with raises_regex(ValueError, "already has units"):
@@ -247,6 +264,21 @@ def test_attach_units_given_unit_objs(self, example_unitless_ds):
         assert_array_equal(result["users"].data.magnitude, orig["users"].data)
         assert str(result["users"].data.units) == "dimensionless"
 
+    def test_attach_units_from_str_attr_no_unit(self, example_unitless_ds):
+        orig = example_unitless_ds
+        orig["users"].attrs["units"] = "none"
+        result = orig.pint.quantify({"users": "m"})
+        assert_array_equal(result["users"].data.magnitude, orig["users"].data)
+        assert str(result["users"].data.units) == "meter"
+
+    @pytest.mark.parametrize("no_unit_value", conversion.no_unit_values)
+    def test_override_units(self, example_unitless_ds, no_unit_value):
+        orig = example_unitless_ds
+        result = orig.pint.quantify({"users": no_unit_value})
+        assert (
+            getattr(result["users"].data, "units", "not a quantity") == "not a quantity"
+        )
+
     def test_error_when_already_units(self, example_quantity_ds):
         with raises_regex(ValueError, "already has units"):
             example_quantity_ds.pint.quantify({"funds": "pounds"})