pandas.tseries.offsets.DateOffset

class pandas.tseries.offsets.DateOffset

Standard kind of date increment used for a date range.

Works exactly like the keyword argument form of relativedelta. Note that the positional argument form of relativedelata is not supported. Use of the keyword n is discouraged– you would be better off specifying n in the keywords you use, but regardless it is there for you. n is needed for DateOffset subclasses.

DateOffset works as follows. Each offset specify a set of dates that conform to the DateOffset. For example, Bday defines this set to be the set of dates that are weekdays (M-F). To test if a date is in the set of a DateOffset dateOffset we can use the is_on_offset method: dateOffset.is_on_offset(date).

If a date is not on a valid date, the rollback and rollforward methods can be used to roll the date to the nearest valid date before/after the date.

DateOffsets can be created to move dates forward a given number of valid dates. For example, Bday(2) can be added to a date to move it two business days forward. If the date does not start on a valid date, first it is moved to a valid date. Thus pseudo code is:

def __add__(date):

date = rollback(date) # does nothing if date is valid return date + <n number of periods>

When a date offset is created for a negative number of periods, the date is first rolled forward. The pseudo code is:

def __add__(date):

date = rollforward(date) # does nothing is date is valid return date + <n number of periods>

Zero presents a problem. Should it roll forward or back? We arbitrarily have it rollforward:

date + BDay(0) == BDay.rollforward(date)

Since 0 is a bit weird, we suggest avoiding its use.

Besides, adding a DateOffsets specified by the singular form of the date component can be used to replace certain component of the timestamp.

Parameters
nint, default 1

The number of time periods the offset represents. If specified without a temporal pattern, defaults to n days.

normalizebool, default False

Whether to round the result of a DateOffset addition down to the previous midnight.

**kwds

Temporal parameter that add to or replace the offset value.

Parameters that add to the offset (like Timedelta):

  • years

  • months

  • weeks

  • days

  • hours

  • minutes

  • seconds

  • milliseconds

  • microseconds

  • nanoseconds

Parameters that replace the offset value:

  • year

  • month

  • day

  • weekday

  • hour

  • minute

  • second

  • microsecond

  • nanosecond.

See also

dateutil.relativedelta.relativedelta

The relativedelta type is designed to be applied to an existing datetime an can replace specific components of that datetime, or represents an interval of time.

Examples

>>> from pandas.tseries.offsets import DateOffset
>>> ts = pd.Timestamp('2017-01-01 09:10:11')
>>> ts + DateOffset(months=3)
Timestamp('2017-04-01 09:10:11')
>>> ts = pd.Timestamp('2017-01-01 09:10:11')
>>> ts + DateOffset(months=2)
Timestamp('2017-03-01 09:10:11')
>>> ts + DateOffset(day=31)
Timestamp('2017-01-31 09:10:11')
>>> ts + pd.DateOffset(hour=8)
Timestamp('2017-01-01 08:10:11')

Attributes

base

Returns a copy of the calling offset object with n=1 and all other attributes equal.

freqstr

kwds

n

name

nanos

normalize

rule_code

Methods

__call__(*args, **kwargs)

Call self as a function.

rollback

Roll provided date backward to next offset only if not on offset.

rollforward

Roll provided date forward to next offset only if not on offset.

apply

apply_index

copy

isAnchored

is_anchored

is_month_end

is_month_start

is_on_offset

is_quarter_end

is_quarter_start

is_year_end

is_year_start

onOffset