cf.TimeDuration

class cf.TimeDuration(duration, units=None, year=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.

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:

>>> t = cf.TimeDuration(6, 'calendar_months')
>>> t
<CF TimeDuration: 6 calendar_months (from Y-01-01 00:00:00)>
>>> t.interval(1999, 12)
(<CF Datetime: 1999-12-01 00:00:00>, <CF Datetime: 2000-06-01 00:00:00>)
>>> t = cf.TimeDuration(5, 'days', hour=6)
>>> t
<CF TimeDuration: 5 days (from Y-01-01 06:00:00)>
>>> t.interval(2004, 3, 2, end=True)
(datetime.datetime(2004, 2, 26, 6, 0), <CF Datetime: 2004-03-02 06:00:00>)
>>> t.interval(2004, 3, 2, end=True, calendar='noleap')
(<CF Datetime: 2004-02-25 06:00:00>, <CF Datetime: 2004-03-02 06:00:00>)
>>> t.interval(2004, 3, 2, end=True, calendar='360_day')
(<CF Datetime: 2004-02-27 06:00:00>, <CF Datetime: 2004-03-02 06:00:00>)
>>> t.interval(2004, 3, 2, end=True, calendar='360_day', iso='start and duration')
'2004-02-27 06:00:00/P5D'

Arithmetic and comparison operators

Arithmetic and 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')
True
>>> cf.TimeDuration(2, 'calendar_years') < cf.TimeDuration(25, 'calendar_months')
True
>>> cf.TimeDuration(2, 'hours') <= cf.TimeDuration(1, 'days')
True
>>> cf.TimeDuration(2, 'hours') == cf.TimeDuration(1/12.0, 'days')
True
>>> cf.TimeDuration(2, 'days') == cf.TimeDuration(48, 'hours')
True
>>> cf.TimeDuration(2, 'days') == cf.Data(2)
True
>>> cf.TimeDuration(2, 'days') == cf.Data([2.], 'days')
True
>>> cf.TimeDuration(2, 'days') > cf.Data([[60]], 'seconds')
True
>>> cf.TimeDuration(2, 'hours') <= 2
True
>>> cf.TimeDuration(2, 'days') != 30.5
True
>>> cf.TimeDuration(2, 'calendar_years') > numpy.array(1.5)
True
>>> cf.TimeDuration(2, 'calendar_months') < numpy.array([[12]])
True

>>> cf.TimeDuration(30, 'days') + 2
<CF TimeDuration: 32 days (from Y-01-01 00:00:00)>
>>> cf.TimeDuration(64, 'calendar_years') - 2.5
<CF TimeDuration: 61.5 calendar_years (from Y-01-01 00:00:00)>
>>> cf.TimeDuration(64, 'calendar_years') + cf.TimeDuration(23, 'calendar_months')
<CF TimeDuration: 65.9166666667 calendar_years (from Y-01-01 00:00:00)>
>>> cf.TimeDuration(36, 'hours') / numpy.array(8)
<CF TimeDuration: 4 hours (from Y-01-01 00:00:00)>
>>> cf.TimeDuration(36, 'hours') / numpy.array(8.0)
<CF TimeDuration: 4.5 hours (from Y-01-01 00:00:00)>
>>> cf.TimeDuration(36, 'hours') // numpy.array(8.0)
<CF TimeDuration: 4.0 hours (from Y-01-01 00:00:00)>
>>> cf.TimeDuration(36, 'calendar_months') * cf.Data([[2.25]])
<CF TimeDuration: 81.0 calendar_months (from Y-01-01 00:00:00)>
>>> cf.TimeDuration(36, 'calendar_months') // cf.Data([0.825], '10')
<CF TimeDuration: 4.3 calendar_months (from Y-01-01 00:00:00)>
>>> cf.TimeDuration(36, 'calendar_months') % 10
<CF Data: 6 calendar_months>
>>> cf.TimeDuration(36, 'calendar_months') % cf.Data(1, 'calendar_year')
<CF Data: 0.0 calendar_months>
>>> cf.TimeDuration(36, 'calendar_months') % cf.Data(2, 'calendar_year')
<CF Data: 12.0 calendar_months>

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

Attributes

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.

Constructors

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.Data, cf.Datetime

New in version 1.0.

Initialization

Parameters:
duration: data-like

The length of the time duration.

units: str, optional

The units of the time duration. Only required if duration is not a cf.Data object which contains the units. Must be a units string equivalent to calendar years, calendar months, days, hours, minutes or seconds.

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

The default date-time elements for defining when a time interval based on this time duration (created with the interval method) begins or ends. See cf.TimeDuration.interval for details.
Examples: 
>>> 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)
__init__(duration, units=None, year=None, month=1, day=1, hour=0, minute=0, second=0)[source]

Initialization

Parameters:
duration: data-like

The length of the time duration.

units: str, optional

The units of the time duration. Only required if duration is not a cf.Data object which contains the units. Must be a units string equivalent to calendar years, calendar months, days, hours, minutes or seconds.

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

The default date-time elements for defining when a time interval based on this time duration (created with the interval method) begins or ends. See cf.TimeDuration.interval for details.
Examples: 
>>> 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)

Methods

__init__(duration[, units, year, month, ...]) Initialization
copy() Return a deep copy.
equals(other[, rtol, atol, traceback]) True if two time durations are equal.
equivalent(other[, rtol, atol, traceback]) True if two time durations are logically equivalent.
inspect() Inspect the attributes.
interval([year, month, day, hour, minute, ...]) 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.

Attributes

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 time duration string.
bounds(year=None, month=1, day=1, hour=0, minute=0, second=0, calendar=None, direction=True)[source]

See also

interval

New in version 1.2.3.

Examples 1: 
>>>
Parameters:
direction: bool, optional

If False then the bounds are decreasing. By default the bounds are increasing. Note that t.bounds(*args, **kwargs, direction=False) is equivalent to t.bounds(*args, **kwargs)[::-1].
Returns:

out: cf.Datetime, cf.Datetime
Examples 2:
copy()[source]

Return a deep copy.

t.copy() is equivalent to copy.deepcopy(t).

New in version 1.0.

Returns:
out :

The deep copy.
Examples: 
>>> u = t.copy()
equals(other, rtol=None, atol=None, traceback=False)[source]

True if two time durations are equal.

See also

equivalent

New in version 1.0.

Parameters:
other:

The object to compare for equality.

atol: float, optional

The absolute tolerance for all numerical comparisons, By default the value returned by the ATOL function is used.

rtol: float, optional

The relative tolerance for all numerical comparisons, By default the value returned by the RTOL function is used.

traceback: bool, optional

If True then print a traceback highlighting where the two instances differ.
Returns:
out: bool

Whether or not the two instances are equal.
Examples: 
>>> t = cf.TimeDuration(36, 'calendar_months')
>>> u = cf.TimeDuration(3, 'calendar_years') 
>>> t == u
True
>>> t.equals(u, traceback=True)
TimeDuration: Different durations: <CF Data: 36 calendar_months>, <CF Data: 3 calendar_years>
False
equivalent(other, rtol=None, atol=None, traceback=False)[source]

True if two time durations are logically equivalent.

See also

equals

New in version 1.0.

Parameters:
other:

The object to compare for equivalence.

atol: float, optional

The absolute tolerance for all numerical comparisons, By default the value returned by the ATOL function is used.

rtol: float, optional

The relative tolerance for all numerical comparisons, By default the value returned by the RTOL function is used.

traceback: bool, optional

If True then print a traceback highlighting where the two instances differ.
Returns:
out: bool

Whether or not the two instances logically equivalent.
Examples: 
>>> t = cf.TimeDuration(36, 'calendar_months')
>>> u = cf.TimeDuration(3, 'calendar_years') 
>>> t == u
True
>>> t.equivalent(u)
True
>>> t.equals(u, traceback=True)
TimeDuration: Different durations: <CF Data: 12 calendar_months>, <CF Data: 1 calendar_years>
False
inspect()[source]

Inspect the attributes.

See also

cf.inspect

New in version 1.0.

Returns:None
Examples: 
>>> t=cf.TimeDuration(9, 'days')
>>> t.inspect()
<CF TimeDuration: 9 days (from Y-01-01 00:00:00)>
-------------------------------------------------
day: 1
duration: <CF Data: 9 days>
hour: 0
minute: 0
month: 1
second: 0
year: None
interval(year=None, month=None, day=None, hour=None, minute=None, second=None, end=False, calendar=None, iso=None)[source]

Return a time interval of exactly the time duration.

The start (or end, if the end parameter is True) date-time of the time interval is determined by the !year, !month, !day, !hour, !minute and !second attributes.

See also

bounds

New in version 1.0.

Examples 1: 
>>> cf.TimeDuration(1, 'calendar_years').interval(1999)
(<CF Datetime: 1999-01-01 00:00:00>, <CF Datetime: 2000-01-01 00:00:00>)
Parameters:
year, month, day, hour, minute, second: int, optional

The date-time of the start (or end) of the time interval. If any parameter is unset then its value defaults to the attribute of the same name. The time interval calculation requires that all of the parameters have numerical values, so if an unset parameter has a corresponding attribute whose value is None then an exception will be raised.

Example:

t.interval(year=1999, day=16) is equivalent to t.interval(1999, t.month, 16, t.hour, t.minute, t.second).

end: bool, optional

If True then the date-time given by the year, month, day, hour, minute and second parameters defines the end of the time interval. By default it defines the start of the time interval.

calendar: str, optional

Define a CF calendar for the time interval. By default the Gregorian calendar is assumed. Ignored for time durations of calendar years or calendar months.

iso: str, optional

Return the time interval as an ISO 8601 time interval string rather than the default of a tuple of date-time objects. Valid values are (with example outputs for the time interval “3 years from 2007-03-01 13:00:00”):

iso Example output
'start and end' '2007-03-01 13:00:00/2010-03-01 13:00:00'
'start and duration' '2007-03-01 13:00:00/P3Y'
'duration and end' 'P3Y/2010-03-01 13:00:00'
Returns:
out: 2-tuple of cf.Datetime or datetime.datetime; or str

The date-times at each end of the time interval. The first date-time is always earlier than or equal to the second date-time. If iso has been set then an ISO 8601 time interval string is returned instead of a tuple.
Examples 2: 
>>> cf.TimeDuration(1, 'calendar_months').interval(1999, 12)
(<CF Datetime: 1999-12-01 00:00:00>, <CF Datetime: 2000-01-01 00:00:00>)

>>> cf.TimeDuration(2, 'calendar_years').interval(2000, 2, end=True)
(<CF Datetime: 1998-02-01 00:00:00>, <CF Datetime: 2000-02-01 00:00:00>)

>>> cf.TimeDuration(30, 'days').interval(1983, 12, 1, 6)
(<CF Datetime: 1983-12-01 06:00:00>, <CF Datetime: 1983-12-31 06:00:00>)

>>> cf.TimeDuration(30, 'days').interval(1983, 12, 1, 6, end=True)
(<CF Datetime: 1983-11-01 06:00:00>, <CF Datetime: 1983-12-01 06:00:00>)

>>> cf.TimeDuration(0, 'days').interval(1984, 2, 3)
(<CF Datetime: 1984-02-03 00:00:00>, <CF Datetime: 1984-02-03 00:00:00>)

>>> cf.TimeDuration(5, 'days', hour=6).interval(2004, 3, 2, end=True)
(<CF Datetime: 2004-02-26 06:00:00>, <CF Datetime: 2004-03-02 06:00:00>)

>>> cf.TimeDuration(5, 'days', hour=6).interval(2004, 3, 2, end=True, calendar='noleap')
(<CF Datetime: 2004-02-25 06:00:00>, <CF Datetime: 2004-03-02 06:00:00>)

>>> cf.TimeDuration(5, 'days', hour=6).interval(2004, 3, 2, end=True, calendar='360_day')
(<CF Datetime: 2004-02-27 06:00:00>, <CF Datetime: 2004-03-02 06:00:00>)

>>> cf.TimeDuration(19897.546, 'hours').interval(1984, 2, 3, 0)
(<CF Datetime: 1984-02-03 00:00:00>, <CF Datetime: 1986-05-12 01:32:46>)

>>> cf.TimeDuration(19897.546, 'hours').interval(1984, 2, 3, 0, end=True)
(<CF Datetime: 1981-10-26 22:27:14>, <CF Datetime: 1984-02-03 00:00:00>)

Create cf.Query objects for a time interval - one including both bounds and one which excludes the upper bound:

>>> t = cf.TimeDuration(2, 'calendar_years')
>>> interval = t.interval(1999, 12)
>>> c = cf.wi(*interval)
>>> c
<CF Query: (wi [<CF Datetime: 1999-12-01 00:00:00>, <CF Datetime: 2001-01-01 00:00:00>])>
>>> d = cf.ge(interval[0]) & cf.lt(interval[1])
>>> d
<CF Query: [(ge <CF Datetime: 1999-12-01 00:00:00>) & (lt <CF Datetime: 2000-01-01 00:00:00>)]>
>>> c == cf.dt('2001-1-1')
True
>>> d == cf.dt('2001-1-1')
False

Create a cf.Query object which may be used to test where a time coordinate object’s bounds lie inside a time interval:

>>> t = cf.TimeDuration(1, 'calendar_months')
>>> c = cf.cellwi(*t.interval(2000, 1, end=True))
>>> c
<CF Query: [lower_bounds(ge <CF Datetime: 1999-12-01 00:00:00>) & upper_bounds(le <CF Datetime: 2000-01-01 00:00:00>)]>

Create ISO 8601 time interval strings:

>>> t = cf.TimeDuration(6, 'calendar_years')
>>> t.interval(1999, 12, end=True, iso='start and end') 
'1993-12-01 00:00:00/1999-12-01 00:00:00'
>>> t.interval(1999, 12, end=True, iso='start and duration')
'1993-12-01 00:00:00/P6Y'
>>> t.interval(1999, 12, end=True, iso='duration and end')
'P6Y/1999-12-01 00:00:00'
is_day_factor()[source]

Return True if an integer multiple of the time duration is equal to one day.

New in version 1.0.

Examples 1: 
>>> cf.TimeDuration(0.5, 'days').is_day_factor()
True
Returns:out: bool
Examples 2: 
>>> cf.TimeDuration(1, 'days').is_day_factor()
True
>>> cf.TimeDuration(0.25, 'days').is_day_factor()
True
>>> cf.TimeDuration(0.3, 'days').is_day_factor()
False
>>> cf.TimeDuration(2, 'days').is_day_factor()
False

>>> cf.TimeDuration(24, 'hours').is_day_factor()
True
>>> cf.TimeDuration(6, 'hours').is_day_factor()
True
>>> cf.TimeDuration(7, 'hours').is_day_factor()
False
>>> cf.TimeDuration(27, 'hours').is_day_factor()

>>> cf.TimeDuration(1440, 'minutes').is_day_factor()
True
>>> cf.TimeDuration(15, 'minutes').is_day_factor()
True
>>> cf.TimeDuration(17, 'minutes').is_day_factor()
False
>>> cf.TimeDuration(2007, 'minutes').is_day_factor()
False

>>> cf.TimeDuration(86400, 'seconds').is_day_factor()
True
>>> cf.TimeDuration(45, 'seconds').is_day_factor()
True
>>> cf.TimeDuration(47, 'seconds').is_day_factor()
False
>>> cf.TimeDuration(86401, 'seconds').is_day_factor()
False

>>> cf.TimeDuration(1, 'calendar_months').is_day_factor()
False
>>> cf.TimeDuration(1, 'calendar_years').is_day_factor()
False
Units

The units of the time duration.

New in version 1.0.

Examples: 
>>> cf.TimeDuration(3, 'days').Units
<CF Units: days>
>>> t = cf.TimeDuration(cf.Data(12, 'calendar_months'))
>>> t.Units
<CF Units: calendar_months>
>>> t.Units = cf.Units('calendar_years')
>>> t.Units
<CF Units: calendar_years>
>>> t
<CF TimeDuration: 1.0 calendar_years (from Y-01-01 00:00:00)>
isint

True if the time duration is a whole number.

New in version 1.0.

Examples: 
>>> cf.TimeDuration(2, 'hours').isint
True
>>> cf.TimeDuration(2.0, 'hours').isint
True
>>> cf.TimeDuration(2.5, 'hours').isint
False
iso

Return the time duration as an ISO 8601 time duration string.

New in version 1.0.

Examples: 
>>> cf.TimeDuration(45, 'days').iso
'P45D'
>>> cf.TimeDuration(5, 'seconds').iso
'PT5S'
>>> cf.TimeDuration(10, 'calendar_years').iso
'P10Y'
>>> cf.TimeDuration(18, 'calendar_months').iso
'P18M'