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.spark: APIs to integrate Merlion with PySpark for using distributed computing to run training and inference on multiple time series in parallel.

  • 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, yhat_color=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)

  • yhat_color (Optional[str]) – the color in which to plot the forecast

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, yhat_color=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.