NumPy | busday_offset method
Start your free 7-days trial now!
NumPy's busday_offset(~) method shifts the provided datetimes by a specific offset in valid days. Note that busday stands for business day, but we can specify what a "business" day is via the parameters.
Parameters
1. dates | array-like of datetime
The input datetimes. Datetimes are essentially strings formatted like so:
"2020-05-25"
2. offsets | array-like of int
The number of days to offset by.
3. roll | string | optional
How to deal with invalid dates prior to offsetting. The allowed values are as follows:
Value | Description |
|---|---|
raise | Throw an error. |
nat | Return a NaT (i.e. not-a-time) |
forward | Return the first valid date after this date |
following | Return the first valid date after this date |
backward | Return the last valid date before the this date |
preceding | Return the last valid date before the this date |
modifiedfollowing | If the first valid date after this date falls in the same month as this date, then return this date. Otherwise, return the last valid date before this date. |
modifiedpreceding | If the last valid date before this date falls in the same month as this date, then return this date. Otherwise, return the first valid date after the this date. |
By default, roll="raise". Look at the examples below for clarification.
3. weekmask | string or array-like of boolean | optional
The days of the week that are considered to be valid. You could either specify a string of length 7 with 0s representing invalid and 1s representing valid weekdays, from Monday to Sunday. For instance, "1111100" would mean that weekends (Saturday and Sunday) would be invalid dates. Also, instead of typing in binaries, you could also use three-character abbreviations like:
Mon Tue Wed Thu Fri Sat Sun
For instance, "Mon Wed Fri" would mean that only Mondays, Wednesdays and Fridays are valid dates, and all other weekdays are invalid.
Alternatively, you could provide an array of booleans of size 7, where True means that that corresponding weekday is valid, and False otherwise. For instance, [True,True,True,True,True,False,False] would again mean that weekends would be invalid dates.
By default, weekmask="1111100", that is, valid weekdays are from Monday to Friday (both inclusive).
4. holidays | array-like of datetime | optional
An array of datetimes that are deemed as invalid dates.
5. busdaycal | busdaycalender | optional
An busdaycalender object that specifies which dates are deemed as valid dates. If this parameter is provided, then you should not specify parameters weekmask and holidays.
6. out | Numpy array | optional
We can store the result in out, which saves memory space as a new Array is not created.
Return value
If a datetime is provided for begindates and enddates, then a single integer is returned. A Numpy array of integers that represent count of the dates that fall between the specified range.
Examples
Roll parameter
raise
Here we get an error because the date 2020-11-22 falls on a Sunday:
dates = ["2020-11-22", "2020-11-25", "2020-11-27"]np.busday_offset(dates, 2)
ValueError: Non-business day date in busday_offset
nat
dates = ["2020-11-22", "2020-11-25", "2020-11-27"]np.busday_offset(dates, 2, roll="nat")
array([ 'NaT', '2020-11-27', '2020-12-01'], dtype='datetime64[D]')
forward
dates = ["2020-11-22", "2020-11-25", "2020-11-27"]np.busday_offset(dates, 2, roll="forward")
array(['2020-11-25', '2020-11-27', '2020-12-01'], dtype='datetime64[D]')
As we've said, the first date 2020-11-22 is invalid since it falls on a Sunday. The roll="forward" parameter means that the first valid date after this date is returned, which in this case, is 2020-11-23 (a Monday). Next, the offset of 2 is applied to give us 2020-11-25.
backward
dates = ["2020-11-22", "2020-11-25", "2020-11-27"]np.busday_offset(dates, 2, roll="backward")
array(['2020-11-24', '2020-11-27', '2020-12-01'], dtype='datetime64[D]')
Again, the first date 2020-11-22 is invalid since it falls on a Sunday. The roll="backward" parameter means that the last valid date before this date is returned, which in this case, is 2020-11-20 (a Friday). Next, the offset of 2 valid days is applied, which entails completely skipping the invalid weekends (i.e. 21st and 22nd), and then applying the 2 days offset to give us 2020-11-24.
modifiedfollowing
dates = ["2020-05-30"]np.busday_offset(dates, 2, roll="modifiedfollowing")
array(['2020-06-02'], dtype='datetime64[D]')
Here, 2020-05-30 is a Saturday, which is invalid. The roll="modifiedfollowing" parameter looks for the first valid date after this date, which is 2020-06-01 (Monday). Since we'e crossed over to the subsequent month, modifiedfollowing requires that we go to the last valid date before 2020-05-30, which is 2020-05-29 (Friday). We then perform the offsetting; we shift by 2 valid days (ignoring all invalid days), which would ultimately give us 2020-06-02!
modifiedpreceding
The section here will be omitted here for brevity, but this is essentially just the reverse of modifiedfollowing.
To demonstrate how the other parameters work, we will use NumPy's is_busday(~) method instead.
Specifying a weekmask
np.is_busday(["2020-12-25", "2020-12-26", "2020-12-27"], "1111110")
array([ True, True, False])
Here, we're setting Sunday as an invalid date - if you check your calendar, you'll see that "2020-12-27" is a Sunday, so this is why we get a False for that entry.
Specifying holidays
Instead of specifying invalid dates, we can also specify just the valid dates and make all other dates invalid:
holidays = ["2020-12-25"]np.is_busday(["2020-12-25", "2020-12-26", "2020-12-27"], "1111111", holidays)
array([False, True, True])
Here, False is returned for 2020-12-25 since we specified that date as a holiday, and holidays are considered to be invalid dates.
Specifying a valid date
Instead of specifying invalid dates, we can also specify just the valid dates and make all other dates invalid:
bdc = np.busdaycalendar(weekmask="1111111", holidays=["2020-12-26"])np.is_busday(["2020-12-25", "2020-12-26", "2020-12-27"], busdaycal=bdc)
array([ True, False, True])
Here, busdaycalendar object specifies what dates are considered to be valid. It may be confusing here but the holidays used in the constructor of busdaycalendar is a list of valid datetimes.
