cf.TimeDuration¶

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, calendar 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')
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])
>>> 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.

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.

New in version 1.0.

See also

cf.dt, cf.Data, cf.Datetime

Initialisation

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.

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:
units='calendar_months'

Parameter example:
units='days'

Parameter 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.

Note

The offset element month is ignored unless the time duration is at least 1 calendar year.

The offset element day is ignored unless the time duration is at least 1 calendar month.

The offset element hour is ignored unless the time duration is at least 1 day

The offset element minute is ignored unless the time duration is at least 1 hour.

The offset element second is ignored unless the time duration is at least 1 minute

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))

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.
`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.

Special¶

Methods

`__deepcopy__`	Used if copy.deepcopy is called.
`__repr__`	Called by the `repr` built-in function.
`__str__`	“Called by the `str` built-in function.
`__abs__`	The unary arithmetic operation `abs`
`__bool__`	Truth value testing and the built-in operation `bool`
`__neg__`	The unary arithmetic operation `-`
`__int__`	Called to implement the built-in function `int`
`__ge__`	The rich comparison operator `>=`
`__gt__`	The rich comparison operator `>`
`__le__`	The rich comparison operator `<=`
`__lt__`	The rich comparison operator `<`
`__eq__`	The rich comparison operator `==`
`__ne__`	The rich comparison operator `!=`
`__add__`	The binary arithmetic operation `+`
`__sub__`	The binary arithmetic operation `-`
`__mul__`	The binary arithmetic operation `*`
`__div__`	The binary arithmetic operation `/`
`__floordiv__`	The binary arithmetic operation `//`
`__truediv__`	The binary arithmetic operation `/` (true division)
`__iadd__`	The augmented arithmetic assignment `+=`
`__idiv__`	The augmented arithmetic assignment `/=`
`__itruediv__`	The augmented arithmetic assignment `/=` (true division)
`__ifloordiv__`	The augmented arithmetic assignment `//=`
`__imul__`	The augmented arithmetic assignment `*=`
`__isub__`	The augmented arithmetic assignment `-=`
`__imod__`	The augmented arithmetic assignment `%=`
`__radd__`	The binary arithmetic operation `+` with reflected operands.
`__rsub__`	The binary arithmetic operation `-` with reflected operands.
`__mod__`	The binary arithmetic operation `%`
`__rmod__`	The binary arithmetic operation `%` with reflected operands.
`__array__`	Returns a `numpy` array representing the time duration.
`__dask_tokenize__`	Return a hashable value fully representative of the object.
`__data__`	Returns a new reference to the `duration` attribute.

cf 3.16.1

Related Topics

cf.TimeDuration¶

Attributes¶

Methods¶

Special¶