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.