Pandas date_range: How to Create a Date Range in Pandas

In this tutorial, we’re diving deep into one of the essential and versatile tools of the Pandas library—the date_range function. Whether you’re a beginner just starting to explore the power of Pandas or already an adept user, this function is one you’ll definitely want to have in your Python toolbox. This will open up your ability to work with dates and times in Pandas.

Mastering the Pandas date_range function will open up a world of possibilities for your time series data analysis. By the end of this tutorial, you’ll not only understand how to use the date_range function to its full potential, but also how to create custom date ranges with specified frequencies, intervals, and periods for a variety of real-world applications.

So, put on your learning cap and buckle up for an engaging journey into the fantastic realm of Pandas and its date_range function.

The Pandas Date Range Function

Let’s take a look at the Pandas date_range function available in Pandas. The function provides a large number of different parameters and default arguments.

# Understanding the Pandas date_range Function
pd.date_range(start=None, end=None, periods=None, freq=None, tz=None, normalize=False, name=None, inclusive=None)

Before going further, let’s break down these parameters a bit further. It’s important to note that exactly three of the following four parameters must be specified for the function to work: start=, end=, periods=, and freq=.

Parameter	Description	Default Argument	Accepted Values
start	The left bound for generating dates	None	string or datetime-like
end	The right bound for generating dates	None	string or datetime-like
periods	The number of periods to generate	None	int
freq	Frequencies to use to generate ranges	‘D‘	string or Dateoffset
tz	The time zone name for timezone-aware date-time values	None	string or timezone info
normalize	Whether to normalize start/end dates to midnight before generating the date range	False	boolean
name	Name of the resulting DatetimeIndex	None	string
inclusive	Which boundaries to include	'both'	{“both”, “neither”, “left”, “right”}

The function replaced the former closed= parameter with the much more powerful inclusive= parameter in January 2022 in version 1.4.

Let’s now dive into creating our first date range, using the Pandas date_range() function.

Creating a Simple Date Range with Pandas date_range

The simplest type of date range we can create with the Pandas date_range() function is to provide a start date, end date, and a frequency (which defaults to “D” for day). Let’s see how we can create a date range that includes the days between July 1, 2023 and July 7, 2023:

# Create a Simple Date Range in Pandas
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-07-07')
print(dates)

# Returns:
# DatetimeIndex(['2023-07-01', '2023-07-02', '2023-07-03', '2023-07-04',
            #    '2023-07-05', '2023-07-06', '2023-07-07'],
            #   dtype='datetime64[ns]', freq='D')

In the code block above, we create a Pandas date range object using the pd.date_range() function. In this case, we passed in only two arguments, those corresponding to the start= and end= parameters. By default, the function will use a frequency of 'D', meaning it separates each value by a day.

Let’s explore this dates object a little bit further by printing out its type:

# Checking the Type of a Date Range Object
print(type(dates))

# Returns:
# <class 'pandas.core.indexes.datetimes.DatetimeIndex'>

We can see that by inspecting the type of object that it returns a DatetimeIndex. This means that Pandas creates a very performant object.

Let’s look at some other types of date ranges that we can create, by customizing the frequencies used.

Creating Date Ranges with Custom Frequencies in Pandas

By default, Pandas uses a frequency of 'D', meaning that each item is one day apart. However, we can also specify our own frequencies by using a frequency string. The table below breaks down a few of the important frequency strings. This is similar to accessing date parts of a date in Pandas.

Alias	Description
B	business day frequency
C	custom business day frequency
D	calendar day frequency
W	weekly frequency
M	month end frequency
SM	semi-month end frequency (15th and end of month)
BM	business month end frequency
BH	business hour frequency
H	hourly frequency
T, min	minutely frequency

Let’s see how we can create a date range using the Pandas date_range() function where the values are split by semi-month frequency. We’ll create a date range from July 1, 2023 to September 31, 2023:

# Create a Date Range in Pandas with a Custom Frequency
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-08-31', freq='SM')
print(dates)

# Returns:
# DatetimeIndex(['2023-07-15', '2023-07-31', '2023-08-15', '2023-08-31'], dtype='datetime64[ns]', freq='SM-15')

In the code block above, we passed the start and end dates from July 1, 2023, to September 31, 2023. We used a frequency of semi-monthly dates, which uses the 15th of a month and the last day of a month. Because of this, the first of July is ignored. You can learn more about custom frequency strings by checking out the official documentation.

Using a Multiple of a Custom Frequency in Pandas date_range

We can take this one step further by specifying multiples of a custom frequency. For example, if we wanted to create a date range that skips every second day, we could use freq='2D'. Let’s see how we can replicate our earlier example with this frequency:

# Create a Custom Date Range in Pandas
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-07-07', freq='2D')
print(dates)

# Returns:
# DatetimeIndex(['2023-07-01', '2023-07-03', '2023-07-05', '2023-07-07'], dtype='datetime64[ns]', freq='2D')

In the code block above, we specified a frequency of '2D', which represents two-days. This means that we start on the first day specified, then generate every second day until the end. This process is much easier than adding dates to a date in a Pandas.

Creating Date Ranges with Specific Periods

So far, we have explored using start and end dates when creating a date range. This means that Pandas determines how many values to include. We can also specify the number of values to generate by using the periods= parameter.

Let’s see how we can create a date range that contains five values between July 1-20, 2023:

# Create a Custom Date Range with Specific Periods
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-07-20', periods=5)
print(dates)

# Returns:
# DatetimeIndex(['2023-07-01 00:00:00', '2023-07-05 18:00:00',
#                '2023-07-10 12:00:00', '2023-07-15 06:00:00',
#                '2023-07-20 00:00:00'],
            #   dtype='datetime64[ns]', freq=None)

In the code block above, we specified three parameters: start, end, and periods. Because of this, we didn’t specify the freq= parameter, meaning that it’s up to Pandas to determine what frequency to use!

Similarly, we can not specify the end of a date range, allowing us to specify the periods and frequency. Let’s explore this in the following section.

Creating Date Ranges with Specific Periods and Frequencies

Because the Pandas date_range() function requires three of the four parameters of start=, end=, periods=, and freq=, we can omit the end= parameter. This allows us to specify a start value, a frequency and a number of periods.

Let’s see what this can look like:

# Create a Custom Date Range with Specific Periods and Frequencies
import pandas as pd
dates = pd.date_range('2023-07-01', freq='B', periods=5)
print(dates)

# Returns:
# DatetimeIndex(['2023-07-03', '2023-07-04', '2023-07-05', '2023-07-06',
#                '2023-07-07'],
#               dtype='datetime64[ns]', freq='B')

In the code block above, we specified that we wanted to create a date range containing business days only, starting on July 1, 2023 for five periods. Because July 1, 2023 was a Saturday, the range actually starts on July 3, 2023.

Changing the Boundaries of a Pandas Date Range

By default, the Pandas date_range function will include both the start and end dates of the range. This is because the Pandas uses inclusive='both'. We can pass in the following options to modify this behavior:

• “both”, which includes both values
• “neither”, which excludes both values
• “left”, which includes only the left value
• “right”, which includes only the right value

Let’s see how we can omit both of the values by replicating our first example:

# Modifying Edge Behavior in a Pandas Date Range
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-07-07', inclusive='neither')
print(dates)

# Returns:
# DatetimeIndex(['2023-07-02', '2023-07-03', '2023-07-04', '2023-07-05',
#                '2023-07-06'],
#               dtype='datetime64[ns]', freq='D')

In the example above, we passed in a daily frequency from July 1 to July 7, 2023. However, we changed the inclusive= parameter to omit both sides of the range. Because of this, both the start and the end values are excluded.

Including Time Zones When Creating a Pandas Date Range

By default, the values in a Pandas date range will be timezone-naive, meaning that timezone information isn’t captured. We can specify a particular timezone by using the name of the timezone that we want to use. For example, let’s specify the Eastern US timezone by passing in 'US/Eastern' as the timezone.

In order to specify a timezone by using the tz= parameter. Let’s see what this looks like below:

# Create a Date Range in Pandas with Timezones
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-07-07', tz='US/Eastern')
print(dates)

# Returns:
# DatetimeIndex(['2023-07-01 00:00:00-04:00', '2023-07-02 00:00:00-04:00',
#                '2023-07-03 00:00:00-04:00', '2023-07-04 00:00:00-04:00',
#                '2023-07-05 00:00:00-04:00', '2023-07-06 00:00:00-04:00',
#                '2023-07-07 00:00:00-04:00'],
#               dtype='datetime64[ns, US/Eastern]', freq='D')

We can see that the values in the resulting date range above now include timezone information, specific to the US/Eastern timezone.

Changing the Name of the Index of a Pandas Date Range

In this final section, we’ll explore how to change the name of the resulting index. Because the Pandas date_range() function returns an index-style object, this will modify the underlying structure. Let’s see how we can specify an index name using the name= parameter:

# Create a Date Range in Pandas with an Index Name
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-07-07', name='Date')
print(dates)

# Returns:
# DatetimeIndex(['2023-07-01', '2023-07-02', '2023-07-03', '2023-07-04',
#                '2023-07-05', '2023-07-06', '2023-07-07'],
#               dtype='datetime64[ns]', name='Date', freq='D')

In the example above, we can see that the name= attribute is now also included in the date range. When we create a DataFrame with this, this label is also applied to the index. Let’s see what looks like:

# Create a DateFrame in Pandas with an Index Name
import pandas as pd
df = pd.DataFrame(range(7), columns=['Num'], index=pd.date_range('2023-07-01', '2023-07-07', name='Date'))
print(df)

# Returns:
#             Num
# Date           
# 2023-07-01    0
# 2023-07-02    1
# 2023-07-03    2
# 2023-07-04    3
# 2023-07-05    4
# 2023-07-06    5
# 2023-07-07    6

We can see in the DataFrame above that the index now has a name, 'Date'.

Conclusion: Creating Date Ranges with Pandas

In conclusion, we’ve successfully covered the fundamentals of the Pandas date_range function, delving into its numerous applications and customizations that allow us to tackle a wide variety of time series data challenges with ease. We explored everything from crafting custom date ranges with specified frequencies and periods, to fine-tuning timezones and index names to better fit our requirements.

You can learn more about the function by visiting the official documentation.