search
Search
Login
Map of Data Science
menu
menu search toc more_vert
Robocat
Guest 0reps
Sign up
Log in
account_circleMy Profile homeAbout paidPricing
emailContact us
exit_to_appLog out
Map of data science
Thanks for the thanks!
close
Comments
Log in or sign up
Cancel
Post
account_circle
Profile
exit_to_app
Sign out
help Ask a question
Share on Twitter
search
keyboard_voice
close
Searching Tips
Search for a recipe:
"Creating a table in MySQL"
Search for an API documentation: "@append"
Search for code: "!dataframe"
Apply a tag filter: "#python"
Useful Shortcuts
/ to open search panel
Esc to close search panel
to navigate between search results
d to clear all current filters
Enter to expand content preview
icon_star
Doc Search
icon_star
Code Search Beta
SORRY NOTHING FOUND!
mic
Start speaking...
Voice search is only supported in Safari and Chrome.
Navigate to
A
A
brightness_medium
share
arrow_backShare
Twitter
Facebook

Pandas | date_range method

Pandas
chevron_right
Documentation
chevron_right
General Functions
schedule Jul 1, 2022
Last updated
local_offer PandasPython
Tags
map
Check out the interactive map of data science

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.

WARNING

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

"left"

  • The lower bound becomes inclusive.

  • The upper bound becomes exclusive.

"right"

  • The lower bound becomes exclusive.

  • The upper bound becomes inclusive.

None

Both bounds are inclusive.

By default, closed=None.

Return Value

A DatetimeIndex.

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:

import datetime
datetime_tomorrow = datetime.date.today() + datetime.timedelta(days=1)
pd.date_range(start=datetime.date.today(), end=datetime_tomorrow)
DatetimeIndex(['2020-09-02', '2020-09-03'], dtype='datetime64[ns]', freq='D')

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 = pd.DataFrame({"A":["a","b","c","d"]}, index=index_date)
df
                     A
2020-12-25 00:00:00  a
2020-12-25 03:00:00  b
2020-12-25 06:00:00  c
2020-12-25 09:00:00  d
robocat
Published by Isshin Inada
Edited by 0 others
Did you find this page useful?
thumb_up
thumb_down
Ask a question or leave a feedback...