augment_holiday_signature

augment_holiday_signature(data, date_column, country_name='UnitedStates', reduce_memory=False, engine='pandas')

Engineers 4 different holiday features from a single datetime for 137 countries and 2 financial markets.

Note: Requires the holidays package to be installed. See https://pypi.org/project/holidays/ for more information.

Parameters

Name Type Description Default
data Union[pd.DataFrame, pd.core.groupby.generic.DataFrameGroupBy] The input DataFrame. required
date_column str The name of the datetime-like column in the DataFrame. required
country_name str The name of the country for which to generate holiday features. Defaults to United States holidays, but the following countries are currently available and accessible by the full name or ISO code: See NOTES. 'UnitedStates'
reduce_memory bool The reduce_memory parameter is used to specify whether to reduce the memory usage of the DataFrame by converting int, float to smaller bytes and str to categorical data. This reduces memory for large data but may impact resolution of float and will change str to categorical. Default is True. False
engine str The engine parameter is used to specify the engine to use for augmenting holidays. It can be either “pandas” or “polars”. - The default value is “pandas”. - When “polars”, the function will internally use the polars library for augmenting holidays. This can be faster than using “pandas” for large datasets. 'pandas'

Returns

Type Description
pd.DataFrame: A pandas DataFrame with three holiday-specific features: - is_holiday: (0, 1) indicator for holiday - before_holiday: (0, 1) indicator for day before holiday - after_holiday: (0, 1) indicator for day after holiday - holiday_name: name of the holiday

Notes

Any of the following are acceptable keys for country_name:

Available Countries Full Country Code
Albania Albania AL
Algeria Algeria DZ
American Samoa AmericanSamoa AS
Andorra Andorra AD
Angola Angola AO
Argentina Argentina AR
Armenia Armenia AM
Aruba Aruba AW
Australia Australia AU
Austria Austria AT
Azerbaijan Azerbaijan AZ
Bahrain Bahrain BH
Bangladesh Bangladesh BD
Barbados Barbados BB
Belarus Belarus BY
Belgium Belgium BE
Belize Belize BZ
Bolivia Bolivia BO
Bosnia and Herzegovina BosniaandHerzegovina BA
Botswana Botswana BW
Brazil Brazil BR
Brunei Brunei BN
Bulgaria Bulgaria BG
Burkina Faso BurkinaFaso BF
Burundi Burundi BI
Laos Laos LA
Latvia Latvia LV
Lesotho Lesotho LS
Liechtenstein Liechtenstein LI
Lithuania Lithuania LT
Luxembourg Luxembourg LU
Madagascar Madagascar MG
Malawi Malawi MW
Malaysia Malaysia MY
Maldives Maldives MV
Malta Malta MT
Marshall Islands MarshallIslands MH
Mexico Mexico MX
Moldova Moldova MD
Monaco Monaco MC
Montenegro Montenegro ME
Morocco Morocco MA
Mozambique Mozambique MZ
Namibia Namibia NA
Netherlands Netherlands NL
New Zealand NewZealand NZ
Nicaragua Nicaragua NI
Nigeria Nigeria NG
Northern Mariana Islands NorthernMarianaIslands MP
North Macedonia NorthMacedonia MK
Norway Norway NO
Pakistan Pakistan PK
Panama Panama PA
Paraguay Paraguay PY
Peru Peru PE
Philippines Philippines PH
Poland Poland PL
Portugal Portugal PT
Puerto Rico PuertoRico PR
Romania Romania RO
Russia Russia RU
San Marino SanMarino SM
Saudi Arabia SaudiArabia SA
Serbia Serbia RS
Singapore Singapore SG
Slovakia Slovakia SK
Slovenia Slovenia SI
South Africa SouthAfrica ZA
South Korea SouthKorea KR
Spain Spain ES
Sweden Sweden SE
Switzerland Switzerland CH
Taiwan Taiwan TW
Tanzania Tanzania TZ
Thailand Thailand TH
Tunisia Tunisia TN
Turkey Turkey TR
Ukraine Ukraine UA
United Arab Emirates UnitedArabEmirates AE
United Kingdom UnitedKingdom GB
United States Minor Outlying Islands UnitedStatesMinorOutlyingIslands UM
United States of America UnitedStatesofAmerica US
United States Virgin Islands UnitedStatesVirginIslands VI
Uruguay Uruguay UY
Uzbekistan Uzbekistan UZ
Vanuatu Vanuatu VU
Vatican City VaticanCity VA
Venezuela Venezuela VE
Vietnam Vietnam VN
Virgin Islands (U.S.) VirginIslandsUS VI
Zambia Zambia ZM
Zimbabwe Zimbabwe ZW

These are the Available Financial Markets:

Available Financial Markets Full Country Code
European Central Bank EuropeanCentralBank ECB
New York Stock Exchange NewYorkStockExchange XNYS

Example

import pandas as pd
import pytimetk as tk

# Make a DataFrame with a date column
start_date = '2023-01-01'
end_date = '2023-01-10'
df = pd.DataFrame(pd.date_range(start=start_date, end=end_date), columns=['date'])

# Add holiday features for US
tk.augment_holiday_signature(df, 'date', 'UnitedStates')
date is_holiday before_holiday after_holiday holiday_name
0 2023-01-01 1 1 0 New Year's Day
1 2023-01-02 1 0 1 New Year's Day (Observed)
2 2023-01-03 0 0 1 NaN
3 2023-01-04 0 0 0 NaN
4 2023-01-05 0 0 0 NaN
5 2023-01-06 0 0 0 NaN
6 2023-01-07 0 0 0 NaN
7 2023-01-08 0 0 0 NaN
8 2023-01-09 0 0 0 NaN
9 2023-01-10 0 0 0 NaN 
# Add holiday features for France
tk.augment_holiday_signature(df, 'date', 'France')
date is_holiday before_holiday after_holiday holiday_name
0 2023-01-01 1 0 0 New Year's Day
1 2023-01-02 0 0 1 NaN
2 2023-01-03 0 0 0 NaN
3 2023-01-04 0 0 0 NaN
4 2023-01-05 0 0 0 NaN
5 2023-01-06 0 0 0 NaN
6 2023-01-07 0 0 0 NaN
7 2023-01-08 0 0 0 NaN
8 2023-01-09 0 0 0 NaN
9 2023-01-10 0 0 0 NaN 
# Add holiday features for France
tk.augment_holiday_signature(df, 'date', 'France', engine='polars')
date is_holiday before_holiday after_holiday holiday_name
0 2023-01-01 1 0 0 New Year's Day
1 2023-01-02 0 0 1 NaN
2 2023-01-03 0 0 0 NaN
3 2023-01-04 0 0 0 NaN
4 2023-01-05 0 0 0 NaN
5 2023-01-06 0 0 0 NaN
6 2023-01-07 0 0 0 NaN
7 2023-01-08 0 0 0 NaN
8 2023-01-09 0 0 0 NaN
9 2023-01-10 0 0 0 NaN