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