0
# Holiday Support
1

2
Built-in holiday calendars for multiple countries and functionality for creating custom holiday definitions with flexible windows and effects. Supports automatic holiday detection and custom holiday DataFrame creation.
3

4
## Capabilities
5

6
### Country Holiday Functions
7

8
Built-in support for holidays from multiple countries.
9

10
```python { .api }
11
def get_holiday_names(country):
12
    """
13
    Get all possible holiday names for a specific country.
14

15
    Parameters:
16
    - country: str, country name (e.g., 'US', 'UK', 'Germany', 'France', 'Italy')
17

18
    Returns:
19
    - list, list of holiday names available for the country
20
    """
21

22
def make_holidays_df(year_list, country, province=None, state=None):
23
    """
24
    Create a holidays DataFrame for specified years and country.
25

26
    Parameters:
27
    - year_list: list, list of years to include holidays for
28
    - country: str, country name for holiday calendar  
29
    - province: str, province/region name for location-specific holidays (optional)
30
    - state: str, state name for location-specific holidays (optional)
31

32
    Returns:
33
    - DataFrame with columns: 'ds' (date), 'holiday' (name), and optional
34
      'lower_window', 'upper_window', 'prior_scale' columns
35
    """
36

37
def get_country_holidays_class(country):
38
    """
39
    Get the holidays class for a specific country.
40

41
    Parameters:
42
    - country: str, country name
43

44
    Returns:
45
    - class, holidays class for the country (from holidays library)
46
    """
47
```
48

49
## Usage Examples
50

51
### Basic Country Holidays
52

53
```python
54
from prophet import Prophet
55
from prophet.make_holidays import make_holidays_df, get_holiday_names
56

57
# See available holidays for US
58
us_holidays = get_holiday_names('US')
59
print("US Holidays:", us_holidays)
60

61
# Create holidays DataFrame for multiple years
62
holidays_df = make_holidays_df(
63
    year_list=[2019, 2020, 2021, 2022], 
64
    country='US'
65
)
66
print(holidays_df.head())
67

68
# Use holidays in Prophet model
69
model = Prophet(holidays=holidays_df)
70
model.fit(df)
71

72
# Or add using built-in method
73
model = Prophet()
74
model.add_country_holidays('US')
75
model.fit(df)
76
```
77

78
### State/Province Specific Holidays
79

80
```python
81
# Get holidays for specific US state
82
california_holidays = make_holidays_df(
83
    year_list=[2020, 2021, 2022],
84
    country='US',
85
    state='CA'
86
)
87

88
# Get holidays for Canadian province  
89
ontario_holidays = make_holidays_df(
90
    year_list=[2020, 2021, 2022],
91
    country='Canada',
92
    province='ON'
93
)
94

95
# Use in model
96
model = Prophet(holidays=california_holidays)
97
model.fit(df)
98
```
99

100
### Custom Holiday Effects
101

102
```python
103
import pandas as pd
104

105
# Create custom holidays DataFrame with custom effects
106
custom_holidays = pd.DataFrame({
107
    'ds': pd.to_datetime(['2020-07-04', '2020-12-25', '2021-07-04', '2021-12-25']),
108
    'holiday': ['july_4th', 'christmas', 'july_4th', 'christmas'],
109
    'lower_window': [-1, -2, -1, -2],  # Days before holiday
110
    'upper_window': [1, 1, 1, 1],      # Days after holiday
111
    'prior_scale': [15, 20, 15, 20]    # Custom prior scales
112
})
113

114
# Use custom holidays
115
model = Prophet(holidays=custom_holidays)
116
model.fit(df)
117

118
# Combine built-in and custom holidays
119
builtin_holidays = make_holidays_df([2020, 2021], 'US')
120
all_holidays = pd.concat([builtin_holidays, custom_holidays], ignore_index=True)
121

122
model = Prophet(holidays=all_holidays)
123
model.fit(df)
124
```
125

126
### International Holiday Support
127

128
```python
129
# Various country examples
130
countries = ['US', 'UK', 'Germany', 'France', 'Italy', 'Japan', 'India']
131

132
for country in countries:
133
    try:
134
        holidays = get_holiday_names(country)
135
        print(f"{country}: {len(holidays)} holidays available")
136
        
137
        # Create sample holidays DataFrame
138
        country_holidays = make_holidays_df([2021, 2022], country)
139
        print(f"  Sample holidays for {country}:")
140
        print(f"  {country_holidays['holiday'].unique()[:5]}")  # First 5 holidays
141
        print()
142
    except Exception as e:
143
        print(f"Error getting holidays for {country}: {e}")
144
```
145

146
### Holiday Effect Analysis
147

148
```python
149
# After fitting model with holidays, analyze their effects
150
model = Prophet()
151
model.add_country_holidays('US')
152
model.fit(df)
153

154
forecast = model.predict(future)
155

156
# Check if holiday components are in forecast
157
holiday_columns = [col for col in forecast.columns if 'holiday' in col.lower()]
158
print("Holiday effect columns:", holiday_columns)
159

160
# Plot holiday effects if using plot functions
161
from prophet.plot import plot_components
162
fig = plot_components(model, forecast)
163
# This will show individual holiday effects if present
164
```