Skip to content

DOC: update documentation for CustomBusinessHour #50182

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 5 commits into from
Dec 12, 2022
Merged

DOC: update documentation for CustomBusinessHour #50182

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
63e51f0
DOC add examples CustomBusinessHour I
natmokval Dec 10, 2022
2d72295
Update pandas/_libs/tslibs/offsets.pyx
natmokval Dec 11, 2022
4380049
DOC add examples CustomBusinessHour II
natmokval Dec 12, 2022
1bf675d
DOC add examples CustomBusinessHour III
natmokval Dec 12, 2022
9ea5981
Merge remote-tracking branch 'origin/main' into 49838-docs-custombusi…
natmokval Dec 12, 2022
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
83 changes: 78 additions & 5 deletions pandas/_libs/tslibs/offsets.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3619,6 +3619,8 @@ cdef class CustomBusinessHour(BusinessHour):
"""
DateOffset subclass representing possibly n custom business days.

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

Parameters
----------
n : int, default 1
Expand All @@ -3627,24 +3629,95 @@ cdef class CustomBusinessHour(BusinessHour):
Normalize start/end dates to midnight before generating date range.
weekmask : str, Default 'Mon Tue Wed Thu Fri'
Weekmask of valid business days, passed to ``numpy.busdaycalendar``.
holidays : list
List/array of dates to exclude from the set of valid business days,
passed to ``numpy.busdaycalendar``.
calendar : np.busdaycalendar
Calendar to integrate.
start : str, time, or list of str/time, default "09:00"
Start time of your custom business hour in 24h format.
end : str, time, or list of str/time, default: "17:00"
End time of your custom business hour in 24h format.
offset : timedelta, default timedelta(0)
Time offset to apply.
Copy link
Member

Choose a reason for hiding this comment

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

have you noticed whether this parameter has any effect, or is it unused?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I haven’t checked it yet, but I’ll do it. If the parameter has any effect, I’ll add an example.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

My checks show that the parameter offset hasn't any effect on how the CustomBusinessHour works. That is why I don’t mark it as a parameter of CustomBusinessHour.


Examples
--------
>>> from datetime import time
In the example below the default parameters give as the next business hour.

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

We can also change the start and the end of business hours.

>>> ts = pd.Timestamp(2022, 8, 5, 15)
>>> ts + pd.offsets.CustomBusinessHour(start="11:00")
Timestamp('2022-08-05 16:00:00')

>>> ts = pd.Timestamp(2022, 8, 5, 16)
>>> ts + pd.offsets.CustomBusinessHour(start="11:00")
Timestamp('2022-08-08 11:00:00')
>>> ts + pd.offsets.CustomBusinessHour(end=time(19, 0))

>>> from datetime import time as dt_time
>>> ts = pd.Timestamp(2022, 8, 5, 16)
>>> ts + pd.offsets.CustomBusinessHour(end=dt_time(19, 0))
Timestamp('2022-08-05 17:00:00')
>>> ts + pd.offsets.CustomBusinessHour(start=[time(9, 0), "20:00"],
... end=["17:00", time(22, 0)])
Timestamp('2022-08-05 20:00:00')

>>> from datetime import time as dt_time
>>> ts = pd.Timestamp(2022, 8, 5, 22)
>>> ts + pd.offsets.CustomBusinessHour(end=dt_time(19, 0))
Timestamp('2022-08-08 10:00:00')

In the example below the business hours start at the default value "09:00"
and end at "8:00".

>>> ts = pd.Timestamp(2022, 8, 5, 22)
>>> ts + pd.offsets.CustomBusinessHour(end="8:00")
Timestamp('2022-08-05 23:00:00')

>>> pd.offsets.CustomBusinessHour(end="8:00")
<CustomBusinessHour: CBH=09:00-08:00>

In the example below we devide our business day hours into several parts.

>>> import datetime as dt
>>> freq = pd.offsets.CustomBusinessHour(start=["06:00", "10:00", "15:00"],
... end=["08:00", "12:00", "17:00"])
>>> pd.date_range(dt.datetime(2022, 12, 9), dt.datetime(2022, 12, 13), freq=freq)
DatetimeIndex(['2022-12-09 06:00:00', '2022-12-09 07:00:00',
'2022-12-09 10:00:00', '2022-12-09 11:00:00',
'2022-12-09 15:00:00', '2022-12-09 16:00:00',
'2022-12-12 06:00:00', '2022-12-12 07:00:00',
'2022-12-12 10:00:00', '2022-12-12 11:00:00',
'2022-12-12 15:00:00', '2022-12-12 16:00:00'],
dtype='datetime64[ns]', freq='CBH')

Business days can be specified by ``weekmask`` parameter.

>>> import datetime as dt
>>> freq = pd.offsets.CustomBusinessHour(weekmask="Mon Wed Fri",
... start="10:00", end="13:00")
>>> pd.date_range(dt.datetime(2022, 12, 10), dt.datetime(2022, 12, 18), freq=freq)
DatetimeIndex(['2022-12-12 10:00:00', '2022-12-12 11:00:00',
'2022-12-12 12:00:00', '2022-12-14 10:00:00',
'2022-12-14 11:00:00', '2022-12-14 12:00:00',
'2022-12-16 10:00:00', '2022-12-16 11:00:00',
'2022-12-16 12:00:00'],
dtype='datetime64[ns]', freq='CBH')

In the example below we define custom holidays by using NumPy business day calendar.

>>> import datetime as dt
>>> bdc = np.busdaycalendar(holidays=['2022-12-12', '2022-12-14'])
>>> freq = pd.offsets.CustomBusinessHour(calendar=bdc, start="10:00", end="13:00")
>>> pd.date_range(dt.datetime(2022, 12, 10), dt.datetime(2022, 12, 18), freq=freq)
DatetimeIndex(['2022-12-13 10:00:00', '2022-12-13 11:00:00',
'2022-12-13 12:00:00', '2022-12-15 10:00:00',
'2022-12-15 11:00:00', '2022-12-15 12:00:00',
'2022-12-16 10:00:00', '2022-12-16 11:00:00',
'2022-12-16 12:00:00'],
dtype='datetime64[ns]', freq='CBH')
"""

_prefix = "CBH"
Expand Down