Pandas | date_range method
Start your free 7-days trial now!
Pandas date_range(~) method returns a DatetimeIndex with fixed frequency.
Parameters
1. startlink | string or datetime-like | optional
The lower bound (inclusive) of the range.
2. endlink | string or datetime-like | optional
The upper bound (inclusive) of the range.
3. periodslink | int | optional
The desired number of dates. By default, periods=True.
Out of the above three parameters, exactly two must be specified - no less, no more.
4. freqlink | string or DateOffset | optional
The step-size (the interval) between a pair of consecutive dates. By default, freq="D" (step-size of a day).
5. tzlink | str or tzinfo | optional
The timezone of the dates. By default, the date-times are naive without any notion of timezones.
6. normalizelink | boolean | optional
Whether or not to set the time unit of the dates to midnight. By default, normalize=False.
7. namelink | string | optional
Name of the resulting DatetimeIndex. By default, name=None.
8. closedlink | None or string | optional
Whether or not to make the bounds (start and end) inclusive/exclusive:
Value | Description |
|---|---|
|
|
|
|
| Both bounds are inclusive. |
By default, closed=None.
Return Value
Examples
Basic usage
To create a sequence of dates from 2020-12-25 to 2020-12-27 (both inclusive):
pd.date_range(start="2020-12-25", end="2020-12-27")
DatetimeIndex(['2020-12-25', '2020-12-26', '2020-12-27'], dtype='datetime64[ns]', freq='D')
The default step-size (the frequency) is a day, so this is why we see freq="D" in the output.
You could also use datetime-like objects for start and end:
Specifying the period
To create a sequence of dates of length 3 from 2020-12-25 (inclusive):
pd.date_range(start="2020-12-25", periods=3)
DatetimeIndex(['2020-12-25', '2020-12-26', '2020-12-27'], dtype='datetime64[ns]', freq='D')
Specifying the frequency
The frequency can be thought of as the step-size. The default frequency is 1 day:
pd.date_range(start="2020-12-25", periods=3) # freq="D"
DatetimeIndex(['2020-12-25', '2020-12-26', '2020-12-27'], dtype='datetime64[ns]', freq='D')
Let's try a 2-day interval:
pd.date_range(start="2020-12-25", periods=3, freq="2D")
DatetimeIndex(['2020-12-25', '2020-12-27', '2020-12-29'], dtype='datetime64[ns]', freq='2D')
Let's now try a 1-month interval:
pd.date_range(start="2020-12-25", periods=3, freq="M")
DatetimeIndex(['2020-12-31', '2021-01-31', '2021-02-28'], dtype='datetime64[ns]', freq='M')
If the frequency is set to months, the day unit of our start parameter becomes irrelevant - the day will always be set to the end of the month.
Specifying the timezone
Instead of the default dates that are unaware of timezones, we can explicitly specify a timezone using the tz parameter:
pd.date_range(start="2020-12-25", periods=3, tz="Europe/Paris")
DatetimeIndex(['2020-12-25 00:00:00+01:00', '2020-12-26 00:00:00+01:00', '2020-12-27 00:00:00+01:00'], dtype='datetime64[ns, Europe/Paris]', freq='D')
Notice how we have +01:00 appended to the Datetimes, which denotes a UTC offset of +1 hour.
Normalising dates
By default, the method will follow the time unit (e.g. the hour of the day) if you specify one:
pd.date_range(start="2020-12-25 05:15:20", periods=3)
DatetimeIndex(['2020-12-25 05:15:20', '2020-12-26 05:15:20', '2020-12-27 05:15:20'], dtype='datetime64[ns]', freq='D')
We can set the time of the dates to midnight by setting normalize=True:
pd.date_range(start="2020-12-25 05:15:20", periods=3, normalize=True)
DatetimeIndex(['2020-12-25', '2020-12-26', '2020-12-27'], dtype='datetime64[ns]', freq='D')
Specifying a name
To give a name to the resulting DatetimeIndex:
pd.date_range(start="2020-12-25", periods=2, name="My Dates")
DatetimeIndex(['2020-12-25', '2020-12-26'], dtype='datetime64[ns]', name='My Dates', freq='D')
Notice how we have name="My Dates" encoded into the DatetimeIndex.
Specifying the close
By default, closed=None, which means that the lower and upper bounds are both inclusive:
pd.date_range(start="2020-12-25", end="2020-12-27")
DatetimeIndex(['2020-12-25', '2020-12-26', '2020-12-27'], dtype='datetime64[ns]', freq='D')
To make the lower bound inclusive and upper bound exclusive, set closed="left":
pd.date_range(start="2020-12-25", end="2020-12-27", closed="left")
DatetimeIndex(['2020-12-25', '2020-12-26'], dtype='datetime64[ns]', freq='D')
To make the lower bound exclusive and upper bound inclusive, set closed="right":
pd.date_range(start="2020-12-25", end="2020-12-27", closed="right")
DatetimeIndex(['2020-12-26', '2020-12-27'], dtype='datetime64[ns]', freq='D')
Creating a DataFrame with DatetimeIndex
The date_range(~) method can be used to initialise a DataFrame with DatetimeIndex like so:
index_date = pd.date_range("2020-12-25", periods=4, freq="3H")df
A2020-12-25 00:00:00 a2020-12-25 03:00:00 b2020-12-25 06:00:00 c2020-12-25 09:00:00 d
