merlion.models.automl package

Contains all AutoML layers.

base

Base class/mixin for AutoML hyperparameter search.

seasonality

Automatic seasonality detection.

autoets

Automatic seasonality detection for ETS.

autoprophet

Automatic (multi)-seasonality detection for Facebook's Prophet.

autosarima

Automatic hyperparameter selection for SARIMA.

Submodules

merlion.models.automl.base module

Base class/mixin for AutoML hyperparameter search.

class merlion.models.automl.base.AutoMLMixIn(config=None, model=None, **kwargs)

Bases: LayeredModel

Base Interface for Implemented AutoML Layers

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

config_class

alias of LayeredModelConfig

train(train_data, **kwargs)

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)

abstract generate_theta(train_data)
Parameters

train_data (TimeSeries) – Training data to use for generation of hyperparameters \(\theta\)

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

Return type

Iterator

abstract 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]]]]

abstract 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 \(\theta\) to the model, since this behavior is custom to every model. Oftentimes in internal implementations, model is the optimal model.

merlion.models.automl.autosarima module

Automatic hyperparameter selection for SARIMA.

class merlion.models.automl.autosarima.AutoSarimaConfig(model=None, auto_seasonality=True, periodicity_strategy=PeriodicityStrategy.ACF, auto_pqPQ=True, auto_d=True, auto_D=True, maxiter=None, max_k=100, max_dur=3600, approximation=None, approx_iter=None, pval=0.05, model_kwargs=None, transform=None, **kwargs)

Bases: SeasonalityConfig

Configuration class for AutoSarima. Acts as a wrapper around a Sarima model, which automatically detects the seasonality, (seasonal) differencing order, and (seasonal) AR/MA orders. If a non-numeric value is specified for any of the relevant parameters in the order or seasonal order, we assume that the user wishes to detect that parameter automatically.

Note

The automatic selection of AR, MA, seasonal AR, and seasonal MA parameters is implemented in a coupled way. The user must specify all of these parameters explicitly to avoid automatic selection.

Parameters
  • model (Union[Sarima, dict, None]) – The model being wrapped, or a dict representing it.

  • auto_seasonality (bool) – Whether to automatically detect the seasonality.

  • periodicity_strategy (PeriodicityStrategy) – Strategy to choose the seasonality if multiple candidates are detected.

  • auto_pqPQ (bool) – Whether to automatically choose AR/MA orders p, q and seasonal AR/MA orders P, Q.

  • auto_d (bool) – Whether to automatically choose the difference order d.

  • auto_D (bool) – Whether to automatically choose the seasonal difference order D.

  • 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

  • pval – p-value for deciding whether a detected seasonality is statistically significant.

  • model_kwargs – Keyword arguments used specifically to initialize the underlying model. Only used if model is a dict. Will override keys in the model dict if specified.

  • transform – Transformation to pre-process input time series.

  • kwargs – Any other keyword arguments (e.g. for initializing a base class). If model is a dict, we will also try to pass these arguments when creating the actual underlying model. However, they will not override arguments in either the model dict or model_kwargs dict.

property order
property seasonal_order
class merlion.models.automl.autosarima.AutoSarima(config=None, model=None, **kwargs)

Bases: SeasonalityLayer

config_class

alias of AutoSarimaConfig

require_even_sampling = True
require_univariate = True
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[Sarima], 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 \(\theta\) to the model, since this behavior is custom to every model. Oftentimes in internal implementations, model is the optimal model.

merlion.models.automl.seasonality module

Automatic seasonality detection.

class merlion.models.automl.seasonality.PeriodicityStrategy(value)

Bases: Enum

Strategy to choose the seasonality if multiple candidates are detected.

ACF = 1

Select the seasonality value with the highest autocorrelation.

Min = 2

Select the minimum seasonality.

Max = 3

Select the maximum seasonality.

All = 4

Use all seasonalities. Only valid for models which support multiple seasonalities.

class merlion.models.automl.seasonality.SeasonalityModel

Bases: object

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

abstract 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.

class merlion.models.automl.seasonality.SeasonalityConfig(model, periodicity_strategy=PeriodicityStrategy.ACF, pval=0.05, model_kwargs=None, transform=None, **kwargs)

Bases: LayeredModelConfig

Config object for an automatic seasonality detection layer.

Parameters
  • model – The model being wrapped, or a dict representing it.

  • periodicity_strategy – Strategy to choose the seasonality if multiple candidates are detected.

  • pval (float) – p-value for deciding whether a detected seasonality is statistically significant.

  • model_kwargs – Keyword arguments used specifically to initialize the underlying model. Only used if model is a dict. Will override keys in the model dict if specified.

  • transform – Transformation to pre-process input time series.

  • kwargs – Any other keyword arguments (e.g. for initializing a base class). If model is a dict, we will also try to pass these arguments when creating the actual underlying model. However, they will not override arguments in either the model dict or model_kwargs dict.

property multi_seasonality
Returns

Whether the model supports multiple seasonalities. False unless explicitly overridden.

property periodicity_strategy: PeriodicityStrategy
Return type

PeriodicityStrategy

Returns

Strategy to choose the seasonality if multiple candidates are detected.

to_dict(_skipped_keys=None)
Returns

dict with keyword arguments used to initialize the config class.

class merlion.models.automl.seasonality.SeasonalityLayer(config=None, model=None, **kwargs)

Bases: AutoMLMixIn

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

config_class

alias of SeasonalityConfig

require_even_sampling = False
property require_univariate

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

property multi_seasonality
Returns

Whether the model supports multiple seasonalities.

property periodicity_strategy
Returns

Strategy to choose the seasonality if multiple candidates are detected.

property pval
Returns

p-value for deciding whether a detected seasonality is statistically significant.

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 \(\theta\) 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[ModelBase], Optional[Tuple[TimeSeries, Optional[TimeSeries]]]]

generate_theta(train_data)
Parameters

train_data (TimeSeries) – Training data to use for generation of hyperparameters \(\theta\)

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

Return type

Iterator