earthkit.time.climatology - Generate dates to compute model climates

Date utilities to build a climatology

class earthkit.time.climatology.RelativeYear(value: int): Wrapper for a year intended to be relative to a reference

earthkit.time.climatology.date_range(reference: date, start: date | int | RelativeYear, end: date | int | RelativeYear, recurrence: str = 'yearly', include_endpoint: bool = True) → Iterator[date]

Generate a sequence of dates following a recurrence pattern

If the reference date is February 29th on a leap year, it will be replaced by February 28th for every year in the output.

Parameters:

reference (datetime.date) – Reference date setting the fixed part in the sequence (e.g., month and day for a yearly recurrence)
start (datetime.date, int, or RelativeYear) – Start of the period. Either a full date or a meaningful identifier (e.g. year for a yearly recurrence)
end (datetime.date, int, or RelativeYear) – End of the period. Included in the sequence unless include_endpoint is False
recurrence ("yearly") – Type of recurrence
include_endpoint (bool) – If False, do not include the end in the sequence

Returns:

Sequence of dates

Return type:

datetime.date iterator

Examples

>>> list(date_range(date(2020, 4, 12), 1999, 2002))
[datetime.date(1999, 4, 12), datetime.date(2000, 4, 12), datetime.date(2001, 4, 12), datetime.date(2002, 4, 12)]
>>> list(date_range(date(2020, 4, 12), 1999, 2002, include_endpoint=False))
[datetime.date(1999, 4, 12), datetime.date(2000, 4, 12), datetime.date(2001, 4, 12)]
>>> list(date_range(date(2014, 8, 23), date(2010, 8, 16), date(2012, 8, 1)))
[datetime.date(2010, 8, 23), datetime.date(2011, 8, 23)]
>>> list(date_range(date(2014, 8, 23), RelativeYear(-3), RelativeYear(-1)))
[datetime.date(2011, 8, 23), datetime.date(2012, 8, 23), datetime.date(2013, 8, 23)]

Generate a set of dates for a model climate

The set is created by combining yearly dates between start and end, for each date between reference - before and reference + after. If any of these dates is February 29th, the whole corresponing sequence will use February 28th instead.