NumPy busday_count() function: Explained (5 examples)

Understanding the NumPy busday_count() function is essential for anyone working with time series data, particularly when calculations need to exclude weekends and possibly holidays. This function provides a powerful way to count business days between dates. This guide will take you through the nuances of busday_count(), complete with progressively complex examples.

Introduction to busday_count()

The busday_count() function in NumPy calculates the number of business days between two dates. It considers Saturdays and Sundays as weekends by default but can be customized to account for different weekends and public holidays.

Syntax:

numpy.busday_count(begindates, enddates, weekmask='1111100', holidays=[], busdaycal=None, out=None)

Parameters:

• begindates: array_like of datetime64[D], datetime.date, strings in ISO 8601 date format. The beginning dates from which to count business days.
• enddates: array_like of datetime64[D], datetime.date, strings in ISO 8601 date format. The end dates to count business days up to, but not including.
• weekmask: A seven-character string or array_like of booleans, indicating which days of the week are considered business days. The default '1111100' treats Saturday and Sunday as weekends.
• holidays: An array_like object of datetime64[D], indicating the dates that should be excluded from the set of business days.
• busdaycal: An instance of numpy.busdaycalendar, specifying the weekmask and holidays. If provided, it overrides weekmask and holidays.
• out: An ndarray object for the result, for cases where begindates and enddates are arrays of dates. It must have the same shape as the output.

Returns:

• count: An integer or array of integers indicating the number of business days between the begindates and enddates. If begindates and enddates are arrays, the return is an array with the count of business days for each pair.

Example 1: Basic Usage

Let’s start with the most straightforward use case of busday_count(): calculating the business days between two given dates.

import numpy as np

start_date = '2023-04-01'
end_date = '2023-04-10'

print(np.busday_count(start_date, end_date))

Output:

6

This calculation assumes the default weekend of Saturday and Sunday. The output tells us there are 6 business days between April 1st and 10th, 2023.

Example 2: Considering Weekends

You might be working in an environment where the weekend days differ. NumPy’s busday_count() accommodates different definitions of weekends through the weekmask parameter.

import numpy as np

weekmask = '1111100'  # Monday to Friday are considered business days
result = np.busday_count('2023-01-01', '2023-01-31', weekmask=weekmask)
print(result) 

Output:

22

Here, only Saturdays and Sundays are considered as non-business days, which is why you get 22 business days in January 2023.

Example 3: Accounting for Holidays

Public holidays are another factor that can affect the business day count. The busday_count() permits incorporating a list of holidays.

import numpy as np

holidays = ['2023-01-01', '2023-01-26']

start = '2023-01-01'
end = '2023-02-01'

print(np.busday_count(start, end, holidays=holidays))

Output:

21

Despite adding holidays, the count remains the same because our date range starts on a Sunday and one of the holidays falls on that day, which is already a non-business day.

Example 4: Custom Week Masks

To demonstrate the flexibility of busday_count(), we’ll create a more complex week mask that defines a business week from Sunday to Thursday, as observed in some countries.

import numpy as np

weekmask = '0111110'  # Sunday to Thursday are business days

result = np.busday_count('2023-01-01', '2023-01-31', weekmask=weekmask)
print(result)

Output:

20

With this custom week mask, the business day count adjusts to the specified working week. We see a deviation from the previous examples, highlighting the method’s versatility.

Example 5: Advanced – Combining Parameters

Lastly, we’ll combine everything – custom weekends, holidays, and complex date ranges to see the full capability of busday_count().

import numpy as np

weekmask = '0111110'
holidays = ['2023-01-02', '2023-01-26']

start = '2023-01-01'
end = '2023-03-01'

print(np.busday_count(start, end, weekmask=weekmask, holidays=holidays))

Output:

40

This advanced example clearly shows how busday_count() can be tailored to fit specific business contexts. By manipulating the weekmask and holidays, you achieve a highly customized business day count.

Conclusion

The busday_count() function is a potent tool for time series analysis in Python, made even more versatile by its configurability. By understanding how to lever its parameters, you can accurately account for business days across various international setups and complex scheduling scenarios. Thus, making your data analysis and forecasting more precise and meaningful.