Skip to content

DOC: add examples to offsets CustomBusinessDay, Business/MonthBegin #51932

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 15, 2023
Merged

DOC: add examples to offsets CustomBusinessDay, Business/MonthBegin #51932

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
171198b
DOC: add examples to offsets CustomBusinessDay, BusinessMonthBegin, M…
natmokval Mar 13, 2023
785b415
DOC: add the parameter offset to CustomBusinessDay
natmokval Mar 14, 2023
034c699
Merge branch 'main' into add-examples-to-offsets
natmokval Mar 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 80 additions & 14 deletions pandas/_libs/tslibs/offsets.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2574,11 +2574,28 @@ cdef class MonthBegin(MonthOffset):
"""
DateOffset of one month at beginning.

MonthBegin goes to the next date which is a start of the month.
To get the start of the current month pass the parameter n equals 0.

See Also
--------
:class:`~pandas.tseries.offsets.DateOffset` : Standard kind of date increment.

Examples
--------
>>> ts = pd.Timestamp(2022, 1, 1)
>>> ts = pd.Timestamp(2022, 11, 30)
>>> ts + pd.offsets.MonthBegin()
Timestamp('2022-12-01 00:00:00')

>>> ts = pd.Timestamp(2022, 12, 1)
>>> ts + pd.offsets.MonthBegin()
Timestamp('2022-02-01 00:00:00')
Timestamp('2023-01-01 00:00:00')

If you want to get the start of the current month pass the parameter n equals 0:

>>> ts = pd.Timestamp(2022, 12, 1)
>>> ts + pd.offsets.MonthBegin(0)
Timestamp('2022-12-01 00:00:00')
"""
_prefix = "MS"
_day_opt = "start"
Expand Down Expand Up @@ -2616,16 +2633,26 @@ cdef class BusinessMonthBegin(MonthOffset):
"""
DateOffset of one month at the first business day.

BusinessMonthBegin goes to the next date which is the first business day
of the month. To get the first business day of the current month pass
the parameter n equals 0.

Examples
--------
>>> from pandas.tseries.offsets import BMonthBegin
>>> ts=pd.Timestamp('2020-05-24 05:01:15')
>>> ts + BMonthBegin()
Timestamp('2020-06-01 05:01:15')
>>> ts + BMonthBegin(2)
Timestamp('2020-07-01 05:01:15')
>>> ts + BMonthBegin(-3)
Timestamp('2020-03-02 05:01:15')
>>> ts = pd.Timestamp(2022, 11, 30)
>>> ts + pd.offsets.BMonthBegin()
Timestamp('2022-12-01 00:00:00')

>>> ts = pd.Timestamp(2022, 12, 1)
>>> ts + pd.offsets.BMonthBegin()
Timestamp('2023-01-02 00:00:00')

If you want to get the start of the current business month pass
the parameter n equals 0:

>>> ts = pd.Timestamp(2022, 12, 1)
>>> ts + pd.offsets.BMonthBegin(0)
Timestamp('2022-12-01 00:00:00')
"""
_prefix = "BMS"
_day_opt = "business_start"
Expand Down Expand Up @@ -3671,7 +3698,9 @@ cdef class Easter(SingleConstructorOffset):

cdef class CustomBusinessDay(BusinessDay):
"""
DateOffset subclass representing custom business days excluding holidays.
DateOffset subclass representing possibly n custom business days.

In CustomBusinessDay we can use custom weekmask, holidays, and calendar.

Parameters
----------
Expand All @@ -3685,13 +3714,50 @@ cdef class CustomBusinessDay(BusinessDay):
List/array of dates to exclude from the set of valid business days,
passed to ``numpy.busdaycalendar``.
calendar : np.busdaycalendar
Calendar to integrate.
offset : timedelta, default timedelta(0)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why remove offset? I think it works, e.g.

In [18]: pd.Timestamp(2022, 8, 5, 16) + pd.offsets.CustomBusinessDay(1)
Out[18]: Timestamp('2022-08-08 16:00:00')

In [19]: pd.Timestamp(2022, 8, 5, 16) + pd.offsets.CustomBusinessDay(1, offset=timedelta(days=1))
Out[19]: Timestamp('2022-08-09 16:00:00')

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the comment. It was my mistake, I thought offset doesn’t have an effect on CustomBusinessDay. I corrected the list of parameters and add an example for offset.

I noticed, that we don't have offset in the list of parameters in BusinessDay. Maybe it would be good to add it?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yup, sounds good, thanks for checking!

Time offset to apply.

Examples
--------
>>> ts = pd.Timestamp(2022, 8, 5)
>>> ts + pd.offsets.CustomBusinessDay(1)
Timestamp('2022-08-08 00:00:00')
In the example below the default parameters give the next business day.

>>> ts = pd.Timestamp(2022, 8, 5, 16)
>>> ts + pd.offsets.CustomBusinessDay()
Timestamp('2022-08-08 16:00:00')

Business days can be specified by ``weekmask`` parameter. To convert
the returned datetime object to its string representation
the function strftime() is used in the next example.

>>> import datetime as dt
>>> freq = pd.offsets.CustomBusinessDay(weekmask="Mon Wed Fri")
>>> pd.date_range(dt.datetime(2022, 12, 10), dt.datetime(2022, 12, 21),
... freq=freq).strftime('%a %d %b %Y %H:%M')
Index(['Mon 12 Dec 2022 00:00', 'Wed 14 Dec 2022 00:00',
'Fri 16 Dec 2022 00:00', 'Mon 19 Dec 2022 00:00',
'Wed 21 Dec 2022 00:00'],
dtype='object')

Using NumPy business day calendar you can define custom holidays.

>>> import datetime as dt
>>> bdc = np.busdaycalendar(holidays=['2022-12-12', '2022-12-14'])
>>> freq = pd.offsets.CustomBusinessDay(calendar=bdc)
>>> pd.date_range(dt.datetime(2022, 12, 10), dt.datetime(2022, 12, 25), freq=freq)
DatetimeIndex(['2022-12-13', '2022-12-15', '2022-12-16', '2022-12-19',
'2022-12-20', '2022-12-21', '2022-12-22', '2022-12-23'],
dtype='datetime64[ns]', freq='C')

If you want to shift the result on n day you can use the parameter ``offset``.

>>> pd.Timestamp(2022, 8, 5, 16) + pd.offsets.CustomBusinessDay(1)
Timestamp('2022-08-08 16:00:00')

>>> import datetime as dt
>>> ts = pd.Timestamp(2022, 8, 5, 16)
>>> ts + pd.offsets.CustomBusinessDay(1, offset=dt.timedelta(days=1))
Timestamp('2022-08-09 16:00:00')
"""

_prefix = "C"
Expand Down