cf.TimeDuration

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

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: 1 day (from Y-M-D 00:00:00)>
>>> t.Units = 's' 
>>> t
<CF TimeDuration: 86400.0 s (from Y-M-D h:m:s)> 
>>> t.Units = cf.Units('minutes')
>>> t
<CF TimeDuration: 1440.0 minutes (from Y-M-D h:m:00)> 
>>> t.Units = 'calendar_months'
ValueError: Can't set units to non-equivalent units

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: 6 calendar_months (from Y-M-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-M-D 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'

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')
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, 'hours') <= 2
True
>>> 30.5 != cf.TimeDuration(2, 'days')
True

>>> cf.TimeDuration(2, 'calendar_years') > numpy.array(1.5)
True
>>> type(cf.TimeDuration(2, 'calendar_years') > numpy.array(1.5))
numpy.bool_
>>> cf.TimeDuration(2, 'calendar_years') > numpy.array([1.5])
array([ True], dtype=bool)
>>> numpy.array([[1, 12]]) > cf.TimeDuration(2, 'calendar_months')
array([[False,  True]], dtype=bool)

>>> cf.TimeDuration(2, 'days') == cf.Data(2)
<CF Data: True>
>>> cf.TimeDuration(2, 'days') == cf.Data([2.], 'days')
<CF Data: [True]>
>>> cf.Data([[60]], 'seconds') < cf.TimeDuration(2, 'days')
<CF Data: [[True]]>
>>> cf.Data([1, 12], 'calendar_months') < cf.TimeDuration(6, 'calendar_months')
<CF Data: [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 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], '10')
<CF TimeDuration: 4.3 calendar_months (from Y-M-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.

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

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.

Example:

units='calendar_months'

Example:

units='days'

Example:

units=cf.Units('calendar_years')

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.

Example:

>>> cf.TimeDuration(1, 'calendar_month').bounds(cf.dt('2000-1-8'))
(<CF Datetime: 2000-01-01 00:00:00>, <CF Datetime: 2000-02-01 00:00:00>)
>>> cf.TimeDuration(1, 'calendar_month', day=15).bounds(cf.dt('2000-1-8'))
(<CF Datetime: 1999-12-15 00:00:00>, <CF Datetime: 2000-01-15 00:00:00>)
>>> cf.TimeDuration(1, 'calendar_month', month=4, day=30).bounds(cf.dt('2000-1-8'))
(<CF Datetime: 1999-12-30 00:00:00>, <CF Datetime: 2000-01-30 00:00:00>)

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)

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-like time duration string.

Methods

bounds	Return a time interval containing a date-time.
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.
is_day_factor	Return True if an integer multiple of the time duration is equal to one day.