# Units handling by the `cf.Units` object

A field (as well as any other object which inherits from `cf.Variable`) always contains a `cf.Units` object which gives the physical units of the values contained in its data array.

The `cf.Units` object is stored in the field’s `Units` attribute but may also be accessed through the field’s `units` and `calendar` CF properties, which may take any value allowed by the CF conventions. In particular, the value of the `units` CF property is a string that can be recognized by UNIDATA’s Udunits-2 package, with a few exceptions for greater consistency with CF. These are detailed by the `cf.Units` object.

## Assignment

The Field’s units may be assigned directly to its `cf.Units` object:

    >>> f.Units.units = 'days since 1-1-1'
    >>> f.Units.calendar = 'noleap'

    >>> f.Units = cf.Units('metre')

But the same result is achieved by assigning to the field’s `units` and `calendar` CF properties:

    >>> f.units = 'days since 1-1-1'
    >>> f.calendar = 'noleap'
    >>> f.Units
    <CF Units: days since 1-1-1 calendar=noleap>
    >>> f.units
    'days since 1-1-1'
    >>> f.calendar
    'noleap'

## Time units

Time units may be given as durations of time or as an amount of time since a reference time:

    >>> f.units = 'day'
    >>> f.units = 'seconds since 1992-10-8 15:15:42.5 -6:00'

Note

It is recommended that the units `'year'` and `'month'` be used with caution, as explained in the following excerpt from the CF conventions: “The Udunits package defines a year to be exactly 365.242198781 days (the interval between 2 successive passages of the sun through vernal equinox). It is not a calendar year. Udunits includes the following definitions for years: a common_year is 365 days, a leap_year is 366 days, a Julian_year is 365.25 days, and a Gregorian_year is 365.2425 days. For similar reasons the unit `'month'`, which is defined to be exactly year/12, should also be used with caution.”

### Calendar

The date given in reference time units is always associated with one of the calendars recognized by the CF conventions and may be set with the calendar CF property (on the field or Units object).

If the calendar is not set then, as in the CF conventions, for the purposes of calculation and comparison, it defaults to the mixed Gregorian/Julian calendar as defined by Udunits:

    >>> f.units = 'days since 2000-1-1'
    >>> f.calendar
    AttributeError: Can't get 'Field' attribute 'calendar'
    >>> g.units = 'days since 2000-1-1'
    >>> g.calendar = 'gregorian'
    >>> g.Units.equals(f.Units)
    True

The calendar is ignored for units other than reference time units.

## Changing units

Changing units to equivalent units causes the variable’s data array values to be modified in place (if required) when they are next accessed, and not before:

    >>> f.units
    'metre'
    >>> f.array
    array([    0.,  1000.,  2000.,  3000.,  4000.])
    >>> f.units = 'kilometre'
    >>> f.units
    'kilometre'
    >>> f.array
    array([ 0.,  1.,  2.,  3.,  4.])

    >>> f.units
    'hours since 2000-1-1'
    >>> f.array
    array([-1227192., -1227168., -1227144.])
    >>> f.units = 'days since 1860-1-1'
    >>> f.array
    array([ 1.,  2.,  3.])

The `cf.Units` object may be operated on with augmented arithmetic assignments and binary arithmetic operations:

    >>> f.units
    'kelvin'
    >>> f.array
    array([ 273.15,  274.15,  275.15,  276.15,  277.15])

    >>> f.Units -= 273.15
    >>> f.units
    'K @ 273.15'
    >>> f.array
    array([ 0.,  1.,  2.,  3.,  4.])

    >>> f.Units = f.Units + 273.15
    >>> f.units
    'K'
    >>> f.array
    array([ 273.15,  274.15,  275.15,  276.15,  277.15])

    >>> f.units = 'K @ 237.15'
    'K @ 273.15'
    >>> f.array
    array([ 0.,  1.,  2.,  3.,  4.])

If the field has a data array and its units are changed to non-equivalent units then a `TypeError` will be raised when the data are next accessed:

    >>> f.units
    'm s-1'
    >>> f.units = 'K'
    >>> f.array
    TypeError: Units are not convertible: <CF Units: m s-1>, <CF Units: K>

### Overriding units

If the units are incorrect, either due to a data manipulation or an incorrect encoding, it is possible to replace the existing units with new units, which don’t have to be equivalent, without altering the data values:

    >>> f.units
    'mm/day'
    >>> f.mean()
    <CF Data: 3.3455467 mm/day>
    >>> g = f.override_units('kg m-2 s-1')
    >>> g.mean()
    <CF Data: 3.3455467 kg m-2 s-1>
    >>> g.override_units('watts m-2', i=True)
    >>> g.mean()
    <CF Data: 3.3455467 watts m-2>

Overriding the calendar of reference time units is done in a similar manner:

    >>> f.calendar
    '360_day'
    >>> f.array.min()
    59.0
    >>> f.min()
    <CF Data: 1960-02-30 00:00:00 360_day>
    >>> g = f.override_calandar('gregorian')
    >>> g.array.min()
    59.0
    >>> g.min()
    <CF Data: 1960-02-29 00:00:00 gregorian>

Note that in this case the data values have remained unchanged, but their date-time interpretation has been redefined.

See `cf.Field.override_units` and `cf.Field.override_calendar` for details.

## Equality and equivalence of units

The `cf.Units` object has methods for assessing whether two units are equivalent or equal, regardless of their exact string representations.

Two units are equivalent if and only if numeric values in one unit are convertible to numeric values in the other unit (such as `'kilometres'` and `'metres'`). Two units are equal if and only if they are equivalent and their conversion is a scale factor of 1 (such as `'kilometres'` and `'1000 metres'`). Note that equivalence and equality are based on internally stored binary representations of the units, rather than their string representations.

    >>> f.units = 'm/s'

    >>> g.units = 'm s-1'
    >>> f.Units == g.Units
    True
    >>> f.Units.equals(g.Units)
    True

    >>> g.units = 'km s-1'
    >>> f.Units.equivalent(g.Units)
    False

    >>> f.units = 'days since 1987-12-3'
    >>> g.units = 'hours since 2000-12-1'
    >>> f.Units == g.Units
    False
    >>> f.Units.equivalent(g.Units)
    True

## Coordinate units

The units of a coordinate’s bounds are always the same as the coordinate itself, and the units of the bounds automatically change when a coordinate’s units are changed:

    >>> c.units
    'degrees'
    >>> c.bounds.units
    'degrees'
    >>> c.bounds.array
    array([  0.,  90.])
    >>> c.units = 'radians'
    >>> c.bounds.units
    'radians'
    >>> c.bounds.array
    array([ 0.        ,  1.57079633])