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

train_data (TimeSeries) – a TimeSeries of metric values to train the model.
anomaly_labels (Optional[TimeSeries]) – a TimeSeries indicating which timestamps are anomalous. Optional.
train_config (Optional[DetectorEnsembleTrainConfig]) – DetectorEnsembleTrainConfig for ensemble training.
post_rule_train_config – the post-rule train config to use for the ensemble-level post-rule.

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)