pandas.date_range#
- pandas.date_range(start=None, end=None, periods=None, freq=None, tz=None, normalize=False, name=None, inclusive='both', *, unit=None, **kwargs)[source]#
Return a fixed frequency DatetimeIndex.
Returns the range of equally spaced time points (where the difference between any two adjacent points is specified by the given frequency) such that they all satisfy start <[=] x <[=] end, where the first one and the last one are, resp., the first and last time points in that range that fall on the boundary of
freq
(if given as a frequency string) or that are valid forfreq
(if given as apandas.tseries.offsets.DateOffset
). (If exactly one ofstart
,end
, orfreq
is not specified, this missing parameter can be computed givenperiods
, the number of timesteps in the range. See the note below.)- Parameters:
- startstr or datetime-like, optional
Left bound for generating dates.
- endstr or datetime-like, optional
Right bound for generating dates.
- periodsint, optional
Number of periods to generate.
- freqstr, Timedelta, datetime.timedelta, or DateOffset, default ‘D’
Frequency strings can have multiples, e.g. ‘5h’. See here for a list of frequency aliases.
- tzstr or tzinfo, optional
Time zone name for returning localized DatetimeIndex, for example ‘Asia/Hong_Kong’. By default, the resulting DatetimeIndex is timezone-naive unless timezone-aware datetime-likes are passed.
- normalizebool, default False
Normalize start/end dates to midnight before generating date range.
- namestr, default None
Name of the resulting DatetimeIndex.
- inclusive{“both”, “neither”, “left”, “right”}, default “both”
Include boundaries; Whether to set each bound as closed or open.
Added in version 1.4.0.
- unitstr, default None
Specify the desired resolution of the result.
Added in version 2.0.0.
- **kwargs
For compatibility. Has no effect on the result.
- Returns:
- DatetimeIndex
See also
DatetimeIndex
An immutable container for datetimes.
timedelta_range
Return a fixed frequency TimedeltaIndex.
period_range
Return a fixed frequency PeriodIndex.
interval_range
Return a fixed frequency IntervalIndex.
Notes
Of the four parameters
start
,end
,periods
, andfreq
, exactly three must be specified. Iffreq
is omitted, the resultingDatetimeIndex
will haveperiods
linearly spaced elements betweenstart
andend
(closed on both sides).To learn more about the frequency strings, please see this link.
Examples
Specifying the values
The next four examples generate the same DatetimeIndex, but vary the combination of start, end and periods.
Specify start and end, with the default daily frequency.
>>> pd.date_range(start='1/1/2018', end='1/08/2018') DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03', '2018-01-04', '2018-01-05', '2018-01-06', '2018-01-07', '2018-01-08'], dtype='datetime64[ns]', freq='D')
Specify timezone-aware start and end, with the default daily frequency.
>>> pd.date_range( ... start=pd.to_datetime("1/1/2018").tz_localize("Europe/Berlin"), ... end=pd.to_datetime("1/08/2018").tz_localize("Europe/Berlin"), ... ) DatetimeIndex(['2018-01-01 00:00:00+01:00', '2018-01-02 00:00:00+01:00', '2018-01-03 00:00:00+01:00', '2018-01-04 00:00:00+01:00', '2018-01-05 00:00:00+01:00', '2018-01-06 00:00:00+01:00', '2018-01-07 00:00:00+01:00', '2018-01-08 00:00:00+01:00'], dtype='datetime64[ns, Europe/Berlin]', freq='D')
Specify start and periods, the number of periods (days).
>>> pd.date_range(start='1/1/2018', periods=8) DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03', '2018-01-04', '2018-01-05', '2018-01-06', '2018-01-07', '2018-01-08'], dtype='datetime64[ns]', freq='D')
Specify end and periods, the number of periods (days).
>>> pd.date_range(end='1/1/2018', periods=8) DatetimeIndex(['2017-12-25', '2017-12-26', '2017-12-27', '2017-12-28', '2017-12-29', '2017-12-30', '2017-12-31', '2018-01-01'], dtype='datetime64[ns]', freq='D')
Specify start, end, and periods; the frequency is generated automatically (linearly spaced).
>>> pd.date_range(start='2018-04-24', end='2018-04-27', periods=3) DatetimeIndex(['2018-04-24 00:00:00', '2018-04-25 12:00:00', '2018-04-27 00:00:00'], dtype='datetime64[ns]', freq=None)
Other Parameters
Changed the freq (frequency) to
'ME'
(month end frequency).>>> pd.date_range(start='1/1/2018', periods=5, freq='ME') DatetimeIndex(['2018-01-31', '2018-02-28', '2018-03-31', '2018-04-30', '2018-05-31'], dtype='datetime64[ns]', freq='ME')
Multiples are allowed
>>> pd.date_range(start='1/1/2018', periods=5, freq='3ME') DatetimeIndex(['2018-01-31', '2018-04-30', '2018-07-31', '2018-10-31', '2019-01-31'], dtype='datetime64[ns]', freq='3ME')
freq can also be specified as an Offset object.
>>> pd.date_range(start='1/1/2018', periods=5, freq=pd.offsets.MonthEnd(3)) DatetimeIndex(['2018-01-31', '2018-04-30', '2018-07-31', '2018-10-31', '2019-01-31'], dtype='datetime64[ns]', freq='3ME')
Specify tz to set the timezone.
>>> pd.date_range(start='1/1/2018', periods=5, tz='Asia/Tokyo') DatetimeIndex(['2018-01-01 00:00:00+09:00', '2018-01-02 00:00:00+09:00', '2018-01-03 00:00:00+09:00', '2018-01-04 00:00:00+09:00', '2018-01-05 00:00:00+09:00'], dtype='datetime64[ns, Asia/Tokyo]', freq='D')
inclusive controls whether to include start and end that are on the boundary. The default, “both”, includes boundary points on either end.
>>> pd.date_range(start='2017-01-01', end='2017-01-04', inclusive="both") DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03', '2017-01-04'], dtype='datetime64[ns]', freq='D')
Use
inclusive='left'
to exclude end if it falls on the boundary.>>> pd.date_range(start='2017-01-01', end='2017-01-04', inclusive='left') DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03'], dtype='datetime64[ns]', freq='D')
Use
inclusive='right'
to exclude start if it falls on the boundary, and similarlyinclusive='neither'
will exclude both start and end.>>> pd.date_range(start='2017-01-01', end='2017-01-04', inclusive='right') DatetimeIndex(['2017-01-02', '2017-01-03', '2017-01-04'], dtype='datetime64[ns]', freq='D')
Specify a unit
>>> pd.date_range(start="2017-01-01", periods=10, freq="100YS", unit="s") DatetimeIndex(['2017-01-01', '2117-01-01', '2217-01-01', '2317-01-01', '2417-01-01', '2517-01-01', '2617-01-01', '2717-01-01', '2817-01-01', '2917-01-01'], dtype='datetime64[s]', freq='100YS-JAN')