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 if 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

Return a string representing the frequency.

kwds

Return a dict of extra parameters for the offset.

name

Return a string representing the base frequency.

n

nanos

normalize

rule_code

Methods

copy

Return a copy of the frequency.

is_anchored

Return boolean whether the frequency is a unit frequency (n=1).

is_month_end

Return boolean whether a timestamp occurs on the month end.

is_month_start

Return boolean whether a timestamp occurs on the month start.

is_on_offset

Return boolean whether a timestamp intersects with this frequency.

is_quarter_end

Return boolean whether a timestamp occurs on the quarter end.

is_quarter_start

Return boolean whether a timestamp occurs on the quarter start.

is_year_end

Return boolean whether a timestamp occurs on the year end.

is_year_start

Return boolean whether a timestamp occurs on the year start.

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.