cf.FieldAncillary.to_units

FieldAncillary.to_units(*args, **kwargs)

Change the data array units.

Changing the units causes the data values to be changed 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

Added in version 3.18.1.

See also

override_units, override_calendar, Units, units, calendar

Parameters:

units: str or Units

The new units for the data array.

inplace: bool, optional

If True then do the operation in-place and return None.

Returns:

FieldAncillary or None

The construct with data converted to the new units, or None if the operation was in-place.

Examples

>>> 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.