Detecting a US Holiday
Question:
What’s the simplest way to determine if a date is a U.S. bank holiday in Python? There seem to be various calendars and webservices listing holidays for various countries, but I haven’t found anything specific to banks in the U.S.
Answers:
Make sure date != one of these:
I’ve actually worked recently on a problem much like this one. The static holidays are rather trivial to generate (e.g. New Years Eve – December 31st, (cycle through years)). There are well defined algorithms out there to generate the floating holidays. Essentially you have a starting date (e.g. January 1st, 1900) and work from there. What I ended up implementing was a nth day of nth week of nth month algorithm (e.g. MLK day = 3rd Monday of January). Easter is a bit different to do, but again there are well defined algorithms for that already out there (Good Friday is trivial after you have January).
There’s a fairly decent book on this out there you may want to check out: Calendrical Calculations
Some general comments:
I don’t think that @ast4 really means “nth day of nth week of nth month algorithm”. The notion of “nth week in nth month” is mind-snapping (like the “ISO calendar”). I’ve never seen a holiday defined in terms of “nth week”. Martin Luther King Day is an example of the”Nth weekday in month” type of holiday:
MONDAY, ...., SATURDAY = range(7)
JAN, ....., DEC = range(1, 12)
Holiday("Martin L King's Birthday", type='floating',
ordinal=3, weekday=MON, month=JAN)
Holiday("Memorial Day", type='floating',
ordinal=-1, weekday=MON, month=MAY)
The USA doesn’t have Easter-related holidays. Definition is not difficult:
Holiday("Good Friday", type='moveable',
base='gregorian_easter', delta_days=-2)
Holiday("Easter Monday", etc, delta_days=1)
# Some states in Australia used to have Easter Tuesday (no kidding)
Holiday("Easter Tuesday", etc, delta_days=2)
The ‘base’ idea can be used to cater for lunar new year, in fact any holiday that is an offset from a base date that needs a special procedure to calculate it.
The so-called “static” holidays are not fixed when the “fixed” date is a Saturday or Sunday and may even vanish (no alternative day off work):
# Americans will get a day off on Friday 31 Dec 2010
# because 1 Jan 2011 is a Saturday.
Holiday("New Year's Day", type='fixed',
day=1, month=JAN, sat_adj=-1, sun_adj=????)
# Australia observes ANZAC Day on the day, with no day off
# if the fixed date falls on a weekend.
Holiday("ANZAC Day", type='fixed', day=25, month=APR, sat_adj=0, sun_adj=0)
# Two consecutive "fixed" holidays is OK; three would need re-thinking.
# Australia again:
Holiday("Christmas Day", type='fixed', day=25, month=DEC, sat_adj=2, sun_adj=1)
Holiday("Boxing Day", type='fixed', day=26, month=DEC, sat_adj=2, sun_adj=2)
I’m sure there are ways of specifying holidays that aren’t catered for by the above rules … any such news is welcome.
The Pandas package provides a convenient solution for this:
from pandas.tseries.holiday import USFederalHolidayCalendar
cal = USFederalHolidayCalendar()
holidays = cal.holidays(start='2014-01-01', end='2014-12-31').to_pydatetime()
if datetime.datetime(2014,01,01) in holidays:
print True
Use the holiday library in python.
pip install holidays
For USA holiday:
1. To check a date holiday or not.
from datetime import date
import holidays
# Select country
us_holidays = holidays.US()
# If it is a holidays then it returns True else False
print('01-01-2018' in us_holidays)
print('02-01-2018' in us_holidays)
# What holidays is it?
print(us_holidays.get('01-01-2018'))
print(us_holidays.get('02-01-2018'))
2. To list out all holidays in US:
from datetime import date
import holidays
# Select country
us_holidays = holidays.US()
# Print all the holidays in US in year 2018
for ptr in holidays.US(years = 2018).items():
print(ptr)
You can find holidays for any country you like the list of countries listed on my Blog.
My Blog on Holidays
I should caution contributors from thinking this is all solvable by an algorithm. Three examples:
- most Islamic holidays are lunar. The moon is predictable, some countries do this, but others explicitly require that the new moon be actually sighted in the country. Some even post people to the tops of tall mountains, tasked to try to spot the new moon. If the night is cloudy, the new moon may not be sighted, so the following day is not a holiday.
- a committee in China meets around November each year to decide on the number of holidays that will be given for Chinese New Year in mainland China the following February. As an added complication, because there are so many public holidays given for Chinese New Year, the Chinese Government sometimes nominates weekends after the holiday as working days, to boost economic activity.
- stock exchanges in India sometimes have a very short trading period at a weekend for auspicious religious reasons.
For this reason, there are companies that do this research, get the updates, and publish holidays via an API, for a fee. Users typically query that API every day in case new holidays are announced.
What’s the simplest way to determine if a date is a U.S. bank holiday in Python? There seem to be various calendars and webservices listing holidays for various countries, but I haven’t found anything specific to banks in the U.S.
Make sure date != one of these:
I’ve actually worked recently on a problem much like this one. The static holidays are rather trivial to generate (e.g. New Years Eve – December 31st, (cycle through years)). There are well defined algorithms out there to generate the floating holidays. Essentially you have a starting date (e.g. January 1st, 1900) and work from there. What I ended up implementing was a nth day of nth week of nth month algorithm (e.g. MLK day = 3rd Monday of January). Easter is a bit different to do, but again there are well defined algorithms for that already out there (Good Friday is trivial after you have January).
There’s a fairly decent book on this out there you may want to check out: Calendrical Calculations
Some general comments:
I don’t think that @ast4 really means “nth day of nth week of nth month algorithm”. The notion of “nth week in nth month” is mind-snapping (like the “ISO calendar”). I’ve never seen a holiday defined in terms of “nth week”. Martin Luther King Day is an example of the”Nth weekday in month” type of holiday:
MONDAY, ...., SATURDAY = range(7)
JAN, ....., DEC = range(1, 12)
Holiday("Martin L King's Birthday", type='floating',
ordinal=3, weekday=MON, month=JAN)
Holiday("Memorial Day", type='floating',
ordinal=-1, weekday=MON, month=MAY)
The USA doesn’t have Easter-related holidays. Definition is not difficult:
Holiday("Good Friday", type='moveable',
base='gregorian_easter', delta_days=-2)
Holiday("Easter Monday", etc, delta_days=1)
# Some states in Australia used to have Easter Tuesday (no kidding)
Holiday("Easter Tuesday", etc, delta_days=2)
The ‘base’ idea can be used to cater for lunar new year, in fact any holiday that is an offset from a base date that needs a special procedure to calculate it.
The so-called “static” holidays are not fixed when the “fixed” date is a Saturday or Sunday and may even vanish (no alternative day off work):
# Americans will get a day off on Friday 31 Dec 2010
# because 1 Jan 2011 is a Saturday.
Holiday("New Year's Day", type='fixed',
day=1, month=JAN, sat_adj=-1, sun_adj=????)
# Australia observes ANZAC Day on the day, with no day off
# if the fixed date falls on a weekend.
Holiday("ANZAC Day", type='fixed', day=25, month=APR, sat_adj=0, sun_adj=0)
# Two consecutive "fixed" holidays is OK; three would need re-thinking.
# Australia again:
Holiday("Christmas Day", type='fixed', day=25, month=DEC, sat_adj=2, sun_adj=1)
Holiday("Boxing Day", type='fixed', day=26, month=DEC, sat_adj=2, sun_adj=2)
I’m sure there are ways of specifying holidays that aren’t catered for by the above rules … any such news is welcome.
The Pandas package provides a convenient solution for this:
from pandas.tseries.holiday import USFederalHolidayCalendar
cal = USFederalHolidayCalendar()
holidays = cal.holidays(start='2014-01-01', end='2014-12-31').to_pydatetime()
if datetime.datetime(2014,01,01) in holidays:
print True
Use the holiday library in python.
pip install holidays
For USA holiday:
1. To check a date holiday or not.
from datetime import date
import holidays
# Select country
us_holidays = holidays.US()
# If it is a holidays then it returns True else False
print('01-01-2018' in us_holidays)
print('02-01-2018' in us_holidays)
# What holidays is it?
print(us_holidays.get('01-01-2018'))
print(us_holidays.get('02-01-2018'))
2. To list out all holidays in US:
from datetime import date
import holidays
# Select country
us_holidays = holidays.US()
# Print all the holidays in US in year 2018
for ptr in holidays.US(years = 2018).items():
print(ptr)
You can find holidays for any country you like the list of countries listed on my Blog.
My Blog on Holidays
I should caution contributors from thinking this is all solvable by an algorithm. Three examples:
- most Islamic holidays are lunar. The moon is predictable, some countries do this, but others explicitly require that the new moon be actually sighted in the country. Some even post people to the tops of tall mountains, tasked to try to spot the new moon. If the night is cloudy, the new moon may not be sighted, so the following day is not a holiday.
- a committee in China meets around November each year to decide on the number of holidays that will be given for Chinese New Year in mainland China the following February. As an added complication, because there are so many public holidays given for Chinese New Year, the Chinese Government sometimes nominates weekends after the holiday as working days, to boost economic activity.
- stock exchanges in India sometimes have a very short trading period at a weekend for auspicious religious reasons.
For this reason, there are companies that do this research, get the updates, and publish holidays via an API, for a fee. Users typically query that API every day in case new holidays are announced.