Modelling Events¶
Often in forecasting problems, we need to consider recurring special events. These are supported
by neural_prophet
. These events can be added both in additive format and multiplicative format.
To provide the information of events into the model, the user has to create a dataframe which has the
column ds
corresponding to the event dates and the column event
which contains
the names of the events on specified dates. In the following example we have created the
dataframe named history_events_df
which contains these events information.
playoffs_history = pd.DataFrame({
'event': 'playoff',
'ds': pd.to_datetime(['2008-01-13', '2009-01-03', '2010-01-16',
'2010-01-24', '2010-02-07', '2011-01-08',
'2013-01-12', '2014-01-12', '2014-01-19',
'2014-02-02', '2015-01-11', '2016-01-17']),
})
superbowls_history = pd.DataFrame({
'event': 'superbowl',
'ds': pd.to_datetime(['2010-02-07', '2014-02-02']),
})
history_events_df = pd.concat((playoffs_history, superbowls_history))
The first few rows of the history_events_df
dataframe looks like below.
event |
ds |
|
---|---|---|
0 |
playoff |
2008-01-13 00:00:00 |
1 |
playoff |
2009-01-03 00:00:00 |
2 |
playoff |
2010-01-16 00:00:00 |
3 |
playoff |
2010-01-24 00:00:00 |
4 |
playoff |
2010-02-07 00:00:00 |
5 |
playoff |
2011-01-08 00:00:00 |
For forecasting, we also need to provide the future dates of these events used to train the model. You can either include these in the same events dataframe that was created before for fitting the model, or in a new dataframe as follows.
playoffs_future = pd.DataFrame({
'event': 'playoff',
'ds': pd.to_datetime(['2016-01-21', '2016-02-07'])
})
superbowl_future = pd.DataFrame({
'event': 'superbowl',
'ds': pd.to_datetime(['2016-01-23', '2016-02-07'])
})
future_events_df = pd.concat((playoffs_future, superbowl_future))
Once the events dataframes have been created, the NeuralProphet
object should be created and the
events configs should be added. This is done using the add_events
function of the NeuralProphet
class.
m = NeuralProphet(
n_forecasts=10,
yearly_seasonality=False,
weekly_seasonality=False,
daily_seasonality=False,
)
m = m.add_events(["superbowl", "playoff"])
After that, we need to convert the events data in the previously created dataframes into the binary input
data expected by the model. This can be done by calling the create_df_with_events
function by passing
original time series dataframe along with the created history_events_df
.
history_df = m.create_df_with_events(df, history_events_df)
This returns a dataframe in the following format.
ds |
y |
superbowl |
playoff |
|
---|---|---|---|---|
0 |
2007-12-10 00:00:00 |
9.59076 |
0 |
0 |
1 |
2007-12-11 00:00:00 |
8.51959 |
0 |
0 |
2 |
2007-12-12 00:00:00 |
8.18368 |
0 |
0 |
3 |
2007-12-13 00:00:00 |
8.07247 |
0 |
0 |
4 |
2007-12-14 00:00:00 |
7.89357 |
0 |
0 |
After that, we can simply fit the model as below by providing to the fit
function, the created history_df
.
metrics = m.fit(history_df, freq="D")
forecast = m.predict(df=history_df)
<The produced forecasts look like below. The 10 step-ahead forecasts are available in the yhat1 column. The components from the individual events are available in the event_playoff and event_superbowl columns and their agrgegated effect is shown on the events_additive column>
Once the forecasting is done, the different components can be plotted like below. All events are plotted as one
component, the Additive Events
{: style=”height:400px”}
The model coefficients would look like below.
{: style=”height:550px”}
Multiplicative Events¶
The default mode for events in neural_prophet
is additive. However, events can also be modelled
in a multiplicative format. For this, when adding the events configs to the NeuralProphet
object,
we need to set the mode
to multiplicative
as below.
m = m.add_events(["superbowl", "playoff"], mode="multiplicative")
All the other steps are the same as for the additive
mode. Now, when you plot the components,
the event components will appear as percentages.
{: style=”height:400px”}
Event Windows¶
You can also provide windows for events. This way, you can consider the days around a
particular event also as special events by providing the arguments lower_window
and
upper_window
as appropriate to the add_events
function of the NeuralProphet
object.
By default, the values for these windows are 0
, which means windows are not considered.
m = m.add_events(["superbowl", "playoff"], lower_window=-1, upper_window=1)
According to this specification, for both superbowl
and playoff
events, three special events will be
modelled, the event date, the previous day and the next day. These will be visible in the component plots as below.
{: style=”height:550px”}
In the parameters plot too, there will now be superbowl_+1
and superbowl_-1
which correspond to the coefficients of the
day following and previous to the superbowl
event. The playoff
event also has the same new coefficients.
{: style=”height:550px”}
If you want to define different windows for the individual events, this can also be done as follows.
m = m.add_events("superbowl", lower_window=-1, upper_window=1)
m = m.add_events("playoff", upper_window=2)
In the above example, for the playoff
event, the specified event date, as well as the two following dates
are considered as three different special events.
Country Specific Holidays¶
Apart from the user specified events, neural_prophet
also supports standard country specific holidays.
If you want to add the holidays for a particular country, you simply have to call the add_country_holidays
function on the NeuralProphet
object and specify the country. Similar to the user specified events,
country specific holidays can either be additive
or multiplicative
and include windows. However,
unlike for user specified events, the windows will be the same for all the country specific events.
m = m.add_country_holidays("US", mode="additive", lower_window=-1, upper_window=1)
This example will add all the US
holidays into the model in additive
format. The coefficients of the
individual events will now look like below.
{: style=”height:600px”}
Regularization for Events¶
Events can also support regularization of the coefficients. You can specify the regularization
when adding the event configs into the NeuralProphet
object like below.
m = m.add_events(["superbowl", "playoff"], regularization=0.05)
The regularization for the individual events can also be different from each other like below.
m = m.add_events("superbowl", regularization=0.05)
m = m.add_events("playoff", regularization=0.03)
For the country specific holidays too, regularizations can be specified like below.
m = m.add_country_holidays("US", mode="additive", regularization=0.05)