Pandas' DateOffset object is a tool used for performing time offsets when processing date and time data.

The following are some key features and usages of DateOffset:

Basic Concepts

The DateOffset object is similar to Timedelta, but it follows calendar-based datetime rules rather than directly performing arithmetic calculations of a temporal nature. This means that DateOffset takes actual calendar days into account. For example, when dealing with dates that cross months or years, it correctly calculates the day differences, whereas Timedelta simply adds the specified number of days without considering changes in months and years.

Usage

DateOffset can perform date offset operations through arithmetic operators (such as +) or the apply method.

For example, you can use DateOffset like this to add months or hours:

Examples

ts = pd.Timestamp('2017-01-01 09:10:11')
ts + DateOffset(months=3)  # Add three months
ts + DateOffset(hours=2)   # Add two hours

If no parameters are specified, DateOffset() adds one calendar day by default:

ts + DateOffset()  # 默认增加一天

Supported Parameters

DateOffset supports multiple parameters, allowing you to specify time units to add or replace, such as years, months, weeks, days, hours, minutes, seconds, etc. These parameters can be added to the offset value (such as years, months, weeks, days, hours, minutes, seconds, etc.), or they can replace the offset value (such as year, month, day, weekday, hour, minute, second, etc.).

Special Methods

DateOffset also provides rollforward() and rollback() methods, which are used to roll dates forward or backward to the nearest valid date. For example, if you use a business day offset (BDay), it will skip weekends and roll directly to the next business day.

Examples

friday = pd.Timestamp('2022-01-05')
two_business_days = 2 * pd.offsets.BDay()
friday + two_business_days  # Add two business days, skipping weekends

Frequency Strings

DateOffset supports frequency strings or offset aliases, which can be passed in as the freq parameter. These frequency strings represent DateOffset objects and their subclasses, and they define the frequency of datetime indexes.

DateOffset is a very useful tool in Pandas for processing time series data, as it makes date and time offset operations more consistent with actual calendar rules.

Common Functions

DateOffset Constructor

Class/Method Description
pd.DateOffset(**kwargs) Create a DateOffset object, supporting custom time offsets.

Common DateOffset Subclasses

Class Description
pd.offsets.Day() Represents an offset of days.
pd.offsets.BDay() Represents an offset of business days (excluding weekends).
pd.offsets.Hour() Represents an offset of hours.
pd.offsets.Minute() Represents an offset of minutes.
pd.offsets.Second() Represents an offset of seconds.
pd.offsets.Milli() Represents an offset of milliseconds.
pd.offsets.Micro() Represents an offset of microseconds.
pd.offsets.MonthEnd() Represents an offset of the end of the month.
pd.offsets.MonthBegin() Represents an offset of the beginning of the month.
pd.offsets.YearEnd() Represents an offset of the end of the year.
pd.offsets.YearBegin() Represents an offset of the beginning of the year.
pd.offsets.QuarterEnd() Represents an offset of the end of the quarter.
pd.offsets.QuarterBegin() Represents an offset of the beginning of the quarter.
pd.offsets.Week() Represents an offset of weeks.
pd.offsets.WeekOfMonth() Represents an offset of the nth week of the month.

DateOffset Attributes

Attribute Description
DateOffset.name Returns the name of the DateOffset.
DateOffset.n Returns or sets the number of offsets.
DateOffset.normalize Returns or sets whether to normalize the time to midnight.

DateOffset Methods

Method Description
DateOffset.apply(other) Apply the offset to another datetime object.
DateOffset.rollforward(other) Roll the date forward to the next offset.
DateOffset.rollback(other) Roll the date backward to the previous offset.
DateOffset.is_anchored() Check whether the offset is anchored (i.e., whether it has a fixed frequency).
DateOffset.onOffset(date) Check whether the date is aligned with the offset.

Examples

Examples

import pandas as pd
from pandas.tseries.offsets import Day, BDay, MonthEnd

# Create DateOffset
offset = Day(3)
print(offset)  # Output <3 * Days>

# Apply DateOffset
date = pd.Timestamp('2023-01-01')
new_date = date + offset
print(new_date)  # Output 2023-01-04

# Use a common subclass
bday_offset = BDay(2)
new_bdate = date + bday_offset
print(new_bdate)  # Output 2023-01-05 (skipping weekends)

# Month-end offset
month_end_offset = MonthEnd()
new_month_end = date + month_end_offset
print(new_month_end)  # Output 2023-01-31

Detailed Parameter Description

pd.DateOffset()

Parameter Description
years Number of years offset.
months Number of months offset.
weeks Number of weeks offset.
days Number of days offset.
hours Number of hours offset.
minutes Number of minutes offset.
seconds Number of seconds offset.
milliseconds Number of milliseconds offset.
microseconds Number of microseconds offset.
nanoseconds Number of nanoseconds offset.

pd.offsets.BDay()

Parameter Description
n The number of offsets, defaulting to 1.
normalize Whether to normalize the time to midnight, defaulting toFalse。

pd.offsets.MonthEnd()

Parameter Description
n The number of offsets, defaulting to 1.
normalize Whether to normalize the time to midnight, defaulting toFalse。

For more detailed information, please refer toPandas Official Documentation。

Other Extensions