cf.TimeDuration.interval

TimeDuration.interval(dt, calendar=None, end=False, 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 parameters, but if any of these is unset then its default value is taken from the attribute of the same name (i.e. the year, month, day, hour, minute and second attributes respectively).

See also

bounds

New in version 1.0.

Examples 1:

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

Parameters:

year, month, day, hour, minute, second: int, 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 whose value 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 the CF calendar for the input date-time and output time interval. By default the calendar of the input date-time is used. If calendar is set, then the calendar of the input date-time is overridden.

Example:

To set a calendar without leap years: calendar='noleap'.

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:

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 2:

>>> 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(5, 'days', hour=6).interval(2004, 3, 2, 13, end=True)
(datetime.datetime(2004, 2, 26, 13, 0), <CF Datetime: 2004-03-02 13: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'