cf.TimeDuration.interval

TimeDuration.interval(year=None, month=None, day=None, hour=None, minute=None, second=None, end=False, calendar=None, iso=None)

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 year, month, day, hour, minute and second attributes.

New in version 1.0.

Parameters:

year, month, day, hour, minute, second : ints, optional

The date-time of the start (or end) of the time interval. If any parameter is unset then its value defaults to the attribute of the same name. The time interval calculation requires that all of the parameters have numerical values, so if an unset parameter has a corresponding attribute default which is None then an exception will be raised.

Example:

t.interval(year=1999, day=16) is equivalent to t.interval(1999, t.month, 16, t.hour, t.minute, t.second).

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.

calendar : str, optional

Define a CF calendar for the time interval. By default the Gregorian calendar is assumed. Ignored for time durations of calendar years or calendar months.

iso : string, 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:

out : 2-tuple of cf.Datetime or datetime.datetime; or str

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:

>>> cf.TimeDuration(1, 'calendar_months').interval(1999, 12)
(<CF Datetime: 1999-12-01 00:00:00>, <CF Datetime: 2000-01-01 00:00:00>)

>>> cf.TimeDuration(2, 'calendar_years').interval(2000, 2, end=True)
(<CF Datetime: 1998-02-01 00:00:00>, <CF Datetime: 2000-02-01 00:00:00>)

>>> cf.TimeDuration(30, 'days').interval(1983, 12, 1, 6)
(<CF Datetime: 1983-12-01 06:00:00>, <CF Datetime: 1983-12-31 06:00:00>)

>>> cf.TimeDuration(30, 'days').interval(1983, 12, 1, 6, end=True)
(<CF Datetime: 1983-11-01 06:00:00>, <CF Datetime: 1983-12-01 06:00:00>)

>>> cf.TimeDuration(0, 'days').interval(1984, 2, 3)
(<CF Datetime: 1984-02-03 00:00:00>, <CF Datetime: 1984-02-03 00:00:00>)

>>> cf.TimeDuration(5, 'days', hour=6).interval(2004, 3, 2, end=True)
(<CF Datetime: 2004-02-26 06:00:00>, <CF Datetime: 2004-03-02 06:00:00>)

>>> cf.TimeDuration(5, 'days', hour=6).interval(2004, 3, 2, end=True, calendar='noleap')
(<CF Datetime: 2004-02-25 06:00:00>, <CF Datetime: 2004-03-02 06:00:00>)

>>> cf.TimeDuration(5, 'days', hour=6).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>)

>>> cf.TimeDuration(19897.546, 'hours').interval(1984, 2, 3, 0)
(<CF Datetime: 1984-02-03 00:00:00>, <CF Datetime: 1986-05-12 01:32:46>)

>>> cf.TimeDuration(19897.546, 'hours').interval(1984, 2, 3, 0, end=True)
(<CF Datetime: 1981-10-26 22:27:14>, <CF Datetime: 1984-02-03 00:00:00>)

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(1999, 12)
>>> c = cf.wi(*interval)
>>> c
<CF Query: (wi [<CF Datetime: 1999-12-01 00:00:00>, <CF Datetime: 2001-01-01 00:00:00>])>
>>> d = cf.ge(interval[0]) & cf.lt(interval[1])
>>> d
<CF Query: [(ge <CF Datetime: 1999-12-01 00:00:00>) & (lt <CF Datetime: 2000-01-01 00:00:00>)]>
>>> c == cf.dt('2001-1-1')
True
>>> d == cf.dt('2001-1-1')
False

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

Create ISO 8601 time interval strings:

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