cf.Units¶

class
cf.
Units
(units=None, calendar=None, formatted=False, names=False, definition=False, _ut_unit=None)[source]¶ Bases:
object
Store, combine and compare physical units and convert numeric values to different units.
Units are as defined in UNIDATA’s Udunits2 package, with a few exceptions for greater consistency with the CF conventions namely support for CF calendars and new units definitions.
Modifications to the standard Udunits database
Whilst a standard Udunits2 database may be used, greater consistency with CF is achieved by using a modified database. The following units are either new to, modified from, or removed from the standard Udunits2 database (version 2.1.24):
Unit name Symbol Definition Status practical_salinity_unit psu 1e3 New unit level 1 New unit sigma_level 1 New unit layer 1 New unit decibel dB 1 New unit bel 10 dB New unit sverdrup Sv 1e6 m3 s1 Added symbol sievert J kg1 Removed symbol Plural forms of the new units’ names are allowed, such as
practical_salinity_units
.The modified database is in the udunits subdirectory of the etc directory found in the same location as this module.
Accessing units
Units may be set, retrieved and deleted via the
units
attribute. Its value is a string that can be recognized by UNIDATA’s Udunits2 package, with the few exceptions given in the CF conventions.>>> u = Units('m s1') >>> u <Cf Units: 'm s1'> >>> u.units = 'days since 200431' >>> u <CF Units: days since 200431>
Equality and equivalence of units
There are methods for assessing whether two units are equivalent or equal. Two units are equivalent if numeric values in one unit are convertible to numeric values in the other unit (such as
kilometres
andmetres
). Two units are equal if they are equivalent and their conversion is a scale factor of 1 and an offset of 0 (such askilometres
and1000 metres
). Note that equivalence and equality are based on internally stored binary representations of the units, rather than their string representations.>>> u = Units('m/s') >>> v = Units('m s1') >>> w = Units('km.s1') >>> x = Units('0.001 kilometer.second1') >>> y = Units('gram')
>>> u.equivalent(v), u.equals(v), u == v (True, True, True) >>> u.equivalent(w), u.equals(w) (True, False) >>> u.equivalent(x), u.equals(x) (True, True) >>> u.equivalent(y), u.equals(y) (False, False)
Time and reference time units
Time units may be given as durations of time (time units) or as an amount of time since a reference time (reference time units):
>>> v = Units() >>> v.units = 's' >>> v.units = 'day' >>> v.units = 'days since 19700101' >>> v.units = 'seconds since 1992108 15:15:42.5 6:00'
Note
It is recommended that the units
year
andmonth
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 unitmonth
, which is defined to be exactly year/12, should also be used with caution.”Calendar
The date given in reference time units is associated with one of the calendars recognized by the CF conventions and may be set with the
calendar
attribute. However, as in the CF conventions, if the calendar is not set then, for the purposes of calculation and comparison, it defaults to the mixed Gregorian/Julian calendar as defined by Udunits:>>> u = Units('days since 200011') >>> u.calendar AttributeError: Can't get 'Units' attribute 'calendar' >>> v = Units('days since 200011') >>> v.calendar = 'gregorian' >>> v.equals(u) True
Arithmetic with units
The following operators, operations and assignments are overloaded:
Comparison operators:
==, !=
Binary arithmetic operations:
+, , *, /, pow(), **
Unary arithmetic operations:
, +
Augmented arithmetic assignments:
+=, =, *=, /=, **=
The comparison operations return a boolean and all other operations return a new units object or modify the units object in place.
>>> u = Units('m') <CF Units: m>
>>> v = u * 1000 >>> v <CF Units: 1000 m>
>>> u == v False >>> u != v True
>>> u **= 2 >>> u <CF Units: m2>
It is also possible to create the logarithm of a unit corresponding to the given logarithmic base:
>>> u = Units('seconds') >>> u.log(10) <CF Units: lg(re 1 s)>
Modifying data for equivalent units
Any numpy array or python numeric type may be modified for equivalent units using the
conform
static method.>>> Units.conform(2, Units('km'), Units('m')) 2000.0
>>> import numpy >>> a = numpy.arange(5.0) >>> Units.conform(a, Units('minute'), Units('second')) array([ 0., 60., 120., 180., 240.]) >>> a array([ 0., 1., 2., 3., 4.])
If the inplace keyword is True, then a numpy array is modified in place, without any copying overheads:
>>> Units.conform(a, Units('days since 2000121'), Units('days since 200111'), inplace=True) array([31., 30., 29., 28., 27.]) >>> a array([31., 30., 29., 28., 27.])
Initialization
Parameters:  units:
str
orcf.Units
, optional Set the new units from this string.
 calendar:
str
, optional Set the calendar for reference time units.
 formatted:
bool
, optional Format the string representation of the units in a standardized manner. See the
formatted
method. names:
bool
, optional Format the string representation of the units using names instead of symbols. See the
format
method. definition:
bool
, optional Format the string representation of the units using basic units. See the
format
method. _ut_unit:
int
, optional Set the new units from this Udunits binary unit representation. This should be an integer returned by a call to
ut_parse
function of Udunits. Ignored ifunits
is set.
 units:
Attributes¶
calendar 
The calendar for reference time units. 
isdimensionless 
True if the units are dimensionless, false otherwise. 
islatitude 
True if and only if the units are latitude units. 
islongitude 
True if and only if the units are longitude units. 
ispressure 
True if the units are pressure units, false otherwise. 
isreftime 
True if the units are reference time units, False otherwise. 
istime 
True if the units are time units, False otherwise. 
reftime 
The reference datetime of reference time units. 
units 
The units. 
Methods¶
conform 
Conform values in one unit to equivalent values in another, compatible unit. 
copy 
Return a deep copy. 
dump 
Return a string containing a description of the units. 
equals 
Return True if and only if numeric values in one unit are convertible to numeric values in the other unit and their conversion is a scale factor of 1. 
equivalent 
Returns True if numeric values in one unit are convertible to numeric values in the other unit. 
formatted 
Formats the string stored in the units attribute in a standardized manner. 
log 
Return the logarithmic unit corresponding to the given logarithmic base. 