cf.TimeDuration.interval

TimeDuration.interval(dt, end=False, 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 date-time given by the dt parameter.

New in version 1.0.

See also

bounds

Parameters
dt:

The date-time. One of:

  • A str specifying an ISO 8601-like date-time string (in which non-Gregorian calendar dates are allowed).

  • datetime.datetime or subclass `cftime.datetime (such as Datetime360Day).

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.

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

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:

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

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(cf.dt(1999, 12))
>>> c = cf.wi(*interval)
>>> c
<CF Query: (wi [cftime.DatetimeGregorian(1999-12-01 00:00:00), cftime.DatetimeGregorian(2001-12-01 00:00:00)])>
>>> c == cf.dt('2001-1-1', calendar='gregorian')
True

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(cf.dt(2000, 1), end=True))
>>> c
<CF Query: [lower_bounds(ge 1999-12-01 00:00:00) & upper_bounds(le 2000-01-01 00:00:00)]>

Create ISO 8601 time interval strings:

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