xarray.date_range#

xarray.date_range(start=None, end=None, periods=None, freq=None, tz=None, normalize=False, name=None, inclusive='both', unit='ns', calendar='standard', use_cftime=None)[source]#

Return a fixed frequency datetime index.

The type (xarray.CFTimeIndex or pandas.DatetimeIndex) of the returned index depends on the requested calendar and on use_cftime.

Parameters:

start (str or datetime-like, optional) – Left bound for generating dates.
end (str or datetime-like, optional) – Right bound for generating dates.
periods (int, optional) – Number of periods to generate.
freq (str or None, default: "D") – Frequency strings can have multiples, e.g. “5h” and negative values, e.g. “-1D”.
tz (str or tzinfo, optional) – Time zone name for returning localized DatetimeIndex, for example ‘Asia/Hong_Kong’. By default, the resulting DatetimeIndex is timezone-naive. Only valid with pandas DatetimeIndex.
normalize (bool, default: False) – Normalize start/end dates to midnight before generating date range.
name (str, default: None) – Name of the resulting index
inclusive ({"both", "neither", "left", "right"}, default: "both") – Include boundaries; whether to set each bound as closed or open.

Added in version 2023.02.0.
unit ({"s", "ms", "us", "ns"}, default "ns") – Specify the desired resolution of the result.

Added in version 2024.12.0.
calendar (str, default: "standard") – Calendar type for the datetimes.
use_cftime (boolean, optional) – If True, always return a CFTimeIndex. If False, return a pd.DatetimeIndex if possible or raise a ValueError. If None (default), return a pd.DatetimeIndex if possible, otherwise return a CFTimeIndex. Overridden to False if tz is not None.

Returns:

CFTimeIndex or pd.DatetimeIndex

Notes

When use_cftime=True, or a calendar other than “standard”, “gregorian”, or “proleptic_gregorian” is provided, this function is an analog of pandas.date_range for use in generating sequences of cftime.datetime objects. It supports most of the features of pandas.date_range (e.g. specifying how the index is closed on either side, or whether or not to normalize the start and end bounds); however, there are some notable exceptions:

You cannot specify a tz (time zone) argument.
Start or end dates specified as partial-datetime strings must use the ISO-8601 format.
It supports many, but not all, frequencies supported by pandas.date_range. For example it does not currently support any of the business-related or semi-monthly frequencies.
Compound sub-monthly frequencies are not supported, e.g. ‘1H1min’, as these can easily be written in terms of the finest common resolution, e.g. ‘61min’.

Valid simple frequency strings for use with cftime-calendars include any multiples of the following.

Alias	Description
YE	Year-end frequency
YS	Year-start frequency
QE	Quarter-end frequency
QS	Quarter-start frequency
ME	Month-end frequency
MS	Month-start frequency
D	Day frequency
h	Hour frequency
min	Minute frequency
s	Second frequency
ms	Millisecond frequency
us	Microsecond frequency

Any multiples of the following anchored offsets are also supported.

Alias	Description
Y(E,S)-JAN	Annual frequency, anchored at the (end, beginning) of January
Y(E,S)-FEB	Annual frequency, anchored at the (end, beginning) of February
Y(E,S)-MAR	Annual frequency, anchored at the (end, beginning) of March
Y(E,S)-APR	Annual frequency, anchored at the (end, beginning) of April
Y(E,S)-MAY	Annual frequency, anchored at the (end, beginning) of May
Y(E,S)-JUN	Annual frequency, anchored at the (end, beginning) of June
Y(E,S)-JUL	Annual frequency, anchored at the (end, beginning) of July
Y(E,S)-AUG	Annual frequency, anchored at the (end, beginning) of August
Y(E,S)-SEP	Annual frequency, anchored at the (end, beginning) of September
Y(E,S)-OCT	Annual frequency, anchored at the (end, beginning) of October
Y(E,S)-NOV	Annual frequency, anchored at the (end, beginning) of November
Y(E,S)-DEC	Annual frequency, anchored at the (end, beginning) of December
Q(E,S)-JAN	Quarter frequency, anchored at the (end, beginning) of January
Q(E,S)-FEB	Quarter frequency, anchored at the (end, beginning) of February
Q(E,S)-MAR	Quarter frequency, anchored at the (end, beginning) of March
Q(E,S)-APR	Quarter frequency, anchored at the (end, beginning) of April
Q(E,S)-MAY	Quarter frequency, anchored at the (end, beginning) of May
Q(E,S)-JUN	Quarter frequency, anchored at the (end, beginning) of June
Q(E,S)-JUL	Quarter frequency, anchored at the (end, beginning) of July
Q(E,S)-AUG	Quarter frequency, anchored at the (end, beginning) of August
Q(E,S)-SEP	Quarter frequency, anchored at the (end, beginning) of September
Q(E,S)-OCT	Quarter frequency, anchored at the (end, beginning) of October
Q(E,S)-NOV	Quarter frequency, anchored at the (end, beginning) of November
Q(E,S)-DEC	Quarter frequency, anchored at the (end, beginning) of December

Finally, the following calendar aliases are supported.

Alias	Date type	Available use_cftime=False
standard, gregorian	`cftime.DatetimeGregorian`	True
proleptic_gregorian	`cftime.DatetimeProlepticGregorian`	True
noleap, 365_day	`cftime.DatetimeNoLeap`	False
all_leap, 366_day	`cftime.DatetimeAllLeap`	False
360_day	`cftime.Datetime360Day`	False
julian	`cftime.DatetimeJulian`	False

As in the standard pandas function, exactly three of start, end, periods, or freq are required to generate a date range. Note that freq defaults to "D" in the event that any of start, end, or periods are set to None. See pandas.date_range(). for more examples of the behavior of date_range with each of the parameters.

Examples

This function returns a CFTimeIndex, populated with cftime.datetime objects associated with the specified calendar type, e.g.

>>> xr.date_range(
...     start="2000", periods=6, freq="2MS", calendar="noleap", use_cftime=True
... )
CFTimeIndex([2000-01-01 00:00:00, 2000-03-01 00:00:00, 2000-05-01 00:00:00,
             2000-07-01 00:00:00, 2000-09-01 00:00:00, 2000-11-01 00:00:00],
            dtype='object', length=6, calendar='noleap', freq='2MS')