class cf.TimeDuration(duration, units=None, month=1, day=1, hour=0, minute=0, second=0)[source]

Bases: object

A duration of time.

The duration of time is a number of either calendar years, calender months, days, hours, minutes or seconds.

A calendar year (or month) is an arbitrary year (or month) in an arbitrary calendar. A calendar is as part of the time duration, but will be taken from the context in which the time duration instance is being used. For example, a calendar may be specified when creating time intervals (see below for examples).

A default offset is specified that may be used by some applications to temporally position the time duration. For example, setting cf.TimeDuration(1, 'calendar_month', day=16, hour=12) will define a duration of one calendar month which, by default, starts at 12:00 on the 16th of the month. Note that the offset

Changing the units

The time duration’s units may be changed in place by assigning equivalent units to the Units attribute:

>>> t = cf.TimeDuration(1, 'day')
>>> t
<CF TimeDuration: P1D (Y-M-D 00:00:00)>
>>> t.Units = 's' 
>>> t
<CF TimeDuration: PT86400.0S (Y-M-D 00:00:00)>
>>> t.Units = cf.Units('minutes')
>>> t
<CF TimeDuration: PT1440.0M (Y-M-D 00:00:00)>
>>> t.Units = 'calendar_months'
ValueError: Can't set units (currently <Units: minutes>) to non-equivalent units <Units: calendar_months>

Creating time intervals

A time interval of exactly the time duration, starting or ending at a particular date-time, may be produced with the interval method. If elements of the start or end date-time are not specified, then default values are taken from the year, month, day, hour, minute, and second attributes of the time duration instance:

>>> t = cf.TimeDuration(6, 'calendar_months')
>>> t
<CF TimeDuration: P6M (Y-M-01 00:00:00)>
>>> t.interval(cf.dt(1999, 12))                                              
(cftime.DatetimeGregorian(1999-12-01 00:00:00),
 cftime.DatetimeGregorian(2000-06-01 00:00:00))
>>> t = cf.TimeDuration(5, 'days', hour=6)
>>> t
<CF TimeDuration: P5D (Y-M-D 06:00:00)>
>>> t.interval(cf.dt(2004, 3, 2), end=True)
(cftime.DatetimeGregorian(2004-02-26 00:00:00),
 cftime.DatetimeGregorian(2004-03-02 00:00:00))
>>> t.interval(cf.dt(2004, 3, 2, calendar='noleap'), end=True)
(cftime.DatetimeNoLeap(2004-02-25 00:00:00),
 cftime.DatetimeNoLeap(2004-03-02 00:00:00))
>>> t.interval(cf.dt(2004, 3, 2, calendar='360_day'), end=True)
(cftime.Datetime360Day(2004-02-27 00:00:00),
 cftime.Datetime360Day(2004-03-02 00:00:00))
>>> t.interval(cf.dt(2004, 3, 2, calendar='360_day'), end=True, iso='start and duration')
'2004-02-27 00:00:00/P5D'

Comparison operations

Comparison operations are defined for cf.TimeDuration objects, ``cf.Data` objects, numpy arrays and numbers:

>>> cf.TimeDuration(2, 'calendar_years') > cf.TimeDuration(1, 'calendar_years')
>>> cf.TimeDuration(2, 'calendar_years') < cf.TimeDuration(25, 'calendar_months')
>>> cf.TimeDuration(2, 'hours') <= cf.TimeDuration(1, 'days')
>>> cf.TimeDuration(2, 'hours') == cf.TimeDuration(1/12.0, 'days')
>>> cf.TimeDuration(2, 'days') == cf.TimeDuration(48, 'hours')
>>> cf.TimeDuration(2, 'hours') <= 2
>>> 30.5 != cf.TimeDuration(2, 'days')
>>> cf.TimeDuration(2, 'calendar_years') > numpy.array(1.5)
>>> type(cf.TimeDuration(2, 'calendar_years') > numpy.array(1.5))
>>> cf.TimeDuration(2, 'calendar_years') > numpy.array([1.5])
array([ True])
>>> numpy.array([[1, 12]]) > cf.TimeDuration(2, 'calendar_months')
array([[False,  True]])
>>> cf.TimeDuration(2, 'days') == cf.Data(2)
<CF Data(): True>
>>> cf.TimeDuration(2, 'days') == cf.Data([2.], 'days')
<CF Data(1): [True]>
>>> cf.Data([[60]], 'seconds') < cf.TimeDuration(2, 'days')
<CF Data(1, 1): [[True]]>
>>> cf.Data([1, 12], 'calendar_months') < cf.TimeDuration(6, 'calendar_months')
<CF Data(2): [True, False]>

Arithmetic operations

Arithmetic operations are defined for cf.TimeDuration objects, date-time-like objects (such as cf.Datetime, datetime.datetime, etc.), ``cf.Data` objects, numpy arrays and numbers:

>>> cf.TimeDuration(64, 'days') + cf.TimeDuration(28, 'days')
<CF TimeDuration: P92D (Y-M-D 00:00:00)>
>>> cf.TimeDuration(64, 'days') + cf.TimeDuration(12, 'hours')
<CF TimeDuration: P65.0D (Y-M-D 00:00:00)>
>>> cf.TimeDuration(64, 'days') + cf.TimeDuration(24, 'hours')
<CF TimeDuration: P64.5D (Y-M-D 00:00:00)>
>>> cf.TimeDuration(64, 'calendar_years') + cf.TimeDuration(21, 'calendar_months')
<CF TimeDuration: P65.75Y (Y-01-01 00:00:00)>
>>> cf.TimeDuration(30, 'days') + 2
<CF TimeDuration: P32D (Y-M-D 00:00:00)>
>>> 4.5 + cf.TimeDuration(30, 'days')
<CF TimeDuration: P34.5D (Y-M-D 00:00:00)>
>>> cf.TimeDuration(64, 'calendar_years') - 2.5
<CF TimeDuration: P61.5Y (Y-01-01 00:00:00)>
>>> cf.TimeDuration(36, 'hours') / numpy.array(8)
<CF TimeDuration: 4.5 hours (from Y-M-D h:00:00)>
>>> cf.TimeDuration(36, 'hours') / numpy.array(8.0)
<CF TimeDuration: 4.5 hours (from Y-M-D h:00:00)>
>>> cf.TimeDuration(36, 'hours') // numpy.array(8.0)
<CF TimeDuration: 4.0 hours (from Y-M-D h:00:00)>
>>> cf.TimeDuration(36, 'calendar_months') * cf.Data([[2.25]])
<CF TimeDuration: 81.0 calendar_months (from Y-M-01 00:00:00)>
>>> cf.TimeDuration(36, 'calendar_months') // cf.Data([0.825])               
<CF TimeDuration: P43.0M (Y-01-01 00:00:00)>
>>> cf.TimeDuration(36, 'calendar_months') % 10
<CF TimeDuration: P6M (Y-01-01 00:00:00)>
>>> cf.TimeDuration(36, 'calendar_months') % cf.Data(1, 'calendar_year')
<CF TimeDuration: P0.0M (Y-01-01 00:00:00)>
>>> cf.TimeDuration(36, 'calendar_months') % cf.Data(2, 'calendar_year')
<CF TimeDuration: P12.0M (Y-01-01 00:00:00)>

The in place operators (+=, //=, etc.) are supported in a similar manner.


Attribute Description
duration The length of the time duration in a cf.Data object with units.
year The default year for time interval creation.
month The default month for time interval creation.
day The default day for time interval creation.
hour The default hour for time interval creation.
minute The default minute for time interval creation.
second The default second for time interval creation.


For convenience, the following functions may also be used to create time duration objects:

Function Description
cf.Y Create a time duration of calendar years.
cf.M Create a time duration of calendar months.
cf.D Create a time duration of days.
cf.h Create a time duration of hours.
cf.m Create a time duration of minutes.
cf.s Create a time duration of seconds.

See also

cf.dt, cf.Data, cf.Datetime

New in version 1.0.


duration: data-like

The length of the time duration.

A data-like object is any object containing array-like or scalar data which could be used to create a cf.Data object.

Parameter example:

Instances, x, of following types are all examples of data-like objects (because cf.Data(x) creates a valid cf.Data object), int, float, str, tuple, list, numpy.ndarray, cf.Data, cf.Coordinate, cf.Field.

units: str or cf.Units, optional

The units of the time duration. Required if, and only if, duration is not a cf.Data object which already contains the units. Units must be one of calendar years, calendar months, days, hours, minutes or seconds.

Parameter example:


Parameter example:


Parameter example:


month, day, hour, minute, second: int or None, optional

The offset used when creating, with the bounds method, a time interval containing a given date-time. Only the offset elements for units smaller that of the time duration are used.

Parameter example:
>>> cf.TimeDuration(1, 'calendar_month').bounds(cf.dt('2000-1-8'))
(cftime.DatetimeGregorian(2000-01-01 00:00:00),
 cftime.DatetimeGregorian(2000-02-01 00:00:00))
>>> cf.TimeDuration(1, 'calendar_month', day=15).bounds(cf.dt('2000-1-8'))
(cftime.DatetimeGregorian(1999-12-15 00:00:00),
 cftime.DatetimeGregorian(2000-01-15 00:00:00))
>>> cf.TimeDuration(1, 'calendar_month', month=4, day=30).bounds(cf.dt('2000-1-8'))
(cftime.DatetimeGregorian(1999-12-30 00:00:00),
 cftime.DatetimeGregorian(2000-01-30 00:00:00))


>>> t = cf.TimeDuration(cf.Data(3 , 'calendar_years'))
>>> t = cf.TimeDuration(cf.Data(12 , 'hours'))
>>> t = cf.TimeDuration(18 , 'calendar_months')
>>> t = cf.TimeDuration(30 , 'days')
>>> t = cf.TimeDuration(1 , 'day', hour=6)


Units The units of the time duration.
isint True if the time duration is a whole number.
iso Return the time duration as an ISO 8601-like time duration string.


bounds Return a time interval containing a date-time.
copy Return a deep copy.
days_in_month The number of days in a specific month in a specific year in a specific calendar.
equals True if two time durations are equal.
equivalent True if two time durations are logically equivalent.
inspect Inspect the attributes.
interval Return a time interval of exactly the time duration.
is_day_factor Return True if an integer multiple of the time duration is equal to one day.