merlion.models.ensemble package

Ensembles of models and automated model selection.

base

Base class for ensembles of models.

combine

Rules for combining the outputs of multiple time series models.

anomaly

Ensembles of anomaly detectors.

forecast

Ensembles of forecasters.

Submodules

merlion.models.ensemble.base module

Base class for ensembles of models.

class merlion.models.ensemble.base.EnsembleConfig(models=None, combiner=None, transform=None, **kwargs)

Bases: Config

An ensemble config contains the each individual model in the ensemble, as well as the Combiner object to combine those models’ outputs. The rationale behind placing the model objects in the EnsembleConfig (rather than in the Ensemble itself) is discussed in more detail in the documentation for LayeredModel.

Parameters
  • models (Optional[List[Union[ModelBase, Dict]]]) – A list of models or dicts representing them.

  • combiner (Optional[CombinerBase]) – The CombinerBase object to combine the outputs of the models in the ensemble.

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

  • kwargs – Any additional kwargs for Config

models: List[ModelBase]
to_dict(_skipped_keys=None)
Returns

dict with keyword arguments used to initialize the config class.

class merlion.models.ensemble.base.EnsembleTrainConfig(valid_frac, per_model_train_configs=None)

Bases: object

Config object describing how to train an ensemble.

Parameters
  • valid_frac – fraction of training data to use for validation.

  • per_model_train_configs – list of train configs to use for individual models, one per model. None means that you use the default for all models. Specifying None for an individual model means that you use the default for that model.

class merlion.models.ensemble.base.EnsembleBase(config=None, models=None)

Bases: ModelBase

An abstract class representing an ensemble of multiple models.

Parameters
  • config (Optional[EnsembleConfig]) – The ensemble’s config

  • models (Optional[List[ModelBase]]) – The models in the ensemble. Only provide this argument if you did not specify config.models.

config_class

alias of EnsembleConfig

property models
property combiner: CombinerBase
Return type

CombinerBase

Returns

the object used to combine model outputs.

reset()

Resets the model’s internal state.

property models_used
train_valid_split(transformed_train_data, train_config)
Return type

Tuple[TimeSeries, TimeSeries]

get_max_common_horizon()
truncate_valid_data(transformed_valid_data)
train_combiner(all_model_outs, target)
Return type

TimeSeries

save(dirname, save_only_used_models=False, **save_config)

Saves the ensemble of models.

Parameters
  • dirname (str) – directory to save the ensemble to

  • save_only_used_models – whether to save only the models that are actually used by the ensemble.

  • save_config – additional save config arguments

to_bytes(save_only_used_models=False, **save_config)

Converts the entire model state and configuration to a single byte object.

Parameters
  • save_only_used_models – whether to save only the models that are actually used by the ensemble.

  • save_config – additional configurations (if needed)

merlion.models.ensemble.combine module

Rules for combining the outputs of multiple time series models.

class merlion.models.ensemble.combine.CombinerBase(abs_score=False)

Bases: object

Abstract base class for combining the outputs of multiple models. Subclasses should implement the abstract method _combine_univariates. All combiners are callable objects.

__call__(all_model_outs, target, _check_dim=True)

Applies the model combination rule to combine multiple model outputs.

Parameters
  • all_model_outs (List[TimeSeries]) – a list of time series, with each time series representing the output of a single model.

  • target (TimeSeries) – a target time series (e.g. labels)

Return type

TimeSeries

Returns

a single time series of combined model outputs on this training data.

Parameters

abs_score – whether to take the absolute value of the model outputs. Useful for anomaly detection.

property requires_training
to_dict(_skipped_keys=None)
classmethod from_dict(state)
property models_used: List[bool]
Return type

List[bool]

Returns

which models are actually used to make predictions.

train(all_model_outs, target=None)

Trains the model combination rule.

Parameters
  • all_model_outs (List[TimeSeries]) – a list of time series, with each time series representing the output of a single model.

  • target (Optional[TimeSeries]) – a target time series (e.g. labels)

Return type

TimeSeries

Returns

a single time series of combined model outputs on this training data.

class merlion.models.ensemble.combine.Mean(abs_score=False)

Bases: CombinerBase

Combines multiple models by taking their mean prediction.

Parameters

abs_score – whether to take the absolute value of the model outputs. Useful for anomaly detection.

property weights: ndarray
Return type

ndarray

class merlion.models.ensemble.combine.Median(abs_score=False)

Bases: CombinerBase

Combines multiple models by taking their median prediction.

Parameters

abs_score – whether to take the absolute value of the model outputs. Useful for anomaly detection.

class merlion.models.ensemble.combine.Max(abs_score=False)

Bases: CombinerBase

Combines multiple models by taking their max prediction.

Parameters

abs_score – whether to take the absolute value of the model outputs. Useful for anomaly detection.

class merlion.models.ensemble.combine.ModelSelector(metric, abs_score=False)

Bases: Mean

Takes the mean of the best models, where the models are ranked according to the value of an evaluation metric.

Parameters
  • metric (Union[str, TSADMetric, ForecastMetric]) – the evaluation metric to use

  • abs_score – whether to take the absolute value of the model outputs. Useful for anomaly detection.

property invert
property requires_training
to_dict(_skipped_keys=None)
classmethod from_dict(state)
property models_used: List[bool]
Return type

List[bool]

Returns

which models are actually used to make predictions.

train(all_model_outs, target=None, **kwargs)

Trains the model combination rule.

Parameters
  • all_model_outs (List[TimeSeries]) – a list of time series, with each time series representing the output of a single model.

  • target (Optional[TimeSeries]) – a target time series (e.g. labels)

Return type

TimeSeries

Returns

a single time series of combined model outputs on this training data.

class merlion.models.ensemble.combine.MetricWeightedMean(metric, abs_score=False)

Bases: ModelSelector

Computes a weighted average of model outputs with weights proportional to the metric values (or their inverses).

Parameters
  • metric (Union[str, TSADMetric, ForecastMetric]) – the evaluation metric to use

  • abs_score – whether to take the absolute value of the model outputs. Useful for anomaly detection.

property models_used: List[bool]
Return type

List[bool]

Returns

which models are actually used to make predictions.

property weights: ndarray
Return type

ndarray

class merlion.models.ensemble.combine.CombinerFactory

Bases: object

Factory object for creating combiner objects.

classmethod create(name, **kwargs)
Return type

CombinerBase

merlion.models.ensemble.anomaly module

Ensembles of anomaly detectors.

class merlion.models.ensemble.anomaly.DetectorEnsembleConfig(enable_calibrator=False, max_score: float = 1000, threshold=None, enable_threshold=True, transform: TransformBase = None, models: List[Union[ModelBase, Dict]] = None, combiner: CombinerBase = None, **kwargs)

Bases: DetectorConfig, EnsembleConfig

Config class for an ensemble of anomaly detectors.

Base class of the object used to configure an anomaly detection model.

Parameters
  • enable_calibrator – Whether to enable calibration of the ensemble anomaly score. False by default.

  • 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

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

  • models – A list of models or dicts representing them.

  • combiner – The CombinerBase object to combine the outputs of the models in the ensemble.

  • kwargs – Any additional kwargs for EnsembleConfig or DetectorConfig

property per_model_threshold
Returns

whether to apply the thresholding rules of each individual model, before combining their outputs. Only done if doing model selection.

class merlion.models.ensemble.anomaly.DetectorEnsembleTrainConfig(valid_frac=0.0, per_model_train_configs=None, per_model_post_rule_train_configs=None)

Bases: EnsembleTrainConfig

Config object describing how to train an ensemble of anomaly detectors.

Parameters
  • valid_frac – fraction of training data to use for validation.

  • per_model_train_configs – list of train configs to use for individual models, one per model. None means that you use the default for all models. Specifying None for an individual model means that you use the default for that model.

  • per_model_post_rule_train_configs – list of post-rule train configs to use for individual models, one per model. None means that you use the default for all models. Specifying None for an individual model means that you use the default for that model.

class merlion.models.ensemble.anomaly.DetectorEnsemble(config=None, models=None)

Bases: EnsembleBase, DetectorBase

Class representing an ensemble of multiple anomaly detection models.

Parameters

config (Optional[DetectorEnsembleConfig]) – model configuration

config_class

alias of DetectorEnsembleConfig

property require_even_sampling: bool

Whether the model assumes that training data is sampled at a fixed frequency

Return type

bool

property require_univariate: bool

Whether the model only works with univariate time series.

Return type

bool

property per_model_threshold
Returns

whether to apply the threshold rule of each individual model before aggregating their anomaly scores.

train(train_data, anomaly_labels=None, train_config=None, post_rule_train_config=None)

Trains each anomaly detector in the ensemble unsupervised, and each of their post-rules supervised (if labels are given).

Parameters
Return type

TimeSeries

Returns

A TimeSeries of the ensemble’s anomaly scores on the training data.

merlion.models.ensemble.forecast module

Ensembles of forecasters.

class merlion.models.ensemble.forecast.ForecasterEnsembleConfig(max_forecast_steps=None, verbose=False, target_seq_index: int = None, invert_transform=False, transform: TransformBase = None, models: List[Union[ModelBase, Dict]] = None, combiner: CombinerBase = None, **kwargs)

Bases: ForecasterConfig, EnsembleConfig

Config class for an ensemble of forecasters.

Parameters
  • max_forecast_steps – Max # of steps we would like to forecast for. Required for some models like MSES and LGBMForecaster.

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

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

  • models – A list of models or dicts representing them.

  • combiner – The CombinerBase object to combine the outputs of the models in the ensemble.

  • kwargs – Any additional kwargs for Config

class merlion.models.ensemble.forecast.ForecasterEnsemble(config=None, models=None)

Bases: EnsembleBase, ForecasterBase

Class representing an ensemble of multiple forecasting models.

Parameters
  • config (Optional[ForecasterEnsembleConfig]) – The ensemble’s config

  • models (Optional[List[ForecasterBase]]) – The models in the ensemble. Only provide this argument if you did not specify config.models.

config_class

alias of ForecasterEnsembleConfig

property require_even_sampling: bool

Whether the model assumes that training data is sampled at a fixed frequency

Return type

bool

train_pre_process(train_data)

Applies pre-processing steps common for training most models.

Parameters

train_data (TimeSeries) – the original time series of training data

Return type

TimeSeries

Returns

the training data, after any necessary pre-processing has been applied

resample_time_stamps(time_stamps, time_series_prev=None)