dev

Author: davidhassell

Changelog.rst

@@ -3,8 +3,9 @@ Version NEXTVERSION
 
 **2025-??-??**
 
-* New methods: `cf.Field.to_units`, `cf.Data.to_units`
-  (https://github.com/NCAS-CMS/cf-python/issues/???)
+* New methods to allow changing units in a chain: `cf.Field.to_units`,
+  `cf.Data.to_units`
+  (https://github.com/NCAS-CMS/cf-python/issues/874)
 
 ----
 

cf/data/data.py

@@ -5651,7 +5651,7 @@ def change_calendar(self, calendar, inplace=False, i=False):
     @_deprecated_kwarg_check("i", version="3.0.0", removed_at="4.0.0")
     @_inplace_enabled(default=False)
     def override_units(self, units, inplace=False, i=False):
-        """Override the data array units.
+        """Override the units.
 
         The new units need not be equivalent to the original ones, and
         the data array elements will not be changed to reflect the new
@@ -5711,10 +5711,9 @@ def override_calendar(self, calendar, inplace=False, i=False):
         it is known that the data array values are correct but the
         calendar has been incorrectly encoded.
 
-        Not to be confused with changing to equivalent units with the
-        `to_units` method or the `Units`, `units`, or `calendar`
-        attributes. These approaches also convert the data to have the
-        new units.
+        Not to be confused with changing to an equivalent calendar
+        with the `to_units` method or the `Units` or `calendar`
+        attributes.
 
         .. seealso:: `override_units`, `to_units`, `Units`, `units`,
                      `calendar`
@@ -7386,8 +7385,8 @@ def to_units(self, units, inplace=False):
         """Change the data array units.
 
         Changing the units will causes the data values to be changed
-        to match the new units, so the new units must be equivalent to
-        the existing ones.
+        to match the new units, therefore the new units must be
+        equivalent to the existing ones.
 
         Not to be confused with overriding the units with
         `override_units`

cf/mixin/propertiesdata.py

@@ -4436,8 +4436,8 @@ def to_units(self, units, inplace=False):
         """Change the data array units.
 
         Changing the units will causes the data values to be changed
-        to match the new units, so the new units must be equivalent to
-        the existing ones.
+        to match the new units, therefore the new units must be
+        equivalent to the existing ones.
 
         Not to be confused with overriding the units with
         `override_units`
@@ -5023,13 +5023,12 @@ def override_calendar(self, calendar, inplace=False, i=False):
         it is known that the data array values are correct but the
         calendar has been incorrectly encoded.
 
-        Not to be confused with changing to equivalent units with the
-        `to_units` method or the `Units`, `units`, or `calendar`
-        attributes. These approaches also convert the data to have the
-        new units.
+        Not to be confused with changing to an equivalent calendar
+        with the `to_units` method or the `Units` or `calendar`
+        attributes.
 
-        .. seealso:: `override_units`, `to_units`, `units`,
-                     `Units`,`calendar`
+        .. seealso:: `override_units`, `to_units`, `units`, `Units`,
+                     `calendar`
 
         :Parameters:
 
@@ -5081,7 +5080,7 @@ def override_calendar(self, calendar, inplace=False, i=False):
     @_deprecated_kwarg_check("i", version="3.0.0", removed_at="4.0.0")
     @_inplace_enabled(default=False)
     def override_units(self, units, inplace=False, i=False):
-        """Override the units. TODOUNITS
+        """Override the units.
 
         The new units need not be equivalent to the original ones, and
         the data array elements will not be changed to reflect the new

cf/mixin/propertiesdatabounds.py

@@ -2188,10 +2188,9 @@ def override_calendar(self, calendar, inplace=False, i=False):
         it is known that the data array values are correct but the
         calendar has been incorrectly encoded.
 
-        Not to be confused with changing to equivalent units with the
-        `to_units` method or the `Units`, `units`, or `calendar`
-        attributes. These approaches also convert the data to have the
-        new units.
+        Not to be confused with changing to an equivalent calendar
+        with the `to_units` method or the `Units` or `calendar`
+        attributes.
 
         .. seealso:: `override_units`, `to_units`, `Units`, `units`,
                      `calendar`
@@ -3326,8 +3325,8 @@ def to_units(self, units, inplace=False):
         """Change the data array units.
 
         Changing the units will causes the data values to be changed
-        to match the new units, so the new units must be equivalent to
-        the existing ones.
+        to match the new units, therefore the new units must be
+        equivalent to the existing ones.
 
         Not to be confused with overriding the units with
         `override_units`
@@ -3352,20 +3351,22 @@ def to_units(self, units, inplace=False):
 
         **Examples**
 
-        >>> f.Units TODOUNITS
-        <Units: hPa>
-        >>> f.datum(0)
-        100000.0
-        >>> f.override_units('km')
-        >>> f.Units
-        <Units: km>
-        >>> f.datum(0)
-        100000.0
-        >>> f.override_units(Units('watts'))
-        >>> f.Units
-        <Units: watts>
-        >>> f.datum(0)
-        100000.0
+        >>> print(f.Units)
+        'km'
+        >>> print(f.array)
+        [1 2]
+        >>> g = f.to_units('metre')
+        >>> print(g.Units)
+        'metre'
+        >>> print(g.array)
+        [1000. 2000.]
+        >>> g.to_units('miles', inplace=True)
+        >>> print(g.array)
+        [0.62137119 1.24274238]
+        >>> g.to_units('degC')
+        Traceback (most recent call last)
+            ...
+        ValueError: Can't set Units to <Units: degC> that are not equivalent to the current units <Units: miles>. Consider using the override_units method instead.
 
         """
         return self._apply_superclass_data_oper(