Understanding Weekly Offsets in pandas: pandas.tseries.offsets.Week.n

Data Offsets in pandas

pandas provides a powerful mechanism for working with time series data through data offsets. These offsets represent relative changes in time units (e.g., days, weeks, months) and are used to shift dates or generate sequences of dates.

pandas.tseries.offsets.Week

The Week class specifically represents a weekly offset in pandas. It inherits from the base class DateOffset.

Week.n Attribute

Customization
You can modify n to represent any number of weeks you need. For example, Week(n=2) would represent a two-week offset.
Default Value
By default, n is set to 1, indicating a single week.
Purpose
The n attribute in Week controls the number of weeks represented by the offset.

Example

import pandas as pd

today = pd.Timestamp('2024-07-15')  # Today's date

# One week from today
one_week_later = today + Week(n=1)
print(one_week_later)  # Output: 2024-07-22

# Three weeks from today
three_weeks_later = today + Week(n=3)
print(three_weeks_later)  # Output: 2024-08-05

For more granular control over weekdays, consider using the WeekOfMonth offset.
When adding or subtracting a Week offset to a date, the day of the week is preserved (e.g., if today is Monday, one week later will also be a Monday).
Week.n allows you to flexibly define the number of weeks in the offset.

Shifting Dates by Multiple Weeks

import pandas as pd

# Start date
start_date = pd.Timestamp('2024-06-10')  # Monday, June 10th

# Shift by different numbers of weeks
week_1_later = start_date + Week(n=1)  # Monday, June 17th
week_2_later = start_date + Week(n=2)  # Monday, June 24th
week_3_later = start_date + Week(n=3)  # Monday, July 1st

print(week_1_later)
print(week_2_later)
print(week_3_later)

Generating a Date Range with Weekly Intervals

import pandas as pd

# Start and end dates
start_date = pd.Timestamp('2024-07-01')  # Monday, July 1st
end_date = pd.Timestamp('2024-07-29')  # Monday, July 29th

# Generate weekly dates (inclusive)
date_range = pd.date_range(start_date, end_date, freq='W')

print(date_range)  # Index(['2024-07-01', '2024-07-08', '2024-07-15', '2024-07-22', '2024-07-29'], dtype='datetime64[ns]')

Subtracting Weeks

import pandas as pd

# Start date
start_date = pd.Timestamp('2024-07-15')  # Monday, July 15th

# Shift back by two weeks
two_weeks_earlier = start_date - Week(n=2)  # Monday, July 1st

print(two_weeks_earlier)

import pandas.tseries.offsets as pdoffsets

# Start date on a weekend (Saturday)
start_date = pd.Timestamp('2024-07-13')  # Saturday

# Shift to the following Monday (normalize to weekday)
next_monday = start_date + pdoffsets.Week(n=1, normalize=True)

print(next_monday)  # Monday, July 22nd (normalized to following weekday)

WeekOfMonth

Syntax: pd.offsets.WeekOfMonth(weekday=weekday, week=week_num)
- weekday: Optional, specifies the day of the week (e.g., pd.offsets.MO for Monday). Defaults to the start day of the date being offset.
- week_num: The week number within the month (1 for first week, 2 for second, etc.).
More granular control: WeekOfMonth allows you to specify the week within a month (e.g., first week, second week, etc.).

Example

import pandas as pd

# Start date (Friday, 2024-07-12)
start_date = pd.Timestamp('2024-07-12')

# Go to the following Monday of the second week of August (2024-08-12)
offset = pd.offsets.WeekOfMonth(weekday=pd.offsets.MO, week=2)
next_monday = start_date + offset
print(next_monday)

Timedelta with Weeks

Syntax: pd.Timedelta(weeks=n)
Useful for simple offsets: If you only need a fixed number of weeks, a Timedelta with weeks as the unit can be concise.

Example

import pandas as pd

# Start date (Monday, 2024-07-15)
start_date = pd.Timestamp('2024-07-15')

# Go to three weeks later (Monday, 2024-08-05)
offset = pd.Timedelta(weeks=3)
three_weeks_later = start_date + offset
print(three_weeks_later)

Custom Offset Function

For complex scenarios: If you require more intricate weekly offset logic, create a custom function that takes a date and returns the desired offset date.

Custom Function: For unique weekly offset logic not covered by existing tools.
Timedelta(weeks=n): Suitable for simple, fixed-week offsets.
WeekOfMonth: Ideal for precise control over week number and weekday within a month.