forecast
Contains all forecasting models, including those which support exogenous regressors.
For forecasting, we define an abstract base ForecasterBase
class which inherits from ModelBase
and supports the
following interface, in addition to model.save()
and ForecasterClass.load
defined for ModelBase
:
model = ForecasterClass(config)
initialization with a model-specific config (which inherits from
ForecasterConfig
)configs contain:
a (potentially trainable) data pre-processing transform from
merlion.transform
; note thatmodel.transform
is a property which refers tomodel.config.transform
model-specific hyperparameters
optionally, a maximum number of steps the model can forecast for
model.forecast(time_stamps, time_series_prev=None)
returns the forecast (
TimeSeries
) for future values at the time stamps specified bytime_stamps
, as well as the standard error of that forecast (TimeSeries
, may beNone
)if
time_series_prev
is specified, it is used as the most recent context. Otherwise, the training data is used
model.train(train_data, train_config=None)
trains the model on the
TimeSeries
train_data
train_config
(optional): extra configuration describing how the model should be trained. Not used for all models. Class-level default provided for models which do use it.returns the model’s prediction
train_data
, in the same format as if you calledForecasterBase.forecast
on the time stamps oftrain_data
Base classes:
Base class for forecasting models. |
|
Base class for Deep Learning Forecasting Models |
|
Base class for forecasters which use arbitrary |
Univariate models:
The classic statistical forecasting model ARIMA (AutoRegressive Integrated Moving Average). |
|
A variant of ARIMA with a user-specified Seasonality. |
|
ETS (Error, Trend, Seasonal) forecasting model. |
|
Wrapper around Facebook's popular Prophet model for time series forecasting. |
|
Multi-Scale Exponential Smoother for univariate time series forecasting. |
Multivariate models:
Vector AutoRegressive model for multivariate time series forecasting. |
|
Tree-based models for multivariate time series forecasting. |
|
Implementation of Deep AR |
|
Implementation of Autoformer. |
|
Implementation of ETSformer. |
|
Implementation of Informer. |
|
Implementation of Transformer for time series data. |
Exogenous regressor models:
Tree-based models for multivariate time series forecasting. |
|
Wrapper around Facebook's popular Prophet model for time series forecasting. |
|
A variant of ARIMA with a user-specified Seasonality. |
|
Vector AutoRegressive model for multivariate time series forecasting. |
|
The classic statistical forecasting model ARIMA (AutoRegressive Integrated Moving Average). |
Deep Learning models:
Implementation of Deep AR |
|
Implementation of Autoformer. |
|
Implementation of ETSformer. |
|
Implementation of Informer. |
|
Implementation of Transformer for time series data. |
Note that the AutoML variants
AutoSarima
and
AutoProphet
also support exogenous regressors.
Base classes
forecast.base
Base class for forecasting models.
- class merlion.models.forecast.base.ForecasterConfig(max_forecast_steps=None, target_seq_index=None, invert_transform=None, transform=None, **kwargs)
Bases:
Config
Config object used to define a forecaster model.
- Parameters
max_forecast_steps (
Optional
[int
]) – Max # of steps we would like to forecast for. Required for some models like MSES.target_seq_index (
Optional
[int
]) – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.transform – Transformation to pre-process input time series.
-
max_forecast_steps:
Optional
[int
] = None
-
target_seq_index:
Optional
[int
] = None
-
invert_transform:
bool
= None
- class merlion.models.forecast.base.ForecasterBase(config)
Bases:
ModelBase
Base class for a forecaster model.
Note
If your model depends on an evenly spaced time series, make sure to
Call ForecasterBase.train_pre_process in ForecasterBase.train
Call ForecasterBase.resample_time_stamps at the start of ForecasterBase.forecast to get a set of resampled time stamps, and call
time_series.align(reference=time_stamps)
to align the forecast with the original time stamps.
- config_class
alias of
ForecasterConfig
- target_name = None
The name of the target univariate to forecast.
- property max_forecast_steps
- property target_seq_index: int
- Returns
the index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
- property invert_transform
- Returns
Whether to automatically invert the
transform
before returning a forecast.
- property require_univariate: bool
All forecasters can work on multivariate data, since they only forecast a single target univariate.
- property support_multivariate_output: bool
Indicating whether the forecasting model can forecast multivariate output.
- resample_time_stamps(time_stamps, time_series_prev=None)
- train_pre_process(train_data, exog_data=None, return_exog=None)
Applies pre-processing steps common for training most models.
- Parameters
train_data (
TimeSeries
) – the original time series of training data- Return type
Union
[TimeSeries
,Tuple
[TimeSeries
,Optional
[TimeSeries
]]]- Returns
the training data, after any necessary pre-processing has been applied
- train(train_data, train_config=None, exog_data=None)
Trains the forecaster on the input time series.
- Parameters
train_data (
TimeSeries
) – a TimeSeries of metric values to train the model.train_config – Additional training configs, if needed. Only required for some models.
exog_data (
Optional
[TimeSeries
]) – A time series of exogenous variables, sampled at the same time stamps astrain_data
. Exogenous variables are known a priori, and they are independent of the variable being forecasted. Only supported for models which inherit from ForecasterExogBase.
- Return type
Tuple
[TimeSeries
,Optional
[TimeSeries
]]- Returns
the model’s prediction on
train_data
, in the same format as if you called ForecasterBase.forecast on the time stamps oftrain_data
- train_post_process(train_result)
Converts the train result (forecast & stderr for training data) into TimeSeries objects, and inverts the model’s transform if desired.
- Return type
Tuple
[TimeSeries
,TimeSeries
]
- transform_exog_data(exog_data, time_stamps, time_series_prev=None)
- Return type
Union
[Tuple
[TimeSeries
,TimeSeries
],Tuple
[TimeSeries
,None
],Tuple
[None
,None
]]
- forecast(time_stamps, time_series_prev=None, exog_data=None, return_iqr=False, return_prev=False)
Returns the model’s forecast on the timestamps given. If
self.transform
is specified in the config, the forecast is a forecast of transformed values by default. To invert the transform and forecast the actual values of the time series, specifyinvert_transform = True
when specifying the config.- Parameters
time_stamps (
Union
[int
,List
[int
]]) – Either alist
of timestamps we wish to forecast for, or the number of steps (int
) we wish to forecast for.time_series_prev (
Optional
[TimeSeries
]) – a time series immediately precedingtime_series
. If given, we use it to initialize the forecaster’s state. Otherwise, we assume thattime_series
immediately follows the training data.exog_data (
Optional
[TimeSeries
]) – A time series of exogenous variables. Exogenous variables are known a priori, and they are independent of the variable being forecasted.exog_data
must include data for all oftime_stamps
; iftime_series_prev
is given, it must include data for all oftime_series_prev.time_stamps
as well. Optional. Only supported for models which inherit from ForecasterExogBase.return_iqr (
bool
) – whether to return the inter-quartile range for the forecast. Only supported for models which return error bars.return_prev (
bool
) – whether to return the forecast fortime_series_prev
(and its stderr or IQR if relevant), in addition to the forecast fortime_stamps
. Only used iftime_series_prev
is provided.
- Return type
Union
[Tuple
[TimeSeries
,Optional
[TimeSeries
]],Tuple
[TimeSeries
,TimeSeries
,TimeSeries
]]- Returns
(forecast, stderr)
ifreturn_iqr
is false,(forecast, lb, ub)
otherwise.forecast
: the forecast for the timestamps givenstderr
: the standard error of each forecast value. May beNone
.lb
: 25th percentile of forecast values for each timestampub
: 75th percentile of forecast values for each timestamp
- batch_forecast(time_stamps_list, time_series_prev_list, return_iqr=False, return_prev=False)
Returns the model’s forecast on a batch of timestamps given.
- Parameters
time_stamps_list (
List
[List
[int
]]) – a list of lists of timestamps we wish to forecast fortime_series_prev_list (
List
[TimeSeries
]) – a list of TimeSeries immediately preceding the time stamps in time_stamps_listreturn_iqr (
bool
) – whether to return the inter-quartile range for the forecast. Only supported by models which can return error bars.return_prev (
bool
) – whether to return the forecast fortime_series_prev
(and its stderr or IQR if relevant), in addition to the forecast fortime_stamps
. Only used iftime_series_prev
is provided.
- Return type
Tuple
[Union
[Tuple
[List
[TimeSeries
],List
[Optional
[TimeSeries
]]],Tuple
[List
[TimeSeries
],List
[TimeSeries
],List
[TimeSeries
]]]]- Returns
(forecast, forecast_stderr)
ifreturn_iqr
is false,(forecast, forecast_lb, forecast_ub)
otherwise.forecast
: the forecast for the timestamps givenforecast_stderr
: the standard error of each forecast value. May beNone
.forecast_lb
: 25th percentile of forecast values for each timestampforecast_ub
: 75th percentile of forecast values for each timestamp
- get_figure(*, time_series=None, time_stamps=None, time_series_prev=None, exog_data=None, plot_forecast_uncertainty=False, plot_time_series_prev=False)
- Parameters
time_series (
Optional
[TimeSeries
]) – the time series over whose timestamps we wish to make a forecast. Exactly one oftime_series
ortime_stamps
should be provided.time_stamps (
Optional
[List
[int
]]) – Either alist
of timestamps we wish to forecast for, or the number of steps (int
) we wish to forecast for. Exactly one oftime_series
ortime_stamps
should be provided.time_series_prev (
Optional
[TimeSeries
]) – a time series immediately precedingtime_series
. If given, we use it to initialize the forecaster’s state. Otherwise, we assume thattime_series
immediately follows the training data.exog_data (
Optional
[TimeSeries
]) – A time series of exogenous variables. Exogenous variables are known a priori, and they are independent of the variable being forecasted.exog_data
must include data for all oftime_stamps
; iftime_series_prev
is given, it must include data for all oftime_series_prev.time_stamps
as well. Optional. Only supported for models which inherit from ForecasterExogBase.plot_forecast_uncertainty – whether to plot uncertainty estimates (the inter-quartile range) for forecast values. Not supported for all models.
plot_time_series_prev – whether to plot
time_series_prev
(and the model’s fit for it). Only used iftime_series_prev
is given.
- Return type
- Returns
a Figure of the model’s forecast.
- plot_forecast(*, time_series=None, time_stamps=None, time_series_prev=None, exog_data=None, plot_forecast_uncertainty=False, plot_time_series_prev=False, figsize=(1000, 600), ax=None)
Plots the forecast for the time series in matplotlib, optionally also plotting the uncertainty of the forecast, as well as the past values (both true and predicted) of the time series.
- Parameters
time_series (
Optional
[TimeSeries
]) – the time series over whose timestamps we wish to make a forecast. Exactly one oftime_series
ortime_stamps
should be provided.time_stamps (
Optional
[List
[int
]]) – Either alist
of timestamps we wish to forecast for, or the number of steps (int
) we wish to forecast for. Exactly one oftime_series
ortime_stamps
should be provided.time_series_prev (
Optional
[TimeSeries
]) – a time series immediately precedingtime_series
. If given, we use it to initialize the forecaster’s state. Otherwise, we assume thattime_series
immediately follows the training data.exog_data (
Optional
[TimeSeries
]) – A time series of exogenous variables. Exogenous variables are known a priori, and they are independent of the variable being forecasted.exog_data
must include data for all oftime_stamps
; iftime_series_prev
is given, it must include data for all oftime_series_prev.time_stamps
as well. Optional. Only supported for models which inherit from ForecasterExogBase.plot_forecast_uncertainty – whether to plot uncertainty estimates (the inter-quartile range) for forecast values. Not supported for all models.
plot_time_series_prev – whether to plot
time_series_prev
(and the model’s fit for it). Only used iftime_series_prev
is given.figsize – figure size in pixels
ax – matplotlib axis to add this plot to
- Returns
(fig, ax): matplotlib figure & axes the figure was plotted on
- plot_forecast_plotly(*, time_series=None, time_stamps=None, time_series_prev=None, exog_data=None, plot_forecast_uncertainty=False, plot_time_series_prev=False, figsize=(1000, 600))
Plots the forecast for the time series in plotly, optionally also plotting the uncertainty of the forecast, as well as the past values (both true and predicted) of the time series.
- Parameters
time_series (
Optional
[TimeSeries
]) – the time series over whose timestamps we wish to make a forecast. Exactly one oftime_series
ortime_stamps
should be provided.time_stamps (
Optional
[List
[int
]]) – Either alist
of timestamps we wish to forecast for, or the number of steps (int
) we wish to forecast for. Exactly one oftime_series
ortime_stamps
should be provided.time_series_prev (
Optional
[TimeSeries
]) – a time series immediately precedingtime_series
. If given, we use it to initialize the forecaster’s state. Otherwise, we assume thattime_series
immediately follows the training data.exog_data (
Optional
[TimeSeries
]) – A time series of exogenous variables. Exogenous variables are known a priori, and they are independent of the variable being forecasted.exog_data
must include data for all oftime_stamps
; iftime_series_prev
is given, it must include data for all oftime_series_prev.time_stamps
as well. Optional. Only supported for models which inherit from ForecasterExogBase.plot_forecast_uncertainty – whether to plot uncertainty estimates (the inter-quartile range) for forecast values. Not supported for all models.
plot_time_series_prev – whether to plot
time_series_prev
(and the model’s fit for it). Only used iftime_series_prev
is given.figsize – figure size in pixels
- class merlion.models.forecast.base.ForecasterExogConfig(exog_transform=None, exog_aggregation_policy='Mean', exog_missing_value_policy='ZFill', max_forecast_steps=None, target_seq_index=None, invert_transform=None, transform=None, **kwargs)
Bases:
ForecasterConfig
- Parameters
exog_transform (
Optional
[TransformBase
]) – The pre-processing transform for exogenous data. Note: resampling is handled separately.exog_aggregation_policy (
Union
[AggregationPolicy
,str
]) – The policy to use for aggregating values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.exog_missing_value_policy (
Union
[MissingValuePolicy
,str
]) – The policy to use for imputing missing values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.max_forecast_steps – Max # of steps we would like to forecast for. Required for some models like MSES.
target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.transform – Transformation to pre-process input time series.
-
exog_transform:
TransformBase
= None
- property exog_aggregation_policy
- property exog_missing_value_policy
- class merlion.models.forecast.base.ForecasterExogBase(config)
Bases:
ForecasterBase
Base class for a forecaster model which supports exogenous variables. Exogenous variables are known a priori, and they are independent of the variable being forecasted.
- property supports_exog
Whether the model supports exogenous regressors.
- property exog_transform
- property exog_aggregation_policy
- property exog_missing_value_policy
- transform_exog_data(exog_data, time_stamps, time_series_prev=None)
Transforms & resamples exogenous data and splits it into two subsets: one with the same timestamps as
time_series_prev
(None
iftime_series_prev
isNone
), and one with the timestampstime_stamps
.- Parameters
exog_data (
TimeSeries
) – The exogenous data of interest.time_stamps (
Union
[List
[int
],DatetimeIndex
]) – The timestamps of interest (either the timestamps of data, or the timestamps at which we want to obtain a forecast)time_series_prev (
Optional
[TimeSeries
]) – The timestamps of a time series precedingtime_stamps
as context. Optional.
- Return type
Union
[Tuple
[TimeSeries
,TimeSeries
],Tuple
[TimeSeries
,None
],Tuple
[None
,None
]]- Returns
(exog_data, exog_data_prev)
, whereexog_data
has been resampled to match thetime_stamps
andexog_data_prev` has been resampled to match ``time_series_prev.time_stamps
.
forecast.deep_base
Base class for Deep Learning Forecasting Models
- class merlion.models.forecast.deep_base.DeepForecasterConfig(n_past, batch_size=32, num_epochs=10, optimizer=Optimizer.Adam, loss_fn=LossFunction.mse, clip_gradient=None, use_gpu=False, ts_encoding='h', lr=0.0001, weight_decay=0.0, valid_fraction=0.2, early_stop_patience=None, transform=None, max_forecast_steps=None, target_seq_index=None, invert_transform=None, **kwargs)
Bases:
DeepConfig
,ForecasterConfig
Config object used to define a forecaster with deep model
- Parameters
n_past (
int
) – # of past steps used for forecasting future.batch_size – Batch size of a batch for stochastic training of deep models
num_epochs – Total number of epochs for training.
optimizer – The optimizer for learning the parameters of the deep learning models. The value of optimizer can be
Adam
,AdamW
,SGD
,Adagrad
,RMSprop
.loss_fn – Loss function for optimizing deep learning models. The value of loss_fn can be
mse
for l2 loss,l1
for l1 loss,huber
for huber loss.clip_gradient – Clipping gradient norm of model parameters before updating. If
clip_gradient is None
, then the gradient will not be clipped.use_gpu – Whether to use gpu for training deep models. If
use_gpu = True
while thre is no GPU device, the model will use CPU for training instead.ts_encoding – whether the timestamp should be encoded to a float vector, which can be used for training deep learning based time series models; if
None
, the timestamp is not encoded. If notNone
, it represents the frequency for time features encoding options:[s:secondly, t:minutely, h:hourly, d:daily, b:business days, w:weekly, m:monthly]lr – Learning rate for optimizing deep learning models.
weight_decay – Weight decay (L2 penalty) (default: 0)
valid_fraction – Fraction of validation set to be split from training data
early_stop_patience – Number of epochs with no improvement after which training will be stopped for early stopping function. If
early_stop_patience = None
, the training process will not stop early.transform – Transformation to pre-process input time series.
max_forecast_steps – Max # of steps we would like to forecast for. Required for some models like MSES.
target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.
- class merlion.models.forecast.deep_base.DeepForecaster(config)
Bases:
DeepModelBase
,ForecasterBase
Base class for a deep forecaster model
- config_class
alias of
DeepForecasterConfig
- property support_multivariate_output: bool
Deep models support multivariate output by default.
- property require_even_sampling: bool
Whether the model assumes that training data is sampled at a fixed frequency
forecast.sklearn_base
Base class for forecasters which use arbitrary sklearn
regression models internally.
- class merlion.models.forecast.sklearn_base.SKLearnForecasterConfig(maxlags=None, max_forecast_steps=None, target_seq_index=None, prediction_stride=1, exog_transform=None, exog_aggregation_policy='Mean', exog_missing_value_policy='ZFill', invert_transform=None, transform=None, **kwargs)
Bases:
ForecasterExogConfig
Configuration class for a SKLearnForecaster.
- Parameters
maxlags (
Optional
[int
]) – Size of historical window to base the forecast on.max_forecast_steps (
Optional
[int
]) – Max # of steps we would like to forecast for.target_seq_index (
Optional
[int
]) – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.prediction_stride (
int
) –the number of steps being forecasted in a single call to underlying the model
If univariate: the sequence target of the length of prediction_stride will be utilized, forecasting will be done autoregressively, with the stride unit of prediction_stride
If multivariate:
if = 1: autoregressively forecast all variables in the time series, one step at a time
if > 1: only support directly forecasting the next prediction_stride steps in the future. Autoregression not supported. Note that the model will set prediction_stride = max_forecast_steps.
exog_transform – The pre-processing transform for exogenous data. Note: resampling is handled separately.
exog_aggregation_policy – The policy to use for aggregating values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
exog_missing_value_policy – The policy to use for imputing missing values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.transform – Transformation to pre-process input time series.
- class merlion.models.forecast.sklearn_base.SKLearnForecaster(config)
Bases:
ForecasterExogBase
Wrapper around a sklearn-style model for time series forecasting. The underlying model must support
fit()
andpredict()
methods. The model can be trained to be either an autoregressive model of ordermaxlags
, or to directly predict the nextprediction_stride
timestamps from a history of lengthmaxlags
.If the data is univariate, the model will predict the next
prediction_stride
elements of the time series. It can then use these predictions to autoregressively predict the nextprediction_stride
elements. If the data is multivariate, the model will either autoregressively predict the next timestamp of all univariates (ifprediction_stride = 1
), or it will directly predict the nextprediction_stride
timestamps of the target univariate (ifprediction_stride > 1
).- config_class
alias of
SKLearnForecasterConfig
- model = None
- property maxlags: int
- property prediction_stride: int
- property require_even_sampling: bool
Whether the model assumes that training data is sampled at a fixed frequency
- property require_univariate: bool
All forecasters can work on multivariate data, since they only forecast a single target univariate.
Univariate models
forecast.arima
The classic statistical forecasting model ARIMA (AutoRegressive Integrated Moving Average).
- class merlion.models.forecast.arima.ArimaConfig(order=(4, 1, 2), seasonal_order=(0, 0, 0, 0), exog_transform: TransformBase = None, exog_aggregation_policy: Union[AggregationPolicy, str] = 'Mean', exog_missing_value_policy: Union[MissingValuePolicy, str] = 'ZFill', max_forecast_steps: int = None, target_seq_index: int = None, invert_transform=None, transform: TransformBase = None, max_score: float = 1000, threshold=None, enable_calibrator=True, enable_threshold=True, **kwargs)
Bases:
SarimaConfig
Configuration class for Arima. Just a Sarima model with seasonal order
(0, 0, 0, 0)
.Base class of the object used to configure an anomaly detection model.
- Parameters
order – Order is (p, d, q) for an ARIMA(p, d, q) process. d must be an integer indicating the integration order of the process, while p and q must be integers indicating the AR and MA orders (so that all lags up to those orders are included).
seasonal_order – (0, 0, 0, 0) because ARIMA has no seasonal order.
exog_transform – The pre-processing transform for exogenous data. Note: resampling is handled separately.
exog_aggregation_policy – The policy to use for aggregating values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
exog_missing_value_policy – The policy to use for imputing missing values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
max_forecast_steps – Max # of steps we would like to forecast for. Required for some models like MSES.
target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.transform – Transformation to pre-process input time series.
max_score – maximum possible uncalibrated anomaly score
threshold – the rule to use for thresholding anomaly scores
enable_calibrator – whether to enable a calibrator which automatically transforms all raw anomaly scores to be z-scores (i.e. distributed as N(0, 1)).
enable_threshold – whether to enable the thresholding rule when post-processing anomaly scores
- property seasonal_order: Tuple[int, int, int, int]
- Returns
(0, 0, 0, 0) because ARIMA has no seasonal order.
- class merlion.models.forecast.arima.Arima(config)
Bases:
Sarima
Implementation of the classic statistical model ARIMA (AutoRegressive Integrated Moving Average) for forecasting.
- config_class
alias of
ArimaConfig
forecast.sarima
A variant of ARIMA with a user-specified Seasonality.
- class merlion.models.forecast.sarima.SarimaConfig(order=(4, 1, 2), seasonal_order=(2, 0, 1, 24), exog_transform=None, exog_aggregation_policy='Mean', exog_missing_value_policy='ZFill', max_forecast_steps=None, target_seq_index=None, invert_transform=None, transform=None, max_score=1000, threshold=None, enable_calibrator=True, enable_threshold=True, **kwargs)
Bases:
ForecasterExogConfig
Config class for Sarima (Seasonal AutoRegressive Integrated Moving Average).
Base class of the object used to configure an anomaly detection model.
- Parameters
order (
List
[int
]) – Order is (p, d, q) for an ARIMA(p, d, q) process. d must be an integer indicating the integration order of the process, while p and q must be integers indicating the AR and MA orders (so that all lags up to those orders are included).seasonal_order (
List
[int
]) – Seasonal order is (P, D, Q, S) for seasonal ARIMA process, where s is the length of the seasonality cycle (e.g. s=24 for 24 hours on hourly granularity). P, D, Q are as for ARIMA.exog_transform – The pre-processing transform for exogenous data. Note: resampling is handled separately.
exog_aggregation_policy – The policy to use for aggregating values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
exog_missing_value_policy – The policy to use for imputing missing values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
max_forecast_steps – Max # of steps we would like to forecast for. Required for some models like MSES.
target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.transform – Transformation to pre-process input time series.
max_score – maximum possible uncalibrated anomaly score
threshold – the rule to use for thresholding anomaly scores
enable_calibrator – whether to enable a calibrator which automatically transforms all raw anomaly scores to be z-scores (i.e. distributed as N(0, 1)).
enable_threshold – whether to enable the thresholding rule when post-processing anomaly scores
- class merlion.models.forecast.sarima.Sarima(config)
Bases:
ForecasterExogBase
,SeasonalityModel
Implementation of the classic statistical model SARIMA (Seasonal AutoRegressive Integrated Moving Average) for forecasting.
- config_class
alias of
SarimaConfig
- property require_even_sampling: bool
Whether the model assumes that training data is sampled at a fixed frequency
- property order: Tuple[int, int, int]
- Returns
the order (p, d, q) of the model, where p is the AR order, d is the integration order, and q is the MA order.
- property seasonal_order: Tuple[int, int, int, int]
- Returns
the seasonal order (P, D, Q, S) for the seasonal ARIMA process, where p is the AR order, D is the integration order, Q is the MA order, and S is the length of the seasonality cycle.
- set_seasonality(theta, train_data)
Implement this method to do any model-specific adjustments on the seasonality that was provided by SeasonalityLayer.
- Parameters
theta – Seasonality processed by SeasonalityLayer.
train_data (
UnivariateTimeSeries
) – Training data (or numpy array representing the target univariate) for any model-specific adjustments you might want to make.
forecast.ets
ETS (Error, Trend, Seasonal) forecasting model.
- class merlion.models.forecast.ets.ETSConfig(max_forecast_steps=None, target_seq_index=None, error='add', trend='add', damped_trend=True, seasonal='add', seasonal_periods=None, refit=True, invert_transform=None, transform=None, enable_calibrator=False, max_score=1000, threshold=None, enable_threshold=True, **kwargs)
Bases:
ForecasterConfig
Configuration class for
ETS
model. ETS model is an underlying state space model consisting of an error term (E), a trend component (T), a seasonal component (S), and a level component. Each component is flexible with different traits with additive (‘add’) or multiplicative (‘mul’) formulation. Refer to https://otexts.com/fpp2/taxonomy.html for more information about ETS model.Base class of the object used to configure an anomaly detection model.
- Parameters
max_forecast_steps (
Optional
[int
]) – Number of steps we would like to forecast for.target_seq_index (
Optional
[int
]) – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.error (
str
) – The error term. “add” or “mul”.trend (
str
) – The trend component. “add”, “mul” or None.damped_trend (
bool
) – Whether or not an included trend component is damped.seasonal (
str
) – The seasonal component. “add”, “mul” or None.seasonal_periods (
Optional
[int
]) – The length of the seasonality cycle.None
by default.refit (
bool
) – ifTrue
, refit the full ETS model whentime_series_prev
is given to the forecast method (slower). IfFalse
, simply perform exponential smoothing (faster).invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.transform – Transformation to pre-process input time series.
enable_calibrator –
False
because this config assumes calibrated outputs from the model.max_score – maximum possible uncalibrated anomaly score
threshold – the rule to use for thresholding anomaly scores
enable_threshold – whether to enable the thresholding rule when post-processing anomaly scores
- class merlion.models.forecast.ets.ETS(config)
Bases:
SeasonalityModel
,ForecasterBase
Implementation of the classic local statistical model ETS (Error, Trend, Seasonal) for forecasting.
- property require_even_sampling: bool
Whether the model assumes that training data is sampled at a fixed frequency
- property error
- property trend
- property damped_trend
- property seasonal
- property seasonal_periods
- set_seasonality(theta, train_data)
Implement this method to do any model-specific adjustments on the seasonality that was provided by SeasonalityLayer.
- Parameters
theta – Seasonality processed by SeasonalityLayer.
train_data (
UnivariateTimeSeries
) – Training data (or numpy array representing the target univariate) for any model-specific adjustments you might want to make.
forecast.prophet
Wrapper around Facebook’s popular Prophet model for time series forecasting.
- class merlion.models.forecast.prophet.ProphetConfig(max_forecast_steps=None, target_seq_index=None, yearly_seasonality='auto', weekly_seasonality='auto', daily_seasonality='auto', seasonality_mode='additive', holidays=None, uncertainty_samples=100, exog_transform=None, exog_aggregation_policy='Mean', exog_missing_value_policy='ZFill', invert_transform=None, transform=None, max_score=1000, threshold=None, enable_calibrator=True, enable_threshold=True, **kwargs)
Bases:
ForecasterExogConfig
Configuration class for Facebook’s Prophet model, as described by Taylor & Letham, 2017.
Base class of the object used to configure an anomaly detection model.
- Parameters
max_forecast_steps (
Optional
[int
]) – Max # of steps we would like to forecast for.target_seq_index (
Optional
[int
]) – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.yearly_seasonality (
Union
[bool
,int
]) – If bool, whether to enable yearly seasonality. By default, it is activated if there are >= 2 years of history, but deactivated otherwise. If int, this is the number of Fourier series components used to model the seasonality (default = 10).weekly_seasonality (
Union
[bool
,int
]) – If bool, whether to enable weekly seasonality. By default, it is activated if there are >= 2 weeks of history, but deactivated otherwise. If int, this is the number of Fourier series components used to model the seasonality (default = 3).daily_seasonality (
Union
[bool
,int
]) – If bool, whether to enable daily seasonality. By default, it is activated if there are >= 2 days of history, but deactivated otherwise. If int, this is the number of Fourier series components used to model the seasonality (default = 4).seasonality_mode – ‘additive’ (default) or ‘multiplicative’.
holidays – pd.DataFrame with columns holiday (string) and ds (date type) and optionally columns lower_window and upper_window which specify a range of days around the date to be included as holidays. lower_window=-2 will include 2 days prior to the date as holidays. Also optionally can have a column prior_scale specifying the prior scale for that holiday. Can also be a dict corresponding to the desired pd.DataFrame.
uncertainty_samples (
int
) – The number of posterior samples to draw in order to calibrate the anomaly scores.exog_transform – The pre-processing transform for exogenous data. Note: resampling is handled separately.
exog_aggregation_policy – The policy to use for aggregating values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
exog_missing_value_policy – The policy to use for imputing missing values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.transform – Transformation to pre-process input time series.
max_score – maximum possible uncalibrated anomaly score
threshold – the rule to use for thresholding anomaly scores
enable_calibrator – whether to enable a calibrator which automatically transforms all raw anomaly scores to be z-scores (i.e. distributed as N(0, 1)).
enable_threshold – whether to enable the thresholding rule when post-processing anomaly scores
- class merlion.models.forecast.prophet.Prophet(config)
Bases:
ForecasterExogBase
,SeasonalityModel
Facebook’s model for time series forecasting. See docs for ProphetConfig and Taylor & Letham, 2017 for more details.
- config_class
alias of
ProphetConfig
- property require_even_sampling: bool
Whether the model assumes that training data is sampled at a fixed frequency
- property yearly_seasonality
- property weekly_seasonality
- property daily_seasonality
- property add_seasonality
- property seasonality_mode
- property holidays
- property uncertainty_samples
- set_seasonality(theta, train_data)
Implement this method to do any model-specific adjustments on the seasonality that was provided by SeasonalityLayer.
- Parameters
theta – Seasonality processed by SeasonalityLayer.
train_data (
UnivariateTimeSeries
) – Training data (or numpy array representing the target univariate) for any model-specific adjustments you might want to make.
forecast.smoother
Multi-Scale Exponential Smoother for univariate time series forecasting.
- class merlion.models.forecast.smoother.MSESConfig(max_forecast_steps, max_backstep=None, recency_weight=0.5, accel_weight=1.0, optimize_acc=True, eta=0.0, rho=0.0, phi=2.0, inflation=1.0, target_seq_index=None, invert_transform=None, transform=None, **kwargs)
Bases:
ForecasterConfig
Configuration class for an MSES forecasting model.
Letting
w
be the recency weight,B
the maximum backstep,x_t
the last seen data point, andl_s,t
the series of losses for scales
.\[\begin{split}\begin{align*} \hat{x}_{t+h} & = \sum_{b=0}^B p_{b} \cdot (x_{t-b} + v_{b+h,t} + a_{b+h,t}) \\ \space \\ \text{where} \space\space & v_{b+h,t} = \text{EMA}_w(\Delta_{b+h} x_t) \\ & a_{b+h,t} = \text{EMA}_w(\Delta_{b+h}^2 x_t) \\ \text{and} \space\space & p_b = \sigma(z)_b \space\space \\ \text{if} & \space\space z_b = (b+h)^\phi \cdot \text{EMA}_w(l_{b+h,t}) \cdot \text{RWSE}_w(l_{b+h,t})\\ \end{align*}\end{split}\]- Parameters
max_forecast_steps (
int
) – Max # of steps we would like to forecast for. Required for some models like MSES.max_backstep (
Optional
[int
]) – Max backstep to use in forecasting. If we train with x(0),…,x(t), Then, the b-th model MSES uses will forecast x(t+h) by anchoring at x(t-b) and predicting xhat(t+h) = x(t-b) + delta_hat(b+h).recency_weight (
float
) – The recency weight parameter to use when estimating delta_hat.accel_weight (
float
) – The weight to scale the acceleration by when computing delta_hat. Specifically, delta_hat(b+h) = velocity(b+h) + accel_weight * acceleration(b+h).optimize_acc (
bool
) – If True, the acceleration correction will only be used at scales ranging from 1,…(max_backstep+max_forecast_steps)/2.eta (
float
) – The parameter used to control the rate at which recency_weight gets tuned when online updates are made to the model and losses can be computed.rho (
float
) – The parameter that determines what fraction of the overall error is due to velcity error, while the rest is due to the complement. The error at any scale will be determined asrho * velocity_error + (1-rho) * loss_error
.phi (
float
) – The parameter used to exponentially inflate the magnitude of loss error at different scales. Loss error for scales
will be increased by a factor ofphi ** s
.inflation (
float
) – The inflation exponent to use when computing the distribution p(b|h) over the models when forecasting at horizon h according to standard errors of the estimated velocities over the models; inflation=1 is equivalent to using the softmax function.target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.transform – Transformation to pre-process input time series.
- property max_scale
- property backsteps
- class merlion.models.forecast.smoother.MSESTrainConfig(incremental=True, process_losses=True, tune_recency_weights=False, init_batch_sz=2, train_cadence=None)
Bases:
object
MSES training configuration.
- Parameters
incremental (
bool
) – If True, train the MSES model incrementally with the initial training data at the giventrain_cadence
. This allows MSES to return a forecast for the training data.init_batch_sz (
int
) – The size of the inital training batch for MSES. This is necessary because MSES cannot predict the past, but needs to start with some data. This should be very small. 2 is the minimum, and is recommended because 2 will result in the most representative train forecast.train_cadence (
Optional
[int
]) – The frequency at which the training forecasts will be generated during incremental training.
- Param
If True, track the losses encountered during incremental initial training.
- Tune_recency_weights
If True, tune recency weights during incremental initial training.
- class merlion.models.forecast.smoother.MSES(config)
Bases:
ForecasterBase
Multi-scale Exponential Smoother (MSES) is a forecasting algorithm modeled heavily after classical mechanical concepts, namely, velocity and acceleration.
Having seen data points of a time series up to time t, MSES forecasts x(t+h) by anchoring at a value b steps back from the last known value, x(t-b), and estimating the delta between x(t-b) and x(t+h). The delta over these b+h timesteps, delta(b+h), also known as the delta at scale b+h, is predicted by estimating the velocity over these timesteps as well as the change in the velocity, acceleration. Specifically,
xhat(t+h) = x(t-b) + velocity_hat(b+h) + acceleration_hat(b+h)
This estimation is done for each b, known as a backstep, from 0, which anchors at x(t), 1,… up to a maximum backstep configurable by the user. The algorithm then takes the seperate forecasts of x(t+h), indexed by which backstep was used, xhat_b(t+h), and determines a final forecast: p(b|h) dot xhat_b, where p(b|h) is a distribution over the xhat_b’s that is determined according to the lowest standard errors of the recency-weighted velocity estimates.
Letting
w
be the recency weight,B
the maximum backstep,x_t
the last seen data point, andl_s,t
the series of losses for scales
.\[\begin{split}\begin{align*} \hat{x}_{t+h} & = \sum_{b=0}^B p_{b} \cdot (x_{t-b} + v_{b+h,t} + a_{b+h,t}) \\ \space \\ \text{where} \space\space & v_{b+h,t} = \text{EMA}_w(\Delta_{b+h} x_t) \\ & a_{b+h,t} = \text{EMA}_w(\Delta_{b+h}^2 x_t) \\ \text{and} \space\space & p_b = \sigma(z)_b \space\space \\ \text{if} & \space\space z_b = (b+h)^\phi \cdot \text{EMA}_w(l_{b+h,t}) \cdot \text{RWSE}_w(l_{b+h,t})\\ \end{align*}\end{split}\]- config_class
alias of
MSESConfig
- property require_even_sampling: bool
Whether the model assumes that training data is sampled at a fixed frequency
- property rho
- property backsteps
- property max_horizon
- update(new_data, tune_recency_weights=True, train_cadence=None)
Updates the MSES model with new data that has been acquired since the model’s initial training.
- Parameters
new_data (
DataFrame
) – New data that has occured since the last training time.tune_recency_weights (
bool
) – If True, the model will first forecast the values at the new_data’s timestamps, calculate the associated losses, and use these losses to make updates to the recency weight.train_cadence – The frequency at which the training forecasts will be generated during incremental training.
- Return type
Tuple
[TimeSeries
,TimeSeries
]
- xhat_h(horizon)
Returns the forecasts for the input horizon at every backstep.
- Return type
List
[Optional
[float
]]
- marginalize_xhat_h(horizon, xhat_h)
Given a list of forecasted values produced by delta estimators at different backsteps, compute a weighted average of these values. The weights are assigned based on the standard errors of the velocities, where the b’th estimate will be given more weight if its velocity has a lower standard error relative to the other estimates.
- Parameters
horizon (
int
) – the horizon at which we want to predictxhat_h (
List
[Optional
[float
]]) – the forecasted values at this horizon, using each of the possible backsteps
- class merlion.models.forecast.smoother.DeltaStats(scale, recency_weight)
Bases:
object
A wrapper around the statistics used to estimate deltas at a given scale.
- Parameters
scale (
int
) – The scale associated with the statisticsrecency_weight (
float
) – The recency weight parameter that that the incremental velocity, acceleration and standard error statistics should use.
- property lag
- update_velocity(vels)
- update_acceleration(accs)
- update_loss(losses)
- tune(losses, eta)
Tunes the recency weight according to recent forecast losses.
- Parameters
losses (
List
[float
]) – List of recent losses.eta (
float
) – Constant by which to scale the update to the recency weight. A bigger eta means more aggressive updates to the recency_weight.
- class merlion.models.forecast.smoother.DeltaEstimator(max_scale, recency_weight, accel_weight, optimize_acc, eta, phi, data=None, stats=None)
Bases:
object
Class for estimating the delta for MSES.
- Parameters
max_scale (
int
) – Delta Estimator can estimate delta over multiple scales, or time steps, ranging from 1,2,…,max_scale.recency_weight (
float
) – The recency weight parameter to use when estimating delta_hat.accel_weight (
float
) – The weight to scale the acceleration by when computing delta_hat. Specifically, delta_hat(b+h) = velocity(b+h) + accel_weight * acceleration(b+h).optimize_acc (
bool
) – If True, the acceleration correction will only be used at scales ranging from 1,…,max_scale/2.eta (
float
) – The parameter used to control the rate at which recency_weight gets tuned when online updates are made to the model and losses can be computed.data (
Optional
[UnivariateTimeSeries
]) – The data to initialize the delta estimator with.stats (
Optional
[Dict
[int
,DeltaStats
]]) – Dictionary mapping scales to DeltaStats objects to be used for delta estimation.
- property acc_max_scale
- property max_scale
- property data
- property x
- train(new_data)
Updates the delta statistics: velocity, acceleration and velocity standard error at each scale using new data.
- Parameters
new_data (
UnivariateTimeSeries
) – new datapoints in the time series.
- process_losses(scale_losses, tune_recency_weights=False)
Uses recent forecast errors to improve the delta estimator. This is done by updating the recency_weight that is used by delta stats at particular scales.
- Parameters
scale_losses (
Dict
[int
,List
[float
]]) – A dictionary mapping a scale to a list of forecasting errors that associated with that scale.
- velocity(scale)
- Return type
float
- acceleration(scale)
- Return type
float
- vel_err(scale)
- Return type
float
- pos_err(scale)
- Return type
float
- neg_err(scale)
- Return type
float
- loss_err(scale)
- Return type
float
- delta_hat(scale)
- Return type
float
Multivariate models
forecast.vector_ar
Vector AutoRegressive model for multivariate time series forecasting.
- class merlion.models.forecast.vector_ar.VectorARConfig(maxlags=None, target_seq_index=None, exog_transform=None, exog_aggregation_policy='Mean', exog_missing_value_policy='ZFill', max_forecast_steps=None, invert_transform=None, transform=None, **kwargs)
Bases:
ForecasterExogConfig
Config object for VectorAR forecaster.
- Parameters
maxlags (
Optional
[int
]) – Max # of lags for ARtarget_seq_index (
Optional
[int
]) – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.exog_transform – The pre-processing transform for exogenous data. Note: resampling is handled separately.
exog_aggregation_policy – The policy to use for aggregating values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
exog_missing_value_policy – The policy to use for imputing missing values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
max_forecast_steps – Max # of steps we would like to forecast for. Required for some models like MSES.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.transform – Transformation to pre-process input time series.
- class merlion.models.forecast.vector_ar.VectorAR(config)
Bases:
ForecasterExogBase
Vector AutoRegressive model for multivariate time series forecasting.
- config_class
alias of
VectorARConfig
- property require_even_sampling: bool
Whether the model assumes that training data is sampled at a fixed frequency
- property maxlags: int
forecast.trees
Tree-based models for multivariate time series forecasting.
- class merlion.models.forecast.trees.RandomForestForecasterConfig(min_samples_split=2, n_estimators=100, max_depth=None, random_state=None, maxlags=None, max_forecast_steps=None, target_seq_index=None, prediction_stride=1, exog_transform=None, exog_aggregation_policy='Mean', exog_missing_value_policy='ZFill', invert_transform=None, transform=None, **kwargs)
Bases:
_TreeEnsembleForecasterConfig
Config class for RandomForestForecaster.
- Parameters
min_samples_split (
int
) – min split for tree leavesn_estimators – number of base estimators for the tree ensemble
max_depth – max depth of base estimators
random_state – random seed for bagging
maxlags – Size of historical window to base the forecast on.
max_forecast_steps – Max # of steps we would like to forecast for.
target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
prediction_stride –
the number of steps being forecasted in a single call to underlying the model
If univariate: the sequence target of the length of prediction_stride will be utilized, forecasting will be done autoregressively, with the stride unit of prediction_stride
If multivariate:
if = 1: autoregressively forecast all variables in the time series, one step at a time
if > 1: only support directly forecasting the next prediction_stride steps in the future. Autoregression not supported. Note that the model will set prediction_stride = max_forecast_steps.
exog_transform – The pre-processing transform for exogenous data. Note: resampling is handled separately.
exog_aggregation_policy – The policy to use for aggregating values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
exog_missing_value_policy – The policy to use for imputing missing values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.transform – Transformation to pre-process input time series.
- class merlion.models.forecast.trees.RandomForestForecaster(config)
Bases:
SKLearnForecaster
Random Forest Regressor for time series forecasting
Random Forest is a meta estimator that fits a number of classifying decision trees on various sub-samples of the dataset, and uses averaging to improve the predictive accuracy and control over-fitting.
- config_class
alias of
RandomForestForecasterConfig
- class merlion.models.forecast.trees.ExtraTreesForecasterConfig(min_samples_split=2, n_estimators=100, max_depth=None, random_state=None, maxlags=None, max_forecast_steps=None, target_seq_index=None, prediction_stride=1, exog_transform=None, exog_aggregation_policy='Mean', exog_missing_value_policy='ZFill', invert_transform=None, transform=None, **kwargs)
Bases:
_TreeEnsembleForecasterConfig
Config class for ExtraTreesForecaster.
- Parameters
min_samples_split (
int
) – min split for tree leavesn_estimators – number of base estimators for the tree ensemble
max_depth – max depth of base estimators
random_state – random seed for bagging
maxlags – Size of historical window to base the forecast on.
max_forecast_steps – Max # of steps we would like to forecast for.
target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
prediction_stride –
the number of steps being forecasted in a single call to underlying the model
If univariate: the sequence target of the length of prediction_stride will be utilized, forecasting will be done autoregressively, with the stride unit of prediction_stride
If multivariate:
if = 1: autoregressively forecast all variables in the time series, one step at a time
if > 1: only support directly forecasting the next prediction_stride steps in the future. Autoregression not supported. Note that the model will set prediction_stride = max_forecast_steps.
exog_transform – The pre-processing transform for exogenous data. Note: resampling is handled separately.
exog_aggregation_policy – The policy to use for aggregating values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
exog_missing_value_policy – The policy to use for imputing missing values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.transform – Transformation to pre-process input time series.
- class merlion.models.forecast.trees.ExtraTreesForecaster(config)
Bases:
SKLearnForecaster
Extra Trees Regressor for time series forecasting
Extra Trees Regressor implements a meta estimator that fits a number of randomized decision trees (a.k.a. extra-trees) on various sub-samples of the dataset and uses averaging to improve the predictive accuracy and control over-fitting.
- config_class
alias of
ExtraTreesForecasterConfig
- class merlion.models.forecast.trees.LGBMForecasterConfig(learning_rate=0.1, n_jobs=-1, n_estimators=100, max_depth=None, random_state=None, maxlags=None, max_forecast_steps=None, target_seq_index=None, prediction_stride=1, exog_transform=None, exog_aggregation_policy='Mean', exog_missing_value_policy='ZFill', invert_transform=None, transform=None, **kwargs)
Bases:
_TreeEnsembleForecasterConfig
Config class for LGBMForecaster.
- Parameters
learning_rate (
float
) – learning rate for boostingn_jobs (
int
) – num of threading, -1 or 0 indicates device default, positive int indicates num of threadsn_estimators – number of base estimators for the tree ensemble
max_depth – max depth of base estimators
random_state – random seed for bagging
maxlags – Size of historical window to base the forecast on.
max_forecast_steps – Max # of steps we would like to forecast for.
target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
prediction_stride –
the number of steps being forecasted in a single call to underlying the model
If univariate: the sequence target of the length of prediction_stride will be utilized, forecasting will be done autoregressively, with the stride unit of prediction_stride
If multivariate:
if = 1: autoregressively forecast all variables in the time series, one step at a time
if > 1: only support directly forecasting the next prediction_stride steps in the future. Autoregression not supported. Note that the model will set prediction_stride = max_forecast_steps.
exog_transform – The pre-processing transform for exogenous data. Note: resampling is handled separately.
exog_aggregation_policy – The policy to use for aggregating values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
exog_missing_value_policy – The policy to use for imputing missing values in exogenous data, to ensure it is sampled at the same timestamps as the endogenous data.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.transform – Transformation to pre-process input time series.
- class merlion.models.forecast.trees.LGBMForecaster(config)
Bases:
SKLearnForecaster
Light gradient boosting (LGBM) regressor for time series forecasting
LightGBM is a light weight and fast gradient boosting framework that uses tree based learning algorithms, for more details, please refer to the document https://lightgbm.readthedocs.io/en/latest/Features.html
- config_class
alias of
LGBMForecasterConfig
forecast.deep_ar
Implementation of Deep AR
- class merlion.models.forecast.deep_ar.DeepARConfig(n_past, max_forecast_steps=None, hidden_size=32, num_hidden_layers=2, lags_seq=[1], num_prediction_samples=10, loss_fn=LossFunction.guassian_nll, **kwargs)
Bases:
DeepForecasterConfig
,NormalizingConfig
DeepAR: Probabilistic Forecasting with Autoregressive Recurrent Networks: https://arxiv.org/abs/1704.04110
- Parameters
n_past – # of past steps used for forecasting future.
max_forecast_steps (
Optional
[int
]) – Max # of steps we would like to forecast for.hidden_size (
Optional
[int
]) – hidden_size of the LSTM layersnum_hidden_layers (
int
) – # of hidden layers in LSTMlags_seq (
List
[int
]) – Indices of the lagged observations that the RNN takes as input. For example,[1]
indicates that the RNN only takes the observation at timet-1
to produce the output for timet
.num_prediction_samples (
int
) – # of samples to produce the forecastingloss_fn (
Union
[str
,LossFunction
]) – Loss function for optimizing deep learning models. The value of loss_fn can bemse
for l2 loss,l1
for l1 loss,huber
for huber loss.batch_size – Batch size of a batch for stochastic training of deep models
num_epochs – Total number of epochs for training.
optimizer – The optimizer for learning the parameters of the deep learning models. The value of optimizer can be
Adam
,AdamW
,SGD
,Adagrad
,RMSprop
.clip_gradient – Clipping gradient norm of model parameters before updating. If
clip_gradient is None
, then the gradient will not be clipped.use_gpu – Whether to use gpu for training deep models. If
use_gpu = True
while thre is no GPU device, the model will use CPU for training instead.ts_encoding – whether the timestamp should be encoded to a float vector, which can be used for training deep learning based time series models; if
None
, the timestamp is not encoded. If notNone
, it represents the frequency for time features encoding options:[s:secondly, t:minutely, h:hourly, d:daily, b:business days, w:weekly, m:monthly]lr – Learning rate for optimizing deep learning models.
weight_decay – Weight decay (L2 penalty) (default: 0)
valid_fraction – Fraction of validation set to be split from training data
early_stop_patience – Number of epochs with no improvement after which training will be stopped for early stopping function. If
early_stop_patience = None
, the training process will not stop early.transform – Transformation to pre-process input time series.
target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.normalize – Pre-trained normalization transformation (optional).
- class merlion.models.forecast.deep_ar.DeepARModel(config)
Bases:
TorchModel
Implementaion of Deep AR model
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- static get_lagged_subsequences(sequence, sequence_length, indices, subsequences_length=1)
- Return type
Tensor
- unroll_encoder(past, past_timestamp, future_timestamp, future=None)
- calculate_loss(past, past_timestamp, future, future_timestamp)
- sampling_decoder(past, time_features, begin_states)
- forward(past, past_timestamp, future_timestamp, mean_samples=True)
Defines the computation performed at every call.
Should be overridden by all subclasses.
Note
Although the recipe for forward pass needs to be defined within this function, one should call the
Module
instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.
- class merlion.models.forecast.deep_ar.DeepARForecaster(config)
Bases:
DeepForecaster
Implementaion of Deep AR model forecaster
- config_class
alias of
DeepARConfig
- deep_model_class
alias of
DeepARModel
forecast.autoformer
Implementation of Autoformer.
- class merlion.models.forecast.autoformer.AutoformerConfig(n_past, max_forecast_steps=None, moving_avg=25, encoder_input_size=None, decoder_input_size=None, num_encoder_layers=2, num_decoder_layers=1, start_token_len=0, factor=3, model_dim=512, embed='timeF', dropout=0.05, activation='gelu', n_heads=8, fcn_dim=2048, **kwargs)
Bases:
DeepForecasterConfig
,NormalizingConfig
Decomposition Transformers with Auto-Correlation for Long-Term Series Forecasting: https://arxiv.org/abs/2106.13008. Code adapted from https://github.com/thuml/Autoformer.
- Parameters
n_past – # of past steps used for forecasting future.
max_forecast_steps (
Optional
[int
]) – Max # of steps we would like to forecast for.moving_avg (
int
) – Window size of moving average for Autoformer.encoder_input_size (
Optional
[int
]) – Input size of encoder. Ifencoder_input_size = None
, then the model will automatically useconfig.dim
, which is the dimension of the input data.decoder_input_size (
Optional
[int
]) – Input size of decoder. Ifdecoder_input_size = None
, then the model will automatically useconfig.dim
, which is the dimension of the input data.num_encoder_layers (
int
) – Number of encoder layers.num_decoder_layers (
int
) – Number of decoder layers.start_token_len (
int
) – Length of start token for deep transformer encoder-decoder based models. The start token is similar to the special tokens for NLP models (e.g., bos, sep, eos tokens).factor (
int
) – Attention factor.model_dim (
int
) – Dimension of the model.embed (
str
) – Time feature encoding type, options includetimeF
,fixed
andlearned
.dropout (
float
) – dropout rate.activation (
str
) – Activation function, can begelu
,relu
,sigmoid
, etc.n_heads (
int
) – Number of heads of the model.fcn_dim (
int
) – Hidden dimension of the MLP layer in the model.batch_size – Batch size of a batch for stochastic training of deep models
num_epochs – Total number of epochs for training.
optimizer – The optimizer for learning the parameters of the deep learning models. The value of optimizer can be
Adam
,AdamW
,SGD
,Adagrad
,RMSprop
.loss_fn – Loss function for optimizing deep learning models. The value of loss_fn can be
mse
for l2 loss,l1
for l1 loss,huber
for huber loss.clip_gradient – Clipping gradient norm of model parameters before updating. If
clip_gradient is None
, then the gradient will not be clipped.use_gpu – Whether to use gpu for training deep models. If
use_gpu = True
while thre is no GPU device, the model will use CPU for training instead.ts_encoding – whether the timestamp should be encoded to a float vector, which can be used for training deep learning based time series models; if
None
, the timestamp is not encoded. If notNone
, it represents the frequency for time features encoding options:[s:secondly, t:minutely, h:hourly, d:daily, b:business days, w:weekly, m:monthly]lr – Learning rate for optimizing deep learning models.
weight_decay – Weight decay (L2 penalty) (default: 0)
valid_fraction – Fraction of validation set to be split from training data
early_stop_patience – Number of epochs with no improvement after which training will be stopped for early stopping function. If
early_stop_patience = None
, the training process will not stop early.transform – Transformation to pre-process input time series.
target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.normalize – Pre-trained normalization transformation (optional).
- class merlion.models.forecast.autoformer.AutoformerModel(config)
Bases:
TorchModel
Implementaion of Autoformer deep torch model.
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(past, past_timestamp, future_timestamp, enc_self_mask=None, dec_self_mask=None, dec_enc_mask=None, **kwargs)
Defines the computation performed at every call.
Should be overridden by all subclasses.
Note
Although the recipe for forward pass needs to be defined within this function, one should call the
Module
instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.
- class merlion.models.forecast.autoformer.AutoformerForecaster(config)
Bases:
DeepForecaster
Implementaion of Autoformer deep forecaster.
- config_class
alias of
AutoformerConfig
- deep_model_class
alias of
AutoformerModel
forecast.etsformer
Implementation of ETSformer.
- class merlion.models.forecast.etsformer.ETSformerConfig(n_past, max_forecast_steps=None, encoder_input_size=None, decoder_input_size=None, num_encoder_layers=2, num_decoder_layers=2, model_dim=512, dropout=0.2, n_heads=8, fcn_dim=2048, top_K=1, sigma=0.2, **kwargs)
Bases:
DeepForecasterConfig
,NormalizingConfig
ETSformer: Exponential Smoothing Transformers for Time-series Forecasting: https://arxiv.org/abs/2202.01381 Code adapted from https://github.com/salesforce/ETSformer.
- Parameters
n_past – # of past steps used for forecasting future.
max_forecast_steps (
Optional
[int
]) – Max # of steps we would like to forecast for.encoder_input_size (
Optional
[int
]) – Input size of encoder. Ifencoder_input_size = None
, then the model will automatically useconfig.dim
, which is the dimension of the input data.decoder_input_size (
Optional
[int
]) – Input size of decoder. Ifdecoder_input_size = None
, then the model will automatically useconfig.dim
, which is the dimension of the input data.num_encoder_layers (
int
) – Number of encoder layers.num_decoder_layers (
int
) – Number of decoder layers.model_dim (
int
) – Dimension of the model.dropout (
float
) – dropout rate.n_heads (
int
) – Number of heads of the model.fcn_dim (
int
) – Hidden dimension of the MLP layer in the model.top_K (
int
) – Top-K Frequent Fourier basis.sigma – Standard derivation for ETS input data transform.
batch_size – Batch size of a batch for stochastic training of deep models
num_epochs – Total number of epochs for training.
optimizer – The optimizer for learning the parameters of the deep learning models. The value of optimizer can be
Adam
,AdamW
,SGD
,Adagrad
,RMSprop
.loss_fn – Loss function for optimizing deep learning models. The value of loss_fn can be
mse
for l2 loss,l1
for l1 loss,huber
for huber loss.clip_gradient – Clipping gradient norm of model parameters before updating. If
clip_gradient is None
, then the gradient will not be clipped.use_gpu – Whether to use gpu for training deep models. If
use_gpu = True
while thre is no GPU device, the model will use CPU for training instead.ts_encoding – whether the timestamp should be encoded to a float vector, which can be used for training deep learning based time series models; if
None
, the timestamp is not encoded. If notNone
, it represents the frequency for time features encoding options:[s:secondly, t:minutely, h:hourly, d:daily, b:business days, w:weekly, m:monthly]lr – Learning rate for optimizing deep learning models.
weight_decay – Weight decay (L2 penalty) (default: 0)
valid_fraction – Fraction of validation set to be split from training data
early_stop_patience – Number of epochs with no improvement after which training will be stopped for early stopping function. If
early_stop_patience = None
, the training process will not stop early.transform – Transformation to pre-process input time series.
target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.normalize – Pre-trained normalization transformation (optional).
- class merlion.models.forecast.etsformer.ETSformerModel(config)
Bases:
TorchModel
Implementaion of ETSformer deep torch model.
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(past, past_timestamp, future_timestamp, enc_self_mask=None, dec_self_mask=None, dec_enc_mask=None, attention=False, **kwargs)
Defines the computation performed at every call.
Should be overridden by all subclasses.
Note
Although the recipe for forward pass needs to be defined within this function, one should call the
Module
instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.
- transform(x)
- jitter(x)
- scale(x)
- shift(x)
- class merlion.models.forecast.etsformer.ETSformerForecaster(config)
Bases:
DeepForecaster
Implementaion of ETSformer deep forecaster.
- config_class
alias of
ETSformerConfig
- deep_model_class
alias of
ETSformerModel
forecast.informer
Implementation of Informer.
- class merlion.models.forecast.informer.InformerConfig(n_past, max_forecast_steps=None, encoder_input_size=None, decoder_input_size=None, num_encoder_layers=2, num_decoder_layers=1, start_token_len=0, factor=3, model_dim=512, embed='timeF', dropout=0.05, activation='gelu', n_heads=8, fcn_dim=2048, distil=True, **kwargs)
Bases:
DeepForecasterConfig
,NormalizingConfig
Informer: Beyond Efficient Transformer for Long Sequence Time-Series Forecasting: https://arxiv.org/abs/2012.07436 Code adapted from https://github.com/thuml/Autoformer.
- Parameters
n_past – # of past steps used for forecasting future.
max_forecast_steps (
Optional
[int
]) – Max # of steps we would like to forecast for.encoder_input_size (
Optional
[int
]) – Input size of encoder. Ifencoder_input_size = None
, then the model will automatically useconfig.dim
, which is the dimension of the input data.decoder_input_size (
Optional
[int
]) – Input size of decoder. Ifdecoder_input_size = None
, then the model will automatically useconfig.dim
, which is the dimension of the input data.num_encoder_layers (
int
) – Number of encoder layers.num_decoder_layers (
int
) – Number of decoder layers.start_token_len (
int
) – Length of start token for deep transformer encoder-decoder based models. The start token is similar to the special tokens for NLP models (e.g., bos, sep, eos tokens).factor (
int
) – Attention factor.model_dim (
int
) – Dimension of the model.embed (
str
) – Time feature encoding type, options includetimeF
,fixed
andlearned
.dropout (
float
) – dropout rate.activation (
str
) – Activation function, can begelu
,relu
,sigmoid
, etc.n_heads (
int
) – Number of heads of the model.fcn_dim (
int
) – Hidden dimension of the MLP layer in the model.distil (
bool
) – whether to use distilling in the encoder of the model.batch_size – Batch size of a batch for stochastic training of deep models
num_epochs – Total number of epochs for training.
optimizer – The optimizer for learning the parameters of the deep learning models. The value of optimizer can be
Adam
,AdamW
,SGD
,Adagrad
,RMSprop
.loss_fn – Loss function for optimizing deep learning models. The value of loss_fn can be
mse
for l2 loss,l1
for l1 loss,huber
for huber loss.clip_gradient – Clipping gradient norm of model parameters before updating. If
clip_gradient is None
, then the gradient will not be clipped.use_gpu – Whether to use gpu for training deep models. If
use_gpu = True
while thre is no GPU device, the model will use CPU for training instead.ts_encoding – whether the timestamp should be encoded to a float vector, which can be used for training deep learning based time series models; if
None
, the timestamp is not encoded. If notNone
, it represents the frequency for time features encoding options:[s:secondly, t:minutely, h:hourly, d:daily, b:business days, w:weekly, m:monthly]lr – Learning rate for optimizing deep learning models.
weight_decay – Weight decay (L2 penalty) (default: 0)
valid_fraction – Fraction of validation set to be split from training data
early_stop_patience – Number of epochs with no improvement after which training will be stopped for early stopping function. If
early_stop_patience = None
, the training process will not stop early.transform – Transformation to pre-process input time series.
target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.normalize – Pre-trained normalization transformation (optional).
- class merlion.models.forecast.informer.InformerModel(config)
Bases:
TorchModel
Implementaion of informer deep torch model.
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(past, past_timestamp, future_timestamp, enc_self_mask=None, dec_self_mask=None, dec_enc_mask=None, **kwargs)
Defines the computation performed at every call.
Should be overridden by all subclasses.
Note
Although the recipe for forward pass needs to be defined within this function, one should call the
Module
instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.
- class merlion.models.forecast.informer.InformerForecaster(config)
Bases:
DeepForecaster
Implementaion of Informer deep forecaster.
- config_class
alias of
InformerConfig
- deep_model_class
alias of
InformerModel
forecast.transformer
Implementation of Transformer for time series data.
- class merlion.models.forecast.transformer.TransformerConfig(n_past, max_forecast_steps=None, encoder_input_size=None, decoder_input_size=None, num_encoder_layers=2, num_decoder_layers=1, start_token_len=0, factor=3, model_dim=512, embed='timeF', dropout=0.05, activation='gelu', n_heads=8, fcn_dim=2048, distil=True, **kwargs)
Bases:
DeepForecasterConfig
,NormalizingConfig
Transformer for time series forecasting. Code adapted from https://github.com/thuml/Autoformer.
- Parameters
n_past – # of past steps used for forecasting future.
max_forecast_steps (
Optional
[int
]) – Max # of steps we would like to forecast for.encoder_input_size (
Optional
[int
]) – Input size of encoder. Ifencoder_input_size = None
, then the model will automatically useconfig.dim
, which is the dimension of the input data.decoder_input_size (
Optional
[int
]) – Input size of decoder. Ifdecoder_input_size = None
, then the model will automatically useconfig.dim
, which is the dimension of the input data.num_encoder_layers (
int
) – Number of encoder layers.num_decoder_layers (
int
) – Number of decoder layers.start_token_len (
int
) – Length of start token for deep transformer encoder-decoder based models. The start token is similar to the special tokens for NLP models (e.g., bos, sep, eos tokens).factor (
int
) – Attention factor.model_dim (
int
) – Dimension of the model.embed (
str
) – Time feature encoding type, options includetimeF
,fixed
andlearned
.dropout (
float
) – dropout rate.activation (
str
) – Activation function, can begelu
,relu
,sigmoid
, etc.n_heads (
int
) – Number of heads of the model.fcn_dim (
int
) – Hidden dimension of the MLP layer in the model.distil (
bool
) – whether to use distilling in the encoder of the model.batch_size – Batch size of a batch for stochastic training of deep models
num_epochs – Total number of epochs for training.
optimizer – The optimizer for learning the parameters of the deep learning models. The value of optimizer can be
Adam
,AdamW
,SGD
,Adagrad
,RMSprop
.loss_fn – Loss function for optimizing deep learning models. The value of loss_fn can be
mse
for l2 loss,l1
for l1 loss,huber
for huber loss.clip_gradient – Clipping gradient norm of model parameters before updating. If
clip_gradient is None
, then the gradient will not be clipped.use_gpu – Whether to use gpu for training deep models. If
use_gpu = True
while thre is no GPU device, the model will use CPU for training instead.ts_encoding – whether the timestamp should be encoded to a float vector, which can be used for training deep learning based time series models; if
None
, the timestamp is not encoded. If notNone
, it represents the frequency for time features encoding options:[s:secondly, t:minutely, h:hourly, d:daily, b:business days, w:weekly, m:monthly]lr – Learning rate for optimizing deep learning models.
weight_decay – Weight decay (L2 penalty) (default: 0)
valid_fraction – Fraction of validation set to be split from training data
early_stop_patience – Number of epochs with no improvement after which training will be stopped for early stopping function. If
early_stop_patience = None
, the training process will not stop early.transform – Transformation to pre-process input time series.
target_seq_index – The index of the univariate (amongst all univariates in a general multivariate time series) whose value we would like to forecast.
invert_transform – Whether to automatically invert the
transform
before returning a forecast. By default, we will invert the transform for all base forecasters if it supports a proper inversion, but we will not invert it for forecaster-based anomaly detectors or transforms without proper inversions.normalize – Pre-trained normalization transformation (optional).
- class merlion.models.forecast.transformer.TransformerModel(config)
Bases:
TorchModel
Implementaion of Transformer deep torch model.
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(past, past_timestamp, future_timestamp, enc_self_mask=None, dec_self_mask=None, dec_enc_mask=None, **kwargs)
Defines the computation performed at every call.
Should be overridden by all subclasses.
Note
Although the recipe for forward pass needs to be defined within this function, one should call the
Module
instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.
- class merlion.models.forecast.transformer.TransformerForecaster(config)
Bases:
DeepForecaster
Implementaion of Transformer deep forecaster
- config_class
alias of
TransformerConfig
- deep_model_class
alias of
TransformerModel