Seasonality
Use model_components.seasonality
to specify the seasonality.
Seasonality is used to model cyclical patterns in your data. These patterns are predictable and repeat over a fixed period of time (e.g. yearly seasonality is a cyclical pattern over 1 year).
You can control each seasonality for different cycle lengths.
To decide which types of seasonality to include, plot your input training data. Plot the values over each cycle and see if there are repeated patterns. See Examine Input Data for details.
Silverkite
Options (defaults shown for SILVERKITE
template):
seasonality: `dict` [`str`, `any`] or None, optional
Seasonality configuration dictionary, with the following optional keys.
(keys are `SilverkiteSeasonalityEnum` members in lower case).
The keys are parameters of
`~greykite.algo.forecast.silverkite.forecast_simple_silverkite.forecast_simple_silverkite`.
Refer to that function for more details.
auto_seasonality: `bool`, default False
If set to True, will trigger automatic seasonality inferring.
The keys below are ignored unless the value is False to force turn the seasonality off.
yearly_seasonality: `str` or `bool` or `int` or a list of such values for grid search, default 'auto'
Determines the yearly seasonality
'auto', True, False, or a number for the Fourier order
quarterly_seasonality: `str` or `bool` or `int` or a list of such values for grid search, default 'auto'
Determines the quarterly seasonality
'auto', True, False, or a number for the Fourier order
monthly_seasonality: `str` or `bool` or `int` or a list of such values for grid search, default 'auto'
Determines the monthly seasonality
'auto', True, False, or a number for the Fourier order
weekly_seasonality: `str` or `bool` or `int` or a list of such values for grid search, default 'auto'
Determines the weekly seasonality
'auto', True, False, or a number for the Fourier order
daily_seasonality: `str` or `bool` or `int` or a list of such values for grid search, default 'auto'
Determines the daily seasonality
'auto', True, False, or a number for the Fourier order
For each seasonality, you can choose 'auto', True, False, or a number for the Fourier order
.
Alternatively, you can choose to use automatic seasonality inferrer, which will infer
all seasonality orders for you.
Simply set auto_seasonality=True
, and the seasonality orders will be populated automatically.
For more details, see Seasonality Inferrer in Auto Configuration Tools.
True: model this seasonality with default Fourier order
False: do not model this seasonality
"auto": let the template decide, based on input data frequency and
the amount of training data. As a general principle, it requires
at least 2 full seasonal cycles and multiple observations per cycle
(e.g. no weekly/daily seasonality for weekly data)
int: model this seasonality with specified Fourier order
The Fourier order is a tuning knob for the flexibility. For Fourier order=k
,
the model includes 2k
seasonality terms. Higher values result in a more flexible model,
but may overfit to past data. Default fourier order is defined in
SilverkiteSeasonalityEnum
,
and you can decide how to increase/decrease order by comparing to the defaults.
The optimal value can be selected via hyperparameter tuning (CV grid search).
Examples:
# Example for daily data
seasonality = dict(
yearly_seasonality=True, # turn seasonality "on"
quarterly_seasonality=False, # turn seasonality "off"
monthly_seasonality="auto", # let the template decide
# weekly_seasonality=False, # missing key is the same as "auto"
daily_seasonality=False, # it's not possible to have daily seasonality for daily observations
)
# Example for hourly data with custom yearly seasonality
seasonality = dict(
yearly_seasonality=3,
# Leaves the rest up to the template ("auto")
)
# Example for weekly data with strong monthly patterns (e.g. Sales)
seasonality = dict(
yearly_seasonality=True,
quarterly_seasonality=False,
monthly_seasonality=2, # there are 4 weeks in a month, so the number of terms must not exceed 4
weekly_seasonality=False,
daily_seasonality=False,
)
# Grid search is possible
seasonality = dict(
yearly_seasonality=True,
quarterly_seasonality=[True, False],
monthly_seasonality=False,
weekly_seasonality=[3, 1],
daily_seasonality=False,
)
# Auto seasonality
seasonality = dict(
auto_seasonality=True, # automatically infers all seasonality orders
yearly_seasonality=False, # forces turning yearly seasonality off despite the inferring result
)
Note
Typical values are <= 4, up to 12 for daily seasonality, and up to 15 for yearly seasonality. The forecast will not improve (and may get worse) if Fourier order is too high.
The Fourier order k
should satisfy 2k <= n_levels+1
. n_levels
is the
number of possible values in a cycle. For example, if your input data is at
daily
frequency:
monthly seasonality:
n_levels=31
days in a month.weekly seasonality:
n_levels=7
days in a week.daily seasonality:
n_levels=1
hours in a day.
Furthermore, plot your timeseries to check how strong each seasonality effect is. Usually monthly seasonality has a weak effect, so we would limit its Fourier order to 2.
Prophet
Options:
seasonality : `dict` [`str`, `any`] or None, optional
Seasonality config dictionary, with the following optional keys.
seasonality_mode: `str` or None or list of such values for grid search
Can be 'additive' (default) or 'multiplicative'.
seasonality_prior_scale: `float` or None or list of such values for grid search
Parameter modulating the strength of the seasonality model. 10.0 by default.
Larger values allow the model to fit larger seasonal fluctuations, smaller values dampen the seasonality.
Specify for individual seasonalities using add_seasonality_dict.
yearly_seasonality: `str` or `bool` or `int` or list of such values for grid search, default 'auto'
Determines the yearly seasonality.
Can be 'auto' (default), True, False, or a number of Fourier terms to generate.
weekly_seasonality: `str` or `bool` or `int` or list of such values for grid search, default 'auto'
Determines the weekly seasonality
Can be 'auto' (default), True, False, or a number of Fourier terms to generate.
daily_seasonality: `str` or `bool` or `int` or list of such values for grid search, default 'auto'
Determines the daily seasonality
Can be 'auto' (default), True, False, or a number of Fourier terms to generate.
add_seasonality_dict: `dict` or None or list of such values for grid search
dict of custom seasonality parameters to be added to the model, default=None
Key is the seasonality component name e.g. 'monthly'; parameters are specified via dict.
For more information on add_seasonality_dict
,
see ProphetEstimator
.
Note
Refer to Silverkite section for Fourier order.
To define other seasonalities (monthly
, quarterly
, etc),
use add_seasonality_dict
.
To further customize or overwrite built-in seasonalities (yearly
, weekly
, daily
),
set them to False
in seasonalities
and define within add_seasonality_dict
.
See examples below.
Note
If no seasonalities are provided or set as "auto"
, Prophet:
Turns on yearly seasonality if there is >=2 years of history.
Turns on weekly seasonality if there is >=2 weeks of history, and the spacing between dates in the history is <7 days.
Turns on daily seasonality if there is >=2 days of history, and the spacing between dates in the history is <1 day.
Seasonality values True
and False
result in similar behavior as Silverkite.
Examples:
# example for daily data
seasonality = dict(
seasonality_mode=["additive"], # seasonality effect is added to the trend to get forecast
yearly_seasonality=[True], # turn seasonality "on"
# weekly_seasonality=[False], # missing key is the same as "auto"
daily_seasonality=[False], # it's not possible to have daily seasonality for daily observations
seasonality_prior_scale=[10.0, 25.0] # grid search over seasonality strength options
)
# example for hourly data with custom yearly, monthly, and quarterly seasonality
seasonality = dict(
seasonality_mode=["multiplicative"], # seasonality effect is multiplied
yearly_seasonality=[3],
add_seasonality_dict=[
# custom seasonality - specify period, and optionally fourier_order & prior scale
# it is possible to model different `seasonality_mode`s for custom seasonalities
{
'monthly': {
'period': 365.25/12,
'fourier_order': 10.0,
'mode': "additive"
},
'quarterly': {
'period': 365.25/4,
'fourier_order': 15.0,
'prior_scale': 15.0,
'mode': "multiplicative",
}
}]
# leave the rest up to the template ("auto")
)
# example of disabling built-in weekly seasonality and customizing via add_seasonality_dict
seasonality = dict(
weekly_seasonality=[False],
seasonality_prior_scale=[3.0], # applies to daily and yearly ("auto") seasonalities.
add_seasonality_dict=[
{
'weekly': {
'period': 7,
'fourier_order': 1.0,
'prior_scale': 5.0, # customized, otherwise defaults to seasonality_prior_scale
'mode': "multiplicative"
}
}
# example for weekly data with strong monthly patterns (e.g. Sales)
seasonality = dict(
seasonality_mode=["additive", "multiplicative"], # grid search over both
yearly_seasonality=[True, False],
seasonality_prior_scale=[4.0, 8.0], # grid search over multiple seasonality strength options
add_seasonality_dict=[ # grid search over multiple custom seasonalities
{
'monthly': {
'period': 365.25/12,
'fourier_order': 1.0
},
'quarterly': {
'period': 365.25/4,
'fourier_order': 3.0
}
},
{
'monthly': {
'period': 365.25/12,
'fourier_order': 2.0
},
'quarterly': {
'period': 365.25/4,
'fourier_order': 7.0
}
}]
)
Note
Use fourier_order
and prior_scale
to tune strength of seasonality effects.
To model Seasonality that depends on other factors,
see more details at Prophet.