Python Pandas - Date Functionality

Pandas - Date and Time Functionality

Pandas excels at working with time series data, which is crucial in fields like finance, economics, and data logging. Key functionalities include generating sequences of dates and times, converting frequencies, and performing time-based operations.

• Generating sequences of dates and timestamps.
• Converting time series data to different frequencies (e.g., daily to monthly).
• Handling time zones and date offsets.
• Performing time-based indexing and selection.

Creating a Range of Dates: pd.date_range()

The pd.date_range() function is the primary tool for creating sequences of dates and times (a DatetimeIndex). You typically specify a start date, an end date, and/or a number of periods, along with an optional frequency.

Syntax commonly involves combinations of start, end, periods, and freq.

Example 1: Specifying start date and number of periods (default frequency is daily ‘D’).

import pandas as pd

# Generate 5 dates starting from '2023-01-01'
date_index = pd.date_range('2023-01-01', periods=5)
print(date_index)

Output:

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

Example 2: Specifying start and end dates.

import pandas as pd

# Generate dates from start to end (inclusive)
date_index = pd.date_range(start='2023-03-01', end='2023-03-05')
print(date_index)

Output:

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

Note: Pandas uses nanosecond resolution (datetime64[ns]) for timestamps.

Changing the Date Frequency (freq)

The freq argument allows you to specify the interval between dates. Common frequencies include ‘D’ (daily), ‘B’ (business daily), ‘W’ (weekly), ‘M’ (month end), ‘MS’ (month start), ‘Q’ (quarter end), ‘A’ (year end), ‘H’ (hourly), ‘T’ or ‘min’ (minutely), ‘S’ (secondly).

Example: Generating month-end dates.

import pandas as pd

# Generate 5 month-end dates starting from 2023-01
# Note: '1/1/2023' sets the starting point for period calculation
monthly_index = pd.date_range('1/1/2023', periods=5, freq='M')
print(monthly_index)

Output:

DatetimeIndex(['2023-01-31', '2023-02-28', '2023-03-31', '2023-04-30',
               '2023-05-31'],
              dtype='datetime64[ns]', freq='M')

Example: Generating business day dates (excludes weekends).

import pandas as pd

# Generate business days between two dates
# Example: Friday March 3rd, 2023 to Thursday March 9th, 2023
business_days = pd.date_range(start='2023-03-03', end='2023-03-09', freq='B')
print(business_days)

Output:

DatetimeIndex(['2023-03-03', '2023-03-06', '2023-03-07', '2023-03-08',
               '2023-03-09'],
              dtype='datetime64[ns]', freq='B')

Observe that Saturday (March 4th) and Sunday (March 5th) are excluded from the sequence because the frequency is ‘B’ (business day).

bdate_range() - Business Date Ranges (Legacy)

Pandas previously had a separate bdate_range() function, specifically for business days. While it might still work, the recommended and more flexible approach is to use pd.date_range() with freq='B'.

import pandas as pd

# Using date_range with freq='B' (Recommended)
business_days_recommended = pd.date_range('2023-01-01', periods=5, freq='B')
print("Recommended (date_range with freq='B'):")
print(business_days_recommended)

# Using bdate_range (Legacy)
try:
    business_days_legacy = pd.bdate_range('2023-01-01', periods=5)
    print("\nLegacy (bdate_range):")
    print(business_days_legacy)
except AttributeError:
    print("\npd.bdate_range might be deprecated or removed in this Pandas version.")

Output (may vary slightly depending on Pandas version):

Recommended (date_range with freq='B'):
DatetimeIndex(['2023-01-02', '2023-01-03', '2023-01-04', '2023-01-05',
               '2023-01-06'],
              dtype='datetime64[ns]', freq='B')

Legacy (bdate_range):
DatetimeIndex(['2023-01-02', '2023-01-03', '2023-01-04', '2023-01-05',
               '2023-01-06'],
              dtype='datetime64[ns]', freq='B')

Note: Using Python’s standard datetime objects or pd.Timestamp is preferred over the deprecated pd.datetime.

import pandas as pd
from datetime import datetime

start_dt = datetime(2023, 1, 1)
end_dt = pd.Timestamp('2023-01-05') # pd.Timestamp is often convenient

date_index = pd.date_range(start_dt, end_dt)
print(date_index)

Output:

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

Common Frequency Offset Aliases

Pandas provides string aliases for many common time series frequencies used in the freq argument:

Alias	Description	Alias	Description
B	business day frequency	QS	quarter start frequency
D	calendar day frequency	BQS	business quarter start freq.
W	weekly frequency (Sunday default)	A	annual (year) end frequency
W-MON	weekly frequency (Monday)	AS	annual (year) start frequency
M	month end frequency	BA	business year end frequency
MS	month start frequency	BAS	business year start frequency
BM	business month end frequency	BH	business hour frequency (9-5)
BMS	business month start frequency	H	hourly frequency
Q	quarter end frequency	T / min	minutely frequency
BQ	business quarter end frequency	S	secondly frequency
L / ms	milliseconds	U / us	microseconds
N	nanoseconds

You can also combine these with multipliers, e.g., ‘2H’ for every 2 hours, ‘5D’ for every 5 days. See the Pandas documentation for a comprehensive list of frequency strings and offset objects.