merlion: Time Series Intelligence

merlion is a Python library for time series intelligence. We support the following key features, each associated with its own sub-package:

merlion.models: A library of models unified under a single shared interface, with specializations for anomaly detection and forecasting. More specifically, we have
- merlion.models.anomaly: Anomaly detection models
- merlion.models.anomaly.change_point: Change point detection models
- merlion.models.forecast: Forecasting models
- merlion.models.anomaly.forecast_based: Forecasting models adapted for anomaly detection. Anomaly scores are based on the residual between the predicted and true value at each timestamp.
- merlion.models.ensemble: Ensembles & automated model selection of models for both anomaly detection and forecasting.
- merlion.models.automl: AutoML layers for various models
merlion.transform: Data pre-processing layer which implements many standard data transformations used in time series analysis. Transforms are callable objects, and each model has its own configurable model.transform which it uses to pre-process all input time series for both training and inference.
merlion.post_process: Post-processing rules to apply on the output of a model. Currently, these are specific to anomaly detection, and include
- merlion.post_process.calibrate: Rules to calibrate the anomaly scores returned by a model, to be interpretable as z-scores, i.e. as standard deviations of a standard normal random variable. Each anomaly detection model has a model.calibrator from this module, which can optionally be applied to ensure that the model’s anomaly scores are calibrated.
- merlion.post_process.threshold: Rules to reduce the noisiness of an anomaly detection model’s outputs. Each anomaly detection model has a model.threshold from this module, which can optionally be applied to filter the model’s predicted sequence of anomaly scores.
merlion.evaluate: Evaluation metrics & pipelines to simulate the live deployment of a time series model for any task.
merlion.plot: Automated visualization of model outputs for univariate time series
merlion.utils: Various utilities, including the TimeSeries class, resampling functions, Bayesian conjugate priors, reconciliation for hierarchical time series, and more.

The key classes for input and output are merlion.utils.time_series.TimeSeries and merlion.utils.time_series.UnivariateTimeSeries. Notably, these classes have transparent inter-operability with pandas.DataFrame and pandas.Series, respectively. Check this tutorial for some examples on how to use these classes, or the API docs linked above for a full list of features.

Subpackages

Submodules

merlion.plot module

Module for visualizing model predictions.

merlion.plot.plot_anoms(ax, anomaly_labels): Plots anomalies as pink windows on the matplotlib Axes object ax.

merlion.plot.plot_anoms_plotly(fig, anomaly_labels): Plots anomalies as pink windows on the plotly Figure object fig.

class merlion.plot.Figure(y=None, anom=None, yhat=None, yhat_lb=None, yhat_ub=None, y_prev=None, yhat_prev=None, yhat_prev_lb=None, yhat_prev_ub=None)

Bases: object

Class for visualizing predictions of univariate anomaly detection & forecasting models.

Parameters

y (Optional[UnivariateTimeSeries]) – the true value of the time series
anom (Optional[UnivariateTimeSeries]) – anomaly scores returned by a model
yhat (Optional[UnivariateTimeSeries]) – forecast returned by a model
yhat_lb (Optional[UnivariateTimeSeries]) – lower bound on yhat (if model supports uncertainty estimation)
yhat_ub (Optional[UnivariateTimeSeries]) – upper bound on yhat (if model supports uncertainty estimation)
y_prev (Optional[UnivariateTimeSeries]) – portion of time series preceding y
yhat_prev (Optional[UnivariateTimeSeries]) – model’s forecast of y_prev
yhat_prev_lb (Optional[UnivariateTimeSeries]) – lower bound on yhat_prev (if model supports uncertainty estimation)
yhat_prev_ub (Optional[UnivariateTimeSeries]) – upper bound on yhat_prev (if model supports uncertainty estimation)

property t0

Returns: First time being plotted.

property tf

Returns: Final time being plotted.

property t_split

Returns: Time splitting train from test.

get_y(): Get all y’s (actual values)

get_yhat(): Get all yhat’s (predicted values).

get_yhat_iqr(): Get IQR of predicted values.

plot(title=None, metric_name=None, figsize=(1000, 600), ax=None, label_alias=None)

Plots the figure in matplotlib.

Parameters

title – title of the plot.
metric_name – name of the metric (y axis)
figsize – figure size in pixels
ax – matplotlib axes to add the figure to.
label_alias (Optional[Dict[str, str]]) – dict which maps entities in the figure, specifically y_hat and anom to their label names.

Returns

(fig, ax): matplotlib figure & matplotlib axes

plot_plotly(title=None, metric_name=None, figsize=(1000, 600), label_alias=None)

Plots the figure in plotly.

Parameters

title – title of the plot.
metric_name – name of the metric (y axis)
figsize – figure size in pixels
label_alias (Optional[Dict[str, str]]) – dict which maps entities in the figure, specifically y_hat and anom to their label names.

Returns

plotly figure.

class merlion.plot.MTSFigure(y=None, anom=None, yhat=None, yhat_lb=None, yhat_ub=None, y_prev=None, yhat_prev=None, yhat_prev_lb=None, yhat_prev_ub=None)

Bases: object

property t0

property tf

property t_split

get_y(): Get all y’s (actual values)

get_yhat(): Get all yhat’s (predicted values).

get_yhat_iqr(): Get IQR of predicted values.

plot_plotly(title=None, figsize=None): Plots the figure in plotly. :param title: title of the plot. :param figsize: figure size in pixels :return: plotly figure.