cf.TimeDuration

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

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 one a units string equivalent to calendar years, calendar months, days, hours, minutes or seconds.

year, month, day, hour, minute, second : ints 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)

TimeDuration attributes

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

TimeDuration methods

copy	Return a deep copy.
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.