Pandas Date Range – pd.date_range()

Think of Pandas Date Range (pd.date_range) like a “date ruler.” You have a start time, end time, and interval frequency you’d like to split your dates by.

Don’t get intimidated by the “date” part, you can just as easily create time ranges as well. The frequency (how you’ll split up your pd.date_range) is set by the offset options. Get familiar with these!

You’ll use pd.date_range when you need to have a clean series of dates to reindex your DataFrame.


Pseudo Code: Create a range of timestamps at a specified start and end.

Pandas Date Range

Pandas Date Range - How to create a time series range of evenly distributed date ranges.

PD.Date_Range Parameters

  • start – The timestamp that you’d like to start your date range
  • end – The timestamp you’d like to end your date range
  • periods (Optional) – Say instead of splitting your start/end times by 5 minute intervals, you just wanted to have 3 cuts. You can specify periods=3 and pandas will automatically cut your time for you.
  • freq – The sub periods of time that you will cut your date range into. In the above image, we chose 6 hours (‘6H’) to split our time by. This resulted in 4 buckets (24 hours in a day). See all the offset aliases here.
  • Normalized (Optional) – Selecting Normalized will automatically set your start and end dates to midnight. This is useful when your start/end time has an hour specified, but you only care about the ‘day’ information.
  • Other Parameters – For a list of other lesser used parameters. Check out the official documentation.

Now the fun part, let’s take a look at a code sample

In [1]:
import pandas as pd

Pandas Date Range

Pandas Date Range is super helpful for creating a range of times or dates. It's most often used when reindexing your DatetimeIndex.

Make sure to check out the frequency offsets for a full list of how to split your data.

The output of pd.date_range() will be a clean list of dates/times.

Examples we'll run through:

  1. Creating a simple date range
  2. Creating a date range in 6 minute intervals
  3. Creating a date range with 10 periods
  4. Exploring different frequencies

1. Creating a simple date range

To create a date range, you must first specify a start time and end time.

Here I'm creating a date range from the Jan 1, 2020 to Jan 6th, 2020. The default frequency is 'day'. This means my date range will be split by days.

Notice how I have 6 values, a day for each day between my start and end times.

In [2]:
pd.date_range(start='2020-01-01', end='2020-01-06')
DatetimeIndex(['2020-01-01', '2020-01-02', '2020-01-03', '2020-01-04',
               '2020-01-05', '2020-01-06'],
              dtype='datetime64[ns]', freq='D')

2. Creating a date range in 6 minute intervals

Let's say you didn't want to split your date range by day, but rather by 6 minutes.

To do this you need to specify your 'freq' parameter and tell pandas to split your start/end times every 6 minutes.

In the example below, I'll specify times (not just dates) within my start/end.

In [3]:
pd.date_range(start='2020-01-01 00:00:00', end='2020-01-01 00:24:00', freq='6T')
DatetimeIndex(['2020-01-01 00:00:00', '2020-01-01 00:06:00',
               '2020-01-01 00:12:00', '2020-01-01 00:18:00',
               '2020-01-01 00:24:00'],
              dtype='datetime64[ns]', freq='6T')

Notice here how I specified '6T' for my frequency. 'T' is the offset code for minutes. '6T' means 6-minutes. For a full list of frequency offsets check out the pandas documentation.

3. Creating a date range with 10 periods

Actually, instead of splitting my date range by every 6 minutes, I just want to create 10 periods or buckets. Rather than specifying a freq=144S (24min / 10), I'm going to tell pandas I want 10 periods

In [4]:
pd.date_range(start='2020-01-01 00:00:00', end='2020-01-01 00:24:00', periods=10)
DatetimeIndex(['2020-01-01 00:00:00', '2020-01-01 00:02:40',
               '2020-01-01 00:05:20', '2020-01-01 00:08:00',
               '2020-01-01 00:10:40', '2020-01-01 00:13:20',
               '2020-01-01 00:16:00', '2020-01-01 00:18:40',
               '2020-01-01 00:21:20', '2020-01-01 00:24:00'],
              dtype='datetime64[ns]', freq=None)

4. Exploring different frequencies

Let's get creative and explore different frequency options. There are a ton of cool ones to use. Pandas actually gives you a ton of flexibility for business use cases as well.

Business Day 'B' - Notice how the weekends are taken out of the date range below

In [5]:
pd.date_range(start='2020-01-01', end='2020-01-10', freq='B')
DatetimeIndex(['2020-01-01', '2020-01-02', '2020-01-03', '2020-01-06',
               '2020-01-07', '2020-01-08', '2020-01-09', '2020-01-10'],
              dtype='datetime64[ns]', freq='B')

Weekly 'W' - Cutting your date range into weeks

In [6]:
pd.date_range(start='2020-01-01', end='2020-03-10', freq='W')
DatetimeIndex(['2020-01-05', '2020-01-12', '2020-01-19', '2020-01-26',
               '2020-02-02', '2020-02-09', '2020-02-16', '2020-02-23',
               '2020-03-01', '2020-03-08'],
              dtype='datetime64[ns]', freq='W-SUN')

Month End 'M' / Month Start 'MS' - Splitting your date range by months

In [7]:
pd.date_range(start='2020-01-01', end='2020-04-01', freq='M')
DatetimeIndex(['2020-01-31', '2020-02-29', '2020-03-31'], dtype='datetime64[ns]', freq='M')
In [8]:
pd.date_range(start='2020-01-01', end='2020-04-01', freq='MS')
DatetimeIndex(['2020-01-01', '2020-02-01', '2020-03-01', '2020-04-01'], dtype='datetime64[ns]', freq='MS')

Quarters 'Q' - Splitting your date range by quarters

In [9]:
pd.date_range(start='2020-01-01', end='2020-12-01', freq='Q')
DatetimeIndex(['2020-03-31', '2020-06-30', '2020-09-30'], dtype='datetime64[ns]', freq='Q-DEC')

Every 5 Months '5M' - Don't forget your can put a integer in front of your freq to expand the frequency

In [10]:
pd.date_range(start='2020-01-01', end='2021-12-01', freq='5M')
DatetimeIndex(['2020-01-31', '2020-06-30', '2020-11-30', '2021-04-30',
              dtype='datetime64[ns]', freq='5M')

What other frequencies can you play with?

Link to code above

Check out more Pandas functions on our Pandas Page

Official Documentation