merlion.models.automl package

Contains all AutoML layers.

`layer_mixin`
`forecasting_layer_base`
`autosarima`
`seasonality_mixin`

Submodules

merlion.models.automl.layer_mixin module

class merlion.models.automl.layer_mixin.LayerMixIn(config)

Bases: ModelBase, ABC

Base Interface for Implemented Layers

This abstract class contains all of the methods that Layers should implement. Ideally, these would be generated by an existing mix-in.

generate_theta(train_data)

Parameters: train_data (TimeSeries) – Training data to use for generation of hyperparameters :math:` heta`

Returns an iterator of hyperparameter candidates for consideration with th underlying model.

Return type: Iterator

evaluate_theta(thetas, train_data, train_config=None)

Parameters

thetas (Iterator) – Iterator of the hyperparameter candidates
train_data (TimeSeries) – Training data
train_config – Training configuration

Return the optimal hyperparameter, as well as optionally a model and result of the training procedure.

Return type: Tuple[Any, Optional[ForecasterBase], Optional[Tuple[TimeSeries, Optional[TimeSeries]]]]

set_theta(model, theta, train_data=None)

Parameters

model – Underlying base model to which the new theta is applied
theta – Hyperparameter to apply
train_data (Optional[TimeSeries]) – Training data (Optional)

Sets the hyperparameter to the provided model. This is used to apply the :math:` heta` to the model, since this behavior is custom to every model. Oftentimes in internal implementations, model is the optimal model.

merlion.models.automl.forecasting_layer_base module

class merlion.models.automl.forecasting_layer_base.ForecasterAutoMLBase(model, **kwargs)

Bases: ForecasterBase, LayerMixIn, ABC

Base Implementation of AutoML Layer Logic.

Custom train and forecast methods that call rely on implementations of LayerMixIn to perform the training and forecasting procedures.

Note: Layer models don’t have a config but any calls to their config will bubble down to the underlying model. This may be a blessing or a curse.

Assume config also inherits ForecastConfig

reset(): Resets the model’s internal state.

train(train_data, train_config=None)

Trains the model on the specified time series, optionally with some additional implementation-specific config options train_config.

Parameters

train_data (TimeSeries) – a TimeSeries to use as a training set
train_config – additional configurations (if needed)

Return type

Tuple[TimeSeries, Optional[TimeSeries]]

forecast(time_stamps, time_series_prev=None, return_iqr=False, return_prev=False)

Returns the model’s forecast on the timestamps given. Note that if self.transform is specified in the config, the forecast is a forecast of transformed values! It is up to you to manually invert the transform if desired.

Parameters

time_stamps (Union[int, List[int]]) – Either a list of timestamps we wish to forecast for, or the number of steps (int) we wish to forecast for.
time_series_prev (Optional[TimeSeries]) – a list of (timestamp, value) pairs immediately preceding time_series. If given, we use it to initialize the time series model. Otherwise, we assume that time_series immediately follows the training data.
return_iqr (bool) – whether to return the inter-quartile range for the forecast. Note that not all models support this option.
return_prev (bool) – whether to return the forecast for time_series_prev (and its stderr or IQR if relevant), in addition to the forecast for time_stamps. Only used if time_series_prev is provided.

Return type

Union[Tuple[TimeSeries, Optional[TimeSeries]], Tuple[TimeSeries, TimeSeries, TimeSeries]]

Returns

(forecast, forecast_stderr) if return_iqr is false, (forecast, forecast_lb, forecast_ub) otherwise.

forecast: the forecast for the timestamps given
forecast_stderr: the standard error of each forecast value.
May be None.
forecast_lb: 25th percentile of forecast values for each timestamp
forecast_ub: 75th percentile of forecast values for each timestamp

save(dirname, **save_config)

Parameters

dirname (str) – directory to save the model & its config
save_config – additional configurations (if needed)

classmethod load(dirname, **kwargs)

Parameters

dirname (str) – directory to load model (and config) from
kwargs – config params to override manually

Returns

ModelBase object loaded from file

timedelta: Optional[float]: The expected number of seconds between observations in an input time series. should be set in ForecasterBase.train if the model assumes a fixed timedelta.

last_train_time: Optional[float]: The last unix timestamp of the training data. Should be set in ForecasterBase.train.

merlion.models.automl.autosarima module

class merlion.models.automl.autosarima.AutoSarimaConfig(max_forecast_steps=None, target_seq_index=None, order=('auto', 'auto', 'auto'), seasonal_order=('auto', 'auto', 'auto', 'auto'), periodicity_strategy='max', maxiter=None, max_k=100, max_dur=3600, approximation=None, approx_iter=None, **kwargs)

Bases: SarimaConfig

Config object used to define a forecaster model.

Configuration class for AutoSarima. For order and seasonal_order, ‘auto’ indicates automatically select the parameter. Now autosarima support automatically select differencing order, length of the seasonality cycle, seasonal differencing order, and the rest of AR, MA, seasonal AR and seasonal MA parameters. Note that automatic selection of AR, MA, seasonal AR and seasonal MA parameters are implemented in a coupled way. Only when all these parameters are specified it will not trigger the automatic selection.

Parameters

max_forecast_steps (Optional[int]) – Max number of steps we aim to forecast
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.
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 – 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.
periodicity_strategy (str) – selection strategy when detecting multiple periods. ‘min’ signifies to select the smallest period, while ‘max’ signifies to select the largest period
maxiter (Optional[int]) – The maximum number of iterations to perform
max_k (int) – Maximum number of models considered in the stepwise search
max_dur (float) – Maximum training time considered in the stepwise search
approximation (Optional[bool]) – Whether to use approx_iter iterations (instead of maxiter) to speed up computation. If None, we use approximation mode when the training data is too long (>150), or when the length off the period is too high (periodicity > 12).
approx_iter (Optional[int]) – The number of iterations to perform in approximation mode

class merlion.models.automl.autosarima.AutoSarima(model=None, **kwargs)

Bases: ForecasterAutoMLBase

Assume config also inherits ForecastConfig

config_class: alias of AutoSarimaConfig

generate_theta(train_data)

generate [action, theta]. action is an indicator for stepwise seach (stepwsie) of p, q, P, Q, trend parameters or use a predefined parameter combination (pqPQ) theta is a list of parameter combination [order, seasonal_order, trend]

Return type: Iterator

evaluate_theta(thetas, train_data, train_config=None)

Parameters

thetas (Iterator) – Iterator of the hyperparameter candidates
train_data (TimeSeries) – Training data
train_config – Training configuration

Return the optimal hyperparameter, as well as optionally a model and result of the training procedure.

Return type: Tuple[Any, Optional[ForecasterBase], Optional[Tuple[TimeSeries, Optional[TimeSeries]]]]

set_theta(model, theta, train_data=None)

Parameters

model – Underlying base model to which the new theta is applied
theta – Hyperparameter to apply
train_data (Optional[TimeSeries]) – Training data (Optional)

Sets the hyperparameter to the provided model. This is used to apply the :math:` heta` to the model, since this behavior is custom to every model. Oftentimes in internal implementations, model is the optimal model.

timedelta: Optional[float]: The expected number of seconds between observations in an input time series. should be set in ForecasterBase.train if the model assumes a fixed timedelta.

last_train_time: Optional[float]: The last unix timestamp of the training data. Should be set in ForecasterBase.train.

merlion.models.automl.seasonality_mixin module

class merlion.models.automl.seasonality_mixin.SeasonalityModel

Bases: ABC

Class provides simple implementation to set the seasonality in a model. Extend this class to implement custom behavior for seasonality processing.

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 – Training data (or numpy array representing the target univariate) for any model-specific adjustments you might want to make.

class merlion.models.automl.seasonality_mixin.SeasonalityLayer(model, **kwargs)

Bases: ForecasterAutoMLBase, ABC

Seasonality Layer that uses AutoSARIMA-like methods to determine seasonality of your data. Can be used directly on any model that implements SeasonalityModel class.

Assume config also inherits ForecastConfig

set_theta(model, theta, train_data=None)

Parameters

model – Underlying base model to which the new theta is applied
theta – Hyperparameter to apply
train_data (Optional[TimeSeries]) – Training data (Optional)

Sets the hyperparameter to the provided model. This is used to apply the :math:` heta` to the model, since this behavior is custom to every model. Oftentimes in internal implementations, model is the optimal model.

evaluate_theta(thetas, train_data, train_config=None)

Parameters

thetas (Iterator) – Iterator of the hyperparameter candidates
train_data (TimeSeries) – Training data
train_config – Training configuration

Return the optimal hyperparameter, as well as optionally a model and result of the training procedure.

Return type: Tuple[Any, Optional[ForecasterBase], Optional[Tuple[TimeSeries, Optional[TimeSeries]]]]

generate_theta(train_data)

Parameters: train_data (TimeSeries) – Training data to use for generation of hyperparameters :math:` heta`

Returns an iterator of hyperparameter candidates for consideration with th underlying model.

Return type: Iterator

timedelta: Optional[float]: The expected number of seconds between observations in an input time series. should be set in ForecasterBase.train if the model assumes a fixed timedelta.

last_train_time: Optional[float]: The last unix timestamp of the training data. Should be set in ForecasterBase.train.