Logo Iris 1.12

Previous topic

iris.time

Next topic

iris.util

This Page

iris.unit

Deprecated since version 1.9: This module has been deprecated. Please use cf_units instead.

Units of measure.

Provision of a wrapper class to support Unidata/UCAR UDUNITS-2, and the netcdftime calendar functionality.

See also: UDUNITS-2.

In this module:

A class to represent S.I. units and support common operations to manipulate such units in a consistent manner as per UDUNITS-2.

These operations include scaling the unit, offsetting the unit by a constant or time, inverting the unit, raising the unit by a power, taking a root of the unit, taking a log of the unit, multiplying the unit by a constant or another unit, dividing the unit by a constant or another unit, comparing units, copying units and converting unit data to single precision or double precision floating point numbers.

This class also supports time and calendar defintion and manipulation.

class iris.unit.Unit(unit, calendar=None)

Bases: iris.util._OrderedHashable

Create a wrapper instance for UDUNITS-2.

An optional calendar may be provided for a unit which defines a time reference of the form ‘<time-unit> since <time-origin>’ i.e. unit=’days since 1970-01-01 00:00:00’. For a unit that is a time reference, the default calendar is ‘standard’.

Accepted calendars are as follows,

  • ‘standard’ or ‘gregorian’ - Mixed Gregorian/Julian calendar as defined by udunits.

  • ‘proleptic_gregorian’ - A Gregorian calendar extended to dates before 1582-10-15. A year is a leap year if either,

    1. It is divisible by 4 but not by 100, or
    2. It is divisible by 400.
  • ‘noleap’ or ‘365_day’ - A Gregorian calendar without leap years i.e. all years are 365 days long.

  • ‘all_leap’ or ‘366_day’ - A Gregorian calendar with every year being a leap year i.e. all years are 366 days long.

  • ‘360_day’ - All years are 360 days divided into 30 day months.

  • ‘julian’ - Proleptic Julian calendar, extended to dates after 1582-10-5. A year is a leap year if it is divisible by 4.

Args:

  • unit:

    Specify the unit as defined by UDUNITS-2.

  • calendar (string):

    Describes the calendar used in time calculations. The default is ‘standard’ or ‘gregorian’ for a time reference unit.

Returns:

Unit object.

Units should be set to “no_unit” for values which are strings. Units can also be set to “unknown” (or None). For example:

>>> from cf_units import Unit
>>> volts = Unit('volts')
>>> no_unit = Unit('no_unit')
>>> unknown = Unit('unknown')
>>> unknown = Unit(None)
convert(value, other, ctype=<class 'ctypes.c_double'>)

Converts a single value or numpy array of values from the current unit to the other target unit.

If the units are not convertible, then no conversion will take place.

Args:

  • value (int/float/numpy.ndarray):

    Value/s to be converted.

  • other (string/Unit):

    Target unit to convert to.

  • ctype (ctypes.c_float/ctypes.c_double):

    Floating point 32-bit single-precision (cf_units.FLOAT32) or 64-bit double-precision (cf_units.FLOAT64) used for conversion when value is not a NumPy array or is a NumPy array composed of NumPy integers. The default is 64-bit double-precision conversion.

Returns:
float or numpy.ndarray of appropriate float type.

For example:

>>> import cf_units as unit
>>> import numpy as np
>>> c = unit.Unit('deg_c')
>>> f = unit.Unit('deg_f')
>>> c.convert(0, f)
31.999999999999886
>>> c.convert(0, f, unit.FLOAT32)
32.0
>>> a64 = np.arange(10, dtype=np.float64)
>>> c.convert(a64, f)
array([ 32. ,  33.8,  35.6,  37.4,  39.2,  41. ,  42.8,  44.6,  46.4,  48.2])
>>> a32 = np.arange(10, dtype=np.float32)
>>> c.convert(a32, f)
array([ 32.        ,  33.79999924,  35.59999847,  37.40000153,
        39.20000076,  41.        ,  42.79999924,  44.59999847,
        46.40000153,  48.20000076], dtype=float32)

Note

Conversion between unit calendars is not permitted.

date2num(date)

Returns the numeric time value calculated from the datetime object using the current calendar and unit time reference.

The current unit time reference must be of the form: ‘<time-unit> since <time-origin>’ i.e. ‘hours since 1970-01-01 00:00:00’

Works for scalars, sequences and numpy arrays. Returns a scalar if input is a scalar, else returns a numpy array.

Args:

  • date (datetime):

    A datetime object or a sequence of datetime objects. The datetime objects should not include a time-zone offset.

Returns:
float or numpy.ndarray of float.
format(option=None)

Return a formatted string representation of the binary unit.

Args:

  • option (cf_units.UT_FORMATS):

    Set the encoding option of the formatted string representation. Valid encoding options may be one of the following enumerations:

    • Unit.UT_ASCII
    • Unit.UT_ISO_8859_1
    • Unit.UT_LATIN1
    • Unit.UT_UTF8
    • Unit.UT_NAMES
    • Unit.UT_DEFINITION

    Multiple options may be combined within a list. The default option is cf_units.UT_ASCII.

Returns:
string.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('meters')
>>> u.format()
'm'
>>> u.format(unit.UT_NAMES)
'meter'
>>> u.format(unit.UT_DEFINITION)
'm'
invert()

Invert the unit i.e. find the reciprocal of the unit, and return the Unit result.

Returns:
Unit.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('meters')
>>> u.invert()
Unit('meter^-1')
is_convertible(other)

Return whether two units are convertible.

Args:

  • other (Unit): Unit to be compared.
Returns:
Boolean.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('meters')
>>> v = unit.Unit('kilometers')
>>> u.is_convertible(v)
True
is_dimensionless()

Return whether the unit is dimensionless.

Returns:
Boolean.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('meters')
>>> u.is_dimensionless()
False
>>> u = unit.Unit('1')
>>> u.is_dimensionless()
True
is_no_unit()

Return whether the unit is defined to be a no_unit unit.

Typically, a quantity such as a string, will have no associated unit to describe it. Such a class of quantity may be defined using the no_unit unit.

Returns:
Boolean.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('no unit')
>>> u.is_no_unit()
True
>>> u = unit.Unit('meters')
>>> u.is_no_unit()
False
is_time()

Determine whether this unit is a related SI Unit of time.

Returns:
Boolean.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('hours')
>>> u.is_time()
True
>>> v = unit.Unit('meter')
>>> v.is_time()
False
is_time_reference()

Return whether the unit is a time reference unit of the form ‘<time-unit> since <time-origin>’ i.e. unit=’days since 1970-01-01 00:00:00’

Returns:
Boolean.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('days since epoch')
>>> u.is_time_reference()
True
is_udunits()

Return whether the unit is a vaild unit of UDUNITS.

is_unknown()

Return whether the unit is defined to be an unknown unit.

Returns:
Boolean.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('unknown')
>>> u.is_unknown()
True
>>> u = unit.Unit('meters')
>>> u.is_unknown()
False
is_vertical()

Determine whether the unit is a related SI Unit of pressure or distance.

Returns:
Boolean.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('millibar')
>>> u.is_vertical()
True
>>> v = unit.Unit('km')
>>> v.is_vertical()
True
log(base)

Returns the logorithmic unit corresponding to the given logorithmic base.

Args:

  • base (int/float): Value of the logorithmic base.
Returns:
None.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('meters')
>>> u.log(2)
Unit('lb(re 1 meter)')
num2date(time_value)

Returns a datetime-like object calculated from the numeric time value using the current calendar and the unit time reference.

The current unit time reference must be of the form: ‘<time-unit> since <time-origin>’ i.e. ‘hours since 1970-01-01 00:00:00’

The datetime objects returned are ‘real’ Python datetime objects if the date falls in the Gregorian calendar (i.e. the calendar is ‘standard’, ‘gregorian’, or ‘proleptic_gregorian’ and the date is after 1582-10-15). Otherwise a ‘phoney’ datetime-like object (netcdftime.datetime) is returned which can handle dates that don’t exist in the Proleptic Gregorian calendar.

Works for scalars, sequences and numpy arrays. Returns a scalar if input is a scalar, else returns a numpy array.

Args:

  • time_value (float): Numeric time value/s. Maximum resolution is 1 second.
Returns:
datetime, or numpy.ndarray of datetime object.
offset_by_time(origin)

Returns the time unit offset with respect to the time origin.

Args:

  • origin (float): Time origin as returned by the cf_units.encode_time() method.
Returns:
None.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('hours')
>>> u.offset_by_time(unit.encode_time(1970, 1, 1, 0, 0, 0))
Unit('hour since 1970-01-01 00:00:00.0000000 UTC')
root(root)

Returns the given root of the unit.

Args:

  • root (int): Value by which the unit root is taken.
Returns:
None.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('meters^2')
>>> u.root(2)
Unit('meter')

Note

Taking a fractional root of a unit is not supported.

title(value)

Return the unit value as a title string.

Args:

  • value (float): Unit value to be incorporated into title string.
Returns:
string.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('hours since epoch',
...               calendar=unit.CALENDAR_STANDARD)
>>> u.title(10)
'1970-01-01 10:00:00'
utime()

Returns a netcdftime.utime object which performs conversions of numeric time values to/from datetime objects given the current calendar and unit time reference.

The current unit time reference must be of the form: ‘<time-unit> since <time-origin>’ i.e. ‘hours since 1970-01-01 00:00:00’

Returns:
netcdftime.utime.
calendar = None

Represents the unit calendar name, see cf_units.CALENDARS

category = None

Is this an unknown unit, a no-unit, or a UDUNITS-2 unit.

definition

(read-only) The symbolic decomposition of the unit.

Formats the binary unit into a string representation using method cf_units.Unit.format() with keyword argument option=cf_units.UT_DEFINITION.

Returns:
string.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('watts')
>>> u.definition
'm2.kg.s-3'
modulus

(read-only) Return the modulus value of the unit.

Convenience method that returns the unit modulus value as follows,
  • ‘radians’ - pi*2
  • ‘degrees’ - 360.0
  • Otherwise None.
Returns:
float.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('degrees')
>>> u.modulus
360.0
name

(read-only) The full name of the unit.

Formats the binary unit into a string representation using method cf_units.Unit.format() with keyword argument option=cf_units.UT_NAMES.

Returns:
string.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('watts')
>>> u.name
'watt'
origin = None

The original string used to create this unit.

symbol

(read-only) The symbolic representation of the unit.

Formats the binary unit into a string representation using method cf_units.Unit.format().

Returns:
string.

For example:

>>> import cf_units as unit
>>> u = unit.Unit('watts')
>>> u.symbol
'W'
ut_unit = None

Reference to the ctypes quantity defining the UDUNITS-2 unit.

↑ top ↑

iris.unit.date2num(date, unit, calendar)

Return numeric time value (resolution of 1 second) encoding of datetime object.

The units of the numeric time values are described by the unit and calendar arguments. The datetime objects must be in UTC with no time-zone offset. If there is a time-zone offset in unit, it will be applied to the returned numeric values.

Like the matplotlib.dates.date2num() function, except that it allows for different units and calendars. Behaves the same as if unit = ‘days since 0001-01-01 00:00:00’ and calendar = ‘proleptic_gregorian’.

Args:

  • date (datetime):

    A datetime object or a sequence of datetime objects. The datetime objects should not include a time-zone offset.

  • unit (string):

    A string of the form ‘<time-unit> since <time-origin>’ describing the time units. The <time-unit> can be days, hours, minutes or seconds. The <time-origin> is a date/time reference point. A valid choice would be unit=’hours since 1800-01-01 00:00:00 -6:00’.

  • calendar (string):

    Name of the calendar, see cf_units.CALENDARS.

Returns:
float, or numpy.ndarray of float.

For example:

>>> import cf_units as unit
>>> import datetime
>>> dt1 = datetime.datetime(1970, 1, 1, 6, 0, 0)
>>> dt2 = datetime.datetime(1970, 1, 1, 7, 0, 0)
>>> unit.date2num(dt1, 'hours since 1970-01-01 00:00:00',
...               unit.CALENDAR_STANDARD)
6.0
>>> unit.date2num([dt1, dt2], 'hours since 1970-01-01 00:00:00',
...               unit.CALENDAR_STANDARD)
array([ 6.,  7.])

↑ top ↑

iris.unit.decode_time(time)

Decode a double precision date/clock time value into its component parts and return as tuple.

Decode time into it’s year, month, day, hour, minute, second, and resolution component parts. Where resolution is the uncertainty of the time in seconds.

Args:

  • time (float): Date/clock time encoded as a double precision value.
Returns:
tuple of (year, month, day, hour, minute, second, resolution).

For example:

>>> import cf_units as unit
>>> unit.decode_time(unit.encode_time(1970, 1, 1, 0, 0, 0))
(1970, 1, 1, 0, 0, 0.0, 1.086139178596568e-07)

↑ top ↑

iris.unit.encode_clock(hour, minute, second)

Return clock time encoded as a double precision value.

Args:

  • hour (int):

    Hour value to be encoded.

  • minute (int):

    Minute value to be encoded.

  • second (int):

    Second value to be encoded.

Returns:
float.

For example:

>>> import cf_units as unit
>>> unit.encode_clock(0, 0, 0)
0.0

↑ top ↑

iris.unit.encode_date(year, month, day)

Return date encoded as a double precision value.

Encoding performed using UDUNITS-2 hybrid Gergorian/Julian calendar. Dates on or after 1582-10-15 are assumed to be Gregorian dates; dates before that are assumed to be Julian dates. In particular, the year 1 BCE is immediately followed by the year 1 CE.

Args:

  • year (int):

    Year value to be encoded.

  • month (int):

    Month value to be encoded.

  • day (int):

    Day value to be encoded.

Returns:
float.

For example:

>>> import cf_units as unit
>>> unit.encode_date(1970, 1, 1)
-978307200.0

↑ top ↑

iris.unit.encode_time(year, month, day, hour, minute, second)

Return date/clock time encoded as a double precision value.

Encoding performed using UDUNITS-2 hybrid Gregorian/Julian calendar. Dates on or after 1582-10-15 are assumed to be Gregorian dates; dates before that are assumed to be Julian dates. In particular, the year 1 BCE is immediately followed by the year 1 CE.

Args:

  • year (int):

    Year value to be encoded.

  • month (int):

    Month value to be encoded.

  • day (int):

    Day value to be encoded.

  • hour (int):

    Hour value to be encoded.

  • minute (int):

    Minute value to be encoded.

  • second (int):

    Second value to be encoded.

Returns:
float.

For example:

>>> import cf_units as unit
>>> unit.encode_time(1970, 1, 1, 0, 0, 0)
-978307200.0

↑ top ↑

iris.unit.num2date(time_value, unit, calendar)

Return datetime encoding of numeric time value (resolution of 1 second).

The units of the numeric time value are described by the unit and calendar arguments. The returned datetime object represent UTC with no time-zone offset, even if the specified unit contain a time-zone offset.

Like the matplotlib.dates.num2date() function, except that it allows for different units and calendars. Behaves the same if unit = ‘days since 001-01-01 00:00:00’} calendar = ‘proleptic_gregorian’.

The datetime instances returned are ‘real’ python datetime objects if the date falls in the Gregorian calendar (i.e. calendar=’proleptic_gregorian’, or calendar = ‘standard’ or ‘gregorian’ and the date is after 1582-10-15). Otherwise, they are ‘phony’ datetime objects which support some but not all the methods of ‘real’ python datetime objects. This is because the python datetime module cannot use the ‘proleptic_gregorian’ calendar, even before the switch occured from the Julian calendar in 1582. The datetime instances do not contain a time-zone offset, even if the specified unit contains one.

Args:

  • time_value (float):

    Numeric time value/s. Maximum resolution is 1 second.

  • unit (sting):

    A string of the form ‘<time-unit> since <time-origin>’ describing the time units. The <time-unit> can be days, hours, minutes or seconds. The <time-origin> is the date/time reference point. A valid choice would be unit=’hours since 1800-01-01 00:00:00 -6:00’.

  • calendar (string):

    Name of the calendar, see cf_units.CALENDARS.

Returns:
datetime, or numpy.ndarray of datetime object.

For example:

>>> import cf_units as unit
>>> import datetime
>>> unit.num2date(6, 'hours since 1970-01-01 00:00:00',
...               unit.CALENDAR_STANDARD)
datetime.datetime(1970, 1, 1, 6, 0)
>>> unit.num2date([6, 7], 'hours since 1970-01-01 00:00:00',
...               unit.CALENDAR_STANDARD)
array([datetime.datetime(1970, 1, 1, 6, 0),
       datetime.datetime(1970, 1, 1, 7, 0)], dtype=object)