timeseria.models package

Submodules

timeseria.models.anomaly_detectors module

Anomaly detection models.

class timeseria.models.anomaly_detectors.AnomalyDetector

Bases: Model

A generic anomaly detection model.

predict(series, *args, **kwargs)

Disabled. Anomaly detectors can be used only with the apply() method.

evaluate(series, *args, **kwargs)

Disabled. Anomaly detectors cannot be evaluated.

cross_validate(series, *args, **kwargs)

Disabled. Anomaly detectors cannot be evaluated.

static mark_events(timeseries, index_treshold=1.0, min_persistence=2, max_gap=2, replace_index=False, inplace=False)

Mark ensembles of anomalous data points as single anomalous events, with some tolerance.

Parameters

• index_treshold (float) – the anomaly index above which to consider a data point anomalous.

• min_persistence (int) – the minimum persistence of an event, in terms of consecutive data points.

• max_gap (int) – the maximum gap within a signle event of data points below the index_treshold.

• replace_index (bool) – if to replace the existent anomaly index instead of adding a new anomaly_event one.

Returns

the time series with the events marked.

Return type

TimeSeries

apply(series)

Call the model apply logic on a series.

Parameters

series (TimeSeries) – the series on which to apply the model logic.

Returns

the series with the results of applying the model.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

fit(series, verbose=False)

Fit the model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• verbose (str) – if to be verbose when fitting.

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.anomaly_detectors.ModelBasedAnomalyDetector(model=None, models=None, model_class=None, index_window=1, *args, **kwargs)

Bases: AnomalyDetector

An anomaly detection model based on another model. See the model_class property for which model is being used.

In short, for each element of the series where the anomaly detector is applied, the model is asked to make a prediction. The predicted and actual values are then compared, and accordingly to the model error distribution, an anomaly index is computed. The anomaly index is proportional to the likelihood of each element to be anomalous, and ranges form 0 to 1.

More in detail, in the fit phase the model set in the model_class is first fitted and then evaluated using the error metric set in the error_metric argument, which defaults to PE (Percentage Error). All of the error values recorded in the evaluation are then used to build the error distribution (one for each data label of the series), which defaults to a generalized normal distribution. If the p-value is low (below 0.05), a warning is issued.

When the anomaly detector is then applied, the anomaly index is computed based on two boundaries of such error distribution, which are set in the index_bounds argument of the apply() method. Error values below the lower bound will map to an anomaly index of zero (no anomaly suspected at all), between the lower and the upper bound will map to anomaly indexes between zero and one (some degree of anomaly is suspected) and above the upper bound will map to an anomaly index of one (certainly an anomaly).

How to set such boundaries depends on many factors, the most important of which being whether the anomaly detector is used in usupervised or semi-supervised mode. In unsupervised mode, a reasonable choice would be to set the lower bound to the average error, and the upper bound to the maximum error. In semi-supervised mode (which is way more powerful since a notion of normality is implicitly given in the fit data), a good choice would be to set the lower bound to the maximum error (which still belongs to the “normal” behavior) and the upper bound to a very high error (e.g. a billion times the probability of an observation to be adherent with the model). More details about how to set the boundaries are provided in the apply() method documentation.

Parameters

• model (Forecaster, Reconstructor) – the model instance to be used for the anomaly detection.

• models (dict) – the model instances by data label, if using different ones, to be used for the anomaly detection.

• model_class (Forecaster type, Reconstructor type) – the model class to be used for anomaly detection, if not already set.

• index_window (int) – the (rolling) window length to be used when computing the anomaly index. Defaults to 1.

property model_class

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

fit(series, with_context=False, error_metric='PE', error_distribution='gennorm', store_errors=True, symmetric_errors='auto', verbose=False, summary=False, **kwargs)

Fit the anomaly detection model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• with_context (bool) – if to use context for multivariate time series or not. Defaults to False.

• error_metric (str) – the error metric to be used for evaluating the model and to build the error distribution for the anomaly index. Supported values are: E, AE, PE and APE. Defaults to PE.

• error_distribution (str) – if to use a specific error distribution or find it automatically (error_distribution='auto'). Defaults to gennorm, a generalized normal distribution.

• store_errors (float) – if to store the prediction errors (together with actual and predicted values) internally for further analysis. Access them with model.data['prediction_errors'], model.data['actual_values'] and model.data['predicted_values'].

• symmetric_errors (bool) – if to compute symmetric (negative) errors when fitting the error distribution. Defaults to auto, which enables it when using AE and APE error metrics.

• verbose (bool) – if to print the fit progress (one dot = 10% done).

• summary (bool) – if to display a summary on the error distribution fitting or selection.

inspect(plot=True, plot_x_min='auto', plot_x_max='auto', series=False)

Inspect the model by printing a summary and plotting the error distribution and/or the fit series.

Parameters

• plot (bool) – if to plot the error distribution. Defaults to True.

• plot_x_min (float or str) – the minimum value of the x axis. Defaults to ‘auto’.

• plot_x_max (float or str) – the maximum value of the x axis. Defaults to ‘auto’.

• series (bool) – if to plot the fit series.

preprocess(series, inplace=False, verbose=False)

Pre-process a time series for this anomaly detector so that multiple apply() calls are much faster.

Parameters

• series (TimeSeries) – the series to pre-process.

• inplace (bool) – if to pre-process in-place.

• verbose (bool) – if to print the progress (one dot = 10% done).

Returns

the pre-processed series.

Return type

TimeSeries

apply(series, index_bounds=['avg_err', 'max_err'], index_type='log', multivariate_index_strategy='max', data_loss_threshold=1.0, details=False, verbose=False)

Apply the anomaly detection model on a series.

Parameters

• series (TimeSeries) – the series on which to apply the anomaly detector.

• index_bounds (tuple) – the lower an upper bounds, in terms of the prediction error, from which the anomaly index is computed. Below the lower limit no anomaly will be assumed (anomlay_index=0), while errors above the upper will always be considered as anomalous (anomlay_index=1). In the middle, the anomaly index will range between 0 and 1 following the model error distribution. Defaults values are ('avg_err', 'max_err'), which are reasonable values for unsupervised anomaly detection. Other supported values are: x_sigma, where x is a standard deviation multiplier; adherence/x, where x is a divider for the model adherence probability; and any other numerical value in terms of prediction error. Can be also set as a tuple of dictionaries, to set the bounds on a per-data label basis.

• index_type (str, callable) – if to use a logarithmic anomaly index (“log”, the default value) which compresses the index range so that bigger anomalies stand out more than smaller ones, or if to use a linear one (“lin”). Can also support a custom anomaly index as a callable, in which case the form must be f(x, y, x_start, x_end, y_start, y_end) where x is the model error, y its value on the distribution curve, and x_start/x_end together with y_start/y_end the respective x and y range start and end values, based on the range set by the index_bounds argument.

• multivariate_index_strategy (str, callable) – the strategy to use when computing the overall anomaly index for multivariate time series items. Possible choices are “max” to use the maximum one, “avg” for the mean and “min” for the minimum; or a callable taking as input the list of the anomaly indexes for each data label. Defaults to “max”.

• data_loss_threshold (float) – if the data loss is equal or greater than this threshold value, then the anomaly detection is not applied.

• details (bool, list) – if to add details to the time series as the predicted value, the error and the model adherence probability. If set to True, it adds all of them, if instead using a list only selected details can be added: pred for the predicted values, err for the errors, and adh for the model adherence probability.

• verbose (bool) – if to print the apply progress (one dot = 10% done).

Returns

the series with the anomaly detection results.

Return type

TimeSeries

property error_distribution_function

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, *args, **kwargs)

Disabled. Anomaly detectors cannot be evaluated.

evaluate(series, *args, **kwargs)

Disabled. Anomaly detectors cannot be evaluated.

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

static mark_events(timeseries, index_treshold=1.0, min_persistence=2, max_gap=2, replace_index=False, inplace=False)

Mark ensembles of anomalous data points as single anomalous events, with some tolerance.

Parameters

• index_treshold (float) – the anomaly index above which to consider a data point anomalous.

• min_persistence (int) – the minimum persistence of an event, in terms of consecutive data points.

• max_gap (int) – the maximum gap within a signle event of data points below the index_treshold.

• replace_index (bool) – if to replace the existent anomaly index instead of adding a new anomaly_event one.

Returns

the time series with the events marked.

Return type

TimeSeries

predict(series, *args, **kwargs)

Disabled. Anomaly detectors can be used only with the apply() method.

class timeseria.models.anomaly_detectors.PeriodicAverageAnomalyDetector(model=None, models=None, model_class=None, index_window=1, *args, **kwargs)

Bases: ModelBasedAnomalyDetector

An anomaly detection model based on a periodic average forecaster.

model_class

alias of PeriodicAverageForecaster

apply(series, index_bounds=['avg_err', 'max_err'], index_type='log', multivariate_index_strategy='max', data_loss_threshold=1.0, details=False, verbose=False)

Apply the anomaly detection model on a series.

Parameters

• series (TimeSeries) – the series on which to apply the anomaly detector.

• index_bounds (tuple) – the lower an upper bounds, in terms of the prediction error, from which the anomaly index is computed. Below the lower limit no anomaly will be assumed (anomlay_index=0), while errors above the upper will always be considered as anomalous (anomlay_index=1). In the middle, the anomaly index will range between 0 and 1 following the model error distribution. Defaults values are ('avg_err', 'max_err'), which are reasonable values for unsupervised anomaly detection. Other supported values are: x_sigma, where x is a standard deviation multiplier; adherence/x, where x is a divider for the model adherence probability; and any other numerical value in terms of prediction error. Can be also set as a tuple of dictionaries, to set the bounds on a per-data label basis.

• index_type (str, callable) – if to use a logarithmic anomaly index (“log”, the default value) which compresses the index range so that bigger anomalies stand out more than smaller ones, or if to use a linear one (“lin”). Can also support a custom anomaly index as a callable, in which case the form must be f(x, y, x_start, x_end, y_start, y_end) where x is the model error, y its value on the distribution curve, and x_start/x_end together with y_start/y_end the respective x and y range start and end values, based on the range set by the index_bounds argument.

• multivariate_index_strategy (str, callable) – the strategy to use when computing the overall anomaly index for multivariate time series items. Possible choices are “max” to use the maximum one, “avg” for the mean and “min” for the minimum; or a callable taking as input the list of the anomaly indexes for each data label. Defaults to “max”.

• data_loss_threshold (float) – if the data loss is equal or greater than this threshold value, then the anomaly detection is not applied.

• details (bool, list) – if to add details to the time series as the predicted value, the error and the model adherence probability. If set to True, it adds all of them, if instead using a list only selected details can be added: pred for the predicted values, err for the errors, and adh for the model adherence probability.

• verbose (bool) – if to print the apply progress (one dot = 10% done).

Returns

the series with the anomaly detection results.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, *args, **kwargs)

Disabled. Anomaly detectors cannot be evaluated.

property error_distribution_function

evaluate(series, *args, **kwargs)

Disabled. Anomaly detectors cannot be evaluated.

fit(series, with_context=False, error_metric='PE', error_distribution='gennorm', store_errors=True, symmetric_errors='auto', verbose=False, summary=False, **kwargs)

Fit the anomaly detection model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• with_context (bool) – if to use context for multivariate time series or not. Defaults to False.

• error_metric (str) – the error metric to be used for evaluating the model and to build the error distribution for the anomaly index. Supported values are: E, AE, PE and APE. Defaults to PE.

• error_distribution (str) – if to use a specific error distribution or find it automatically (error_distribution='auto'). Defaults to gennorm, a generalized normal distribution.

• store_errors (float) – if to store the prediction errors (together with actual and predicted values) internally for further analysis. Access them with model.data['prediction_errors'], model.data['actual_values'] and model.data['predicted_values'].

• symmetric_errors (bool) – if to compute symmetric (negative) errors when fitting the error distribution. Defaults to auto, which enables it when using AE and APE error metrics.

• verbose (bool) – if to print the fit progress (one dot = 10% done).

• summary (bool) – if to display a summary on the error distribution fitting or selection.

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

inspect(plot=True, plot_x_min='auto', plot_x_max='auto', series=False)

Inspect the model by printing a summary and plotting the error distribution and/or the fit series.

Parameters

• plot (bool) – if to plot the error distribution. Defaults to True.

• plot_x_min (float or str) – the minimum value of the x axis. Defaults to ‘auto’.

• plot_x_max (float or str) – the maximum value of the x axis. Defaults to ‘auto’.

• series (bool) – if to plot the fit series.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

static mark_events(timeseries, index_treshold=1.0, min_persistence=2, max_gap=2, replace_index=False, inplace=False)

Mark ensembles of anomalous data points as single anomalous events, with some tolerance.

Parameters

• index_treshold (float) – the anomaly index above which to consider a data point anomalous.

• min_persistence (int) – the minimum persistence of an event, in terms of consecutive data points.

• max_gap (int) – the maximum gap within a signle event of data points below the index_treshold.

• replace_index (bool) – if to replace the existent anomaly index instead of adding a new anomaly_event one.

Returns

the time series with the events marked.

Return type

TimeSeries

predict(series, *args, **kwargs)

Disabled. Anomaly detectors can be used only with the apply() method.

preprocess(series, inplace=False, verbose=False)

Pre-process a time series for this anomaly detector so that multiple apply() calls are much faster.

Parameters

• series (TimeSeries) – the series to pre-process.

• inplace (bool) – if to pre-process in-place.

• verbose (bool) – if to print the progress (one dot = 10% done).

Returns

the pre-processed series.

Return type

TimeSeries

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.anomaly_detectors.PeriodicAverageReconstructorAnomalyDetector(model=None, models=None, model_class=None, index_window=1, *args, **kwargs)

Bases: ModelBasedAnomalyDetector

An anomaly detection model based on a periodic average reconstructor.

model_class

alias of PeriodicAverageReconstructor

apply(series, index_bounds=['avg_err', 'max_err'], index_type='log', multivariate_index_strategy='max', data_loss_threshold=1.0, details=False, verbose=False)

Apply the anomaly detection model on a series.

Parameters

• series (TimeSeries) – the series on which to apply the anomaly detector.

• index_bounds (tuple) – the lower an upper bounds, in terms of the prediction error, from which the anomaly index is computed. Below the lower limit no anomaly will be assumed (anomlay_index=0), while errors above the upper will always be considered as anomalous (anomlay_index=1). In the middle, the anomaly index will range between 0 and 1 following the model error distribution. Defaults values are ('avg_err', 'max_err'), which are reasonable values for unsupervised anomaly detection. Other supported values are: x_sigma, where x is a standard deviation multiplier; adherence/x, where x is a divider for the model adherence probability; and any other numerical value in terms of prediction error. Can be also set as a tuple of dictionaries, to set the bounds on a per-data label basis.

• index_type (str, callable) – if to use a logarithmic anomaly index (“log”, the default value) which compresses the index range so that bigger anomalies stand out more than smaller ones, or if to use a linear one (“lin”). Can also support a custom anomaly index as a callable, in which case the form must be f(x, y, x_start, x_end, y_start, y_end) where x is the model error, y its value on the distribution curve, and x_start/x_end together with y_start/y_end the respective x and y range start and end values, based on the range set by the index_bounds argument.

• multivariate_index_strategy (str, callable) – the strategy to use when computing the overall anomaly index for multivariate time series items. Possible choices are “max” to use the maximum one, “avg” for the mean and “min” for the minimum; or a callable taking as input the list of the anomaly indexes for each data label. Defaults to “max”.

• data_loss_threshold (float) – if the data loss is equal or greater than this threshold value, then the anomaly detection is not applied.

• details (bool, list) – if to add details to the time series as the predicted value, the error and the model adherence probability. If set to True, it adds all of them, if instead using a list only selected details can be added: pred for the predicted values, err for the errors, and adh for the model adherence probability.

• verbose (bool) – if to print the apply progress (one dot = 10% done).

Returns

the series with the anomaly detection results.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, *args, **kwargs)

Disabled. Anomaly detectors cannot be evaluated.

property error_distribution_function

evaluate(series, *args, **kwargs)

Disabled. Anomaly detectors cannot be evaluated.

fit(series, with_context=False, error_metric='PE', error_distribution='gennorm', store_errors=True, symmetric_errors='auto', verbose=False, summary=False, **kwargs)

Fit the anomaly detection model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• with_context (bool) – if to use context for multivariate time series or not. Defaults to False.

• error_metric (str) – the error metric to be used for evaluating the model and to build the error distribution for the anomaly index. Supported values are: E, AE, PE and APE. Defaults to PE.

• error_distribution (str) – if to use a specific error distribution or find it automatically (error_distribution='auto'). Defaults to gennorm, a generalized normal distribution.

• store_errors (float) – if to store the prediction errors (together with actual and predicted values) internally for further analysis. Access them with model.data['prediction_errors'], model.data['actual_values'] and model.data['predicted_values'].

• symmetric_errors (bool) – if to compute symmetric (negative) errors when fitting the error distribution. Defaults to auto, which enables it when using AE and APE error metrics.

• verbose (bool) – if to print the fit progress (one dot = 10% done).

• summary (bool) – if to display a summary on the error distribution fitting or selection.

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

inspect(plot=True, plot_x_min='auto', plot_x_max='auto', series=False)

Inspect the model by printing a summary and plotting the error distribution and/or the fit series.

Parameters

• plot (bool) – if to plot the error distribution. Defaults to True.

• plot_x_min (float or str) – the minimum value of the x axis. Defaults to ‘auto’.

• plot_x_max (float or str) – the maximum value of the x axis. Defaults to ‘auto’.

• series (bool) – if to plot the fit series.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

static mark_events(timeseries, index_treshold=1.0, min_persistence=2, max_gap=2, replace_index=False, inplace=False)

Mark ensembles of anomalous data points as single anomalous events, with some tolerance.

Parameters

• index_treshold (float) – the anomaly index above which to consider a data point anomalous.

• min_persistence (int) – the minimum persistence of an event, in terms of consecutive data points.

• max_gap (int) – the maximum gap within a signle event of data points below the index_treshold.

• replace_index (bool) – if to replace the existent anomaly index instead of adding a new anomaly_event one.

Returns

the time series with the events marked.

Return type

TimeSeries

predict(series, *args, **kwargs)

Disabled. Anomaly detectors can be used only with the apply() method.

preprocess(series, inplace=False, verbose=False)

Pre-process a time series for this anomaly detector so that multiple apply() calls are much faster.

Parameters

• series (TimeSeries) – the series to pre-process.

• inplace (bool) – if to pre-process in-place.

• verbose (bool) – if to print the progress (one dot = 10% done).

Returns

the pre-processed series.

Return type

TimeSeries

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.anomaly_detectors.LSTMAnomalyDetector(model=None, models=None, model_class=None, index_window=1, *args, **kwargs)

Bases: ModelBasedAnomalyDetector

An anomaly detection model based on a LSTM neural network forecaster.

model_class

alias of LSTMForecaster

apply(series, index_bounds=['avg_err', 'max_err'], index_type='log', multivariate_index_strategy='max', data_loss_threshold=1.0, details=False, verbose=False)

Apply the anomaly detection model on a series.

Parameters

• series (TimeSeries) – the series on which to apply the anomaly detector.

• index_bounds (tuple) – the lower an upper bounds, in terms of the prediction error, from which the anomaly index is computed. Below the lower limit no anomaly will be assumed (anomlay_index=0), while errors above the upper will always be considered as anomalous (anomlay_index=1). In the middle, the anomaly index will range between 0 and 1 following the model error distribution. Defaults values are ('avg_err', 'max_err'), which are reasonable values for unsupervised anomaly detection. Other supported values are: x_sigma, where x is a standard deviation multiplier; adherence/x, where x is a divider for the model adherence probability; and any other numerical value in terms of prediction error. Can be also set as a tuple of dictionaries, to set the bounds on a per-data label basis.

• index_type (str, callable) – if to use a logarithmic anomaly index (“log”, the default value) which compresses the index range so that bigger anomalies stand out more than smaller ones, or if to use a linear one (“lin”). Can also support a custom anomaly index as a callable, in which case the form must be f(x, y, x_start, x_end, y_start, y_end) where x is the model error, y its value on the distribution curve, and x_start/x_end together with y_start/y_end the respective x and y range start and end values, based on the range set by the index_bounds argument.

• multivariate_index_strategy (str, callable) – the strategy to use when computing the overall anomaly index for multivariate time series items. Possible choices are “max” to use the maximum one, “avg” for the mean and “min” for the minimum; or a callable taking as input the list of the anomaly indexes for each data label. Defaults to “max”.

• data_loss_threshold (float) – if the data loss is equal or greater than this threshold value, then the anomaly detection is not applied.

• details (bool, list) – if to add details to the time series as the predicted value, the error and the model adherence probability. If set to True, it adds all of them, if instead using a list only selected details can be added: pred for the predicted values, err for the errors, and adh for the model adherence probability.

• verbose (bool) – if to print the apply progress (one dot = 10% done).

Returns

the series with the anomaly detection results.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, *args, **kwargs)

Disabled. Anomaly detectors cannot be evaluated.

property error_distribution_function

evaluate(series, *args, **kwargs)

Disabled. Anomaly detectors cannot be evaluated.

fit(series, with_context=False, error_metric='PE', error_distribution='gennorm', store_errors=True, symmetric_errors='auto', verbose=False, summary=False, **kwargs)

Fit the anomaly detection model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• with_context (bool) – if to use context for multivariate time series or not. Defaults to False.

• error_metric (str) – the error metric to be used for evaluating the model and to build the error distribution for the anomaly index. Supported values are: E, AE, PE and APE. Defaults to PE.

• error_distribution (str) – if to use a specific error distribution or find it automatically (error_distribution='auto'). Defaults to gennorm, a generalized normal distribution.

• store_errors (float) – if to store the prediction errors (together with actual and predicted values) internally for further analysis. Access them with model.data['prediction_errors'], model.data['actual_values'] and model.data['predicted_values'].

• symmetric_errors (bool) – if to compute symmetric (negative) errors when fitting the error distribution. Defaults to auto, which enables it when using AE and APE error metrics.

• verbose (bool) – if to print the fit progress (one dot = 10% done).

• summary (bool) – if to display a summary on the error distribution fitting or selection.

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

inspect(plot=True, plot_x_min='auto', plot_x_max='auto', series=False)

Inspect the model by printing a summary and plotting the error distribution and/or the fit series.

Parameters

• plot (bool) – if to plot the error distribution. Defaults to True.

• plot_x_min (float or str) – the minimum value of the x axis. Defaults to ‘auto’.

• plot_x_max (float or str) – the maximum value of the x axis. Defaults to ‘auto’.

• series (bool) – if to plot the fit series.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

static mark_events(timeseries, index_treshold=1.0, min_persistence=2, max_gap=2, replace_index=False, inplace=False)

Mark ensembles of anomalous data points as single anomalous events, with some tolerance.

Parameters

• index_treshold (float) – the anomaly index above which to consider a data point anomalous.

• min_persistence (int) – the minimum persistence of an event, in terms of consecutive data points.

• max_gap (int) – the maximum gap within a signle event of data points below the index_treshold.

• replace_index (bool) – if to replace the existent anomaly index instead of adding a new anomaly_event one.

Returns

the time series with the events marked.

Return type

TimeSeries

predict(series, *args, **kwargs)

Disabled. Anomaly detectors can be used only with the apply() method.

preprocess(series, inplace=False, verbose=False)

Pre-process a time series for this anomaly detector so that multiple apply() calls are much faster.

Parameters

• series (TimeSeries) – the series to pre-process.

• inplace (bool) – if to pre-process in-place.

• verbose (bool) – if to print the progress (one dot = 10% done).

Returns

the pre-processed series.

Return type

TimeSeries

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.anomaly_detectors.LinearRegressionAnomalyDetector(model=None, models=None, model_class=None, index_window=1, *args, **kwargs)

Bases: ModelBasedAnomalyDetector

An anomaly detection model based on a linear regression forecaster.

model_class

alias of LinearRegressionForecaster

apply(series, index_bounds=['avg_err', 'max_err'], index_type='log', multivariate_index_strategy='max', data_loss_threshold=1.0, details=False, verbose=False)

Apply the anomaly detection model on a series.

Parameters

• series (TimeSeries) – the series on which to apply the anomaly detector.

• index_bounds (tuple) – the lower an upper bounds, in terms of the prediction error, from which the anomaly index is computed. Below the lower limit no anomaly will be assumed (anomlay_index=0), while errors above the upper will always be considered as anomalous (anomlay_index=1). In the middle, the anomaly index will range between 0 and 1 following the model error distribution. Defaults values are ('avg_err', 'max_err'), which are reasonable values for unsupervised anomaly detection. Other supported values are: x_sigma, where x is a standard deviation multiplier; adherence/x, where x is a divider for the model adherence probability; and any other numerical value in terms of prediction error. Can be also set as a tuple of dictionaries, to set the bounds on a per-data label basis.

• index_type (str, callable) – if to use a logarithmic anomaly index (“log”, the default value) which compresses the index range so that bigger anomalies stand out more than smaller ones, or if to use a linear one (“lin”). Can also support a custom anomaly index as a callable, in which case the form must be f(x, y, x_start, x_end, y_start, y_end) where x is the model error, y its value on the distribution curve, and x_start/x_end together with y_start/y_end the respective x and y range start and end values, based on the range set by the index_bounds argument.

• multivariate_index_strategy (str, callable) – the strategy to use when computing the overall anomaly index for multivariate time series items. Possible choices are “max” to use the maximum one, “avg” for the mean and “min” for the minimum; or a callable taking as input the list of the anomaly indexes for each data label. Defaults to “max”.

• data_loss_threshold (float) – if the data loss is equal or greater than this threshold value, then the anomaly detection is not applied.

• details (bool, list) – if to add details to the time series as the predicted value, the error and the model adherence probability. If set to True, it adds all of them, if instead using a list only selected details can be added: pred for the predicted values, err for the errors, and adh for the model adherence probability.

• verbose (bool) – if to print the apply progress (one dot = 10% done).

Returns

the series with the anomaly detection results.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, *args, **kwargs)

Disabled. Anomaly detectors cannot be evaluated.

property error_distribution_function

evaluate(series, *args, **kwargs)

Disabled. Anomaly detectors cannot be evaluated.

fit(series, with_context=False, error_metric='PE', error_distribution='gennorm', store_errors=True, symmetric_errors='auto', verbose=False, summary=False, **kwargs)

Fit the anomaly detection model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• with_context (bool) – if to use context for multivariate time series or not. Defaults to False.

• error_metric (str) – the error metric to be used for evaluating the model and to build the error distribution for the anomaly index. Supported values are: E, AE, PE and APE. Defaults to PE.

• error_distribution (str) – if to use a specific error distribution or find it automatically (error_distribution='auto'). Defaults to gennorm, a generalized normal distribution.

• store_errors (float) – if to store the prediction errors (together with actual and predicted values) internally for further analysis. Access them with model.data['prediction_errors'], model.data['actual_values'] and model.data['predicted_values'].

• symmetric_errors (bool) – if to compute symmetric (negative) errors when fitting the error distribution. Defaults to auto, which enables it when using AE and APE error metrics.

• verbose (bool) – if to print the fit progress (one dot = 10% done).

• summary (bool) – if to display a summary on the error distribution fitting or selection.

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

inspect(plot=True, plot_x_min='auto', plot_x_max='auto', series=False)

Inspect the model by printing a summary and plotting the error distribution and/or the fit series.

Parameters

• plot (bool) – if to plot the error distribution. Defaults to True.

• plot_x_min (float or str) – the minimum value of the x axis. Defaults to ‘auto’.

• plot_x_max (float or str) – the maximum value of the x axis. Defaults to ‘auto’.

• series (bool) – if to plot the fit series.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

static mark_events(timeseries, index_treshold=1.0, min_persistence=2, max_gap=2, replace_index=False, inplace=False)

Mark ensembles of anomalous data points as single anomalous events, with some tolerance.

Parameters

• index_treshold (float) – the anomaly index above which to consider a data point anomalous.

• min_persistence (int) – the minimum persistence of an event, in terms of consecutive data points.

• max_gap (int) – the maximum gap within a signle event of data points below the index_treshold.

• replace_index (bool) – if to replace the existent anomaly index instead of adding a new anomaly_event one.

Returns

the time series with the events marked.

Return type

TimeSeries

predict(series, *args, **kwargs)

Disabled. Anomaly detectors can be used only with the apply() method.

preprocess(series, inplace=False, verbose=False)

Pre-process a time series for this anomaly detector so that multiple apply() calls are much faster.

Parameters

• series (TimeSeries) – the series to pre-process.

• inplace (bool) – if to pre-process in-place.

• verbose (bool) – if to print the progress (one dot = 10% done).

Returns

the pre-processed series.

Return type

TimeSeries

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

timeseria.models.base module

Base model classes.

exception timeseria.models.base.TooMuchDataLoss

Bases: Exception

add_note()

Exception.add_note(note) – add a note to the exception

class timeseria.models.base.Model

Bases: object

A generic model. This can be either a stateless model, where all the information is coded and there are no parameters, or a stateful (parametric) model, where there are a number of parameters which can be both set manually or learnt (fitted) from the data.

All models expose a predict(), apply() and evaluate() methods, while parametric models also provide a save() method to store the parameters of the model, and an optional fit() method if the parameters are to be learnt form data. In this case also a cross_validate() method is available.

Series resolution and data labels consistency are enforced between all methods and save/load operations.

property id

A unique identifier for the model. Only for parametric models.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

fit(series, verbose=False)

Fit the model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• verbose (str) – if to be verbose when fitting.

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

predict(series)

Call the model predict logic on a series.

Parameters

series (TimeSeries) – the series on which to apply the predict logic.

Returns

the predicted data.

Return type

dict

apply(series)

Call the model apply logic on a series.

Parameters

series (TimeSeries) – the series on which to apply the model logic.

Returns

the series with the results of applying the model.

Return type

TimeSeries

evaluate(series)

Call the model evaluate logic on a series.

Parameters

series (TimeSeries) – the series on which to evaluate the model.

Returns

the evaluation results.

Return type

dict

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

timeseria.models.calibrators module

Calibration models.

class timeseria.models.calibrators.Calibrator

Bases: Model

A generic calibration model.

fit(series, model, error_metric, *args, **kwargs)

Fit the calibrator model on the given series

adjust(prediction, series=None)

Adjust a probabilistic prediction interval or distribution.

Parameters

• prediction (dict,list) – the predicted data, according to the predict() method of the calibrated model.

• series (TimeSeries) – the series from which the prediction originates, as (optional) context.

predict(series, *args, **kwargs)

Disabled. Calibrators can be used only with the wrap() or adjust() methods.

apply(series, *args, **kwargs)

Disabled. Calibrators can be used only with the adjust() method.

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series)

Call the model evaluate logic on a series.

Parameters

series (TimeSeries) – the series on which to evaluate the model.

Returns

the evaluation results.

Return type

dict

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.calibrators.ErrorQuantileCalibrator

Bases: Calibrator

A calibration model based on the error quantiles.

fit(series, model, verbose, error_metric='AE', alpha=0.1)

Fit the calibrator, computing the global error distribution.

Parameters

• series (TimeSeries) – the series to use for calibration.

• model (Model) – the model being calibrated.

• error_metric (str) – the error metric to calibrate for. Defaults to AE.

• alpha (float) – Significance level for prediction intervals. Defaults to 0.1

adjust(prediction, series, _as_pfloat='auto')

Adjust a probabilistic prediction interval or distribution.

Parameters

• prediction (dict,list) – the predicted data, according to the predict() method of the calibrated model.

• series (TimeSeries) – the series from which the prediction originates, as (optional) context.

apply(series, *args, **kwargs)

Disabled. Calibrators can be used only with the adjust() method.

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series)

Call the model evaluate logic on a series.

Parameters

series (TimeSeries) – the series on which to evaluate the model.

Returns

the evaluation results.

Return type

dict

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

predict(series, *args, **kwargs)

Disabled. Calibrators can be used only with the wrap() or adjust() methods.

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.calibrators.ErrorDistributionCalibrator

Bases: Calibrator

A calibration model based on the error distribution.

fit(series, model, verbose, error_metric='AE', error_distribution='norm')

Fit the calibrator, computing the global error distribution.

Parameters

• series (TimeSeries) – the series to use for calibration.

• model (Model) – the model being calibrated.

• error_metric (str) – the error metric to calibrate for.

• error_distribution (string) – the distribution used to model the error. Default to ‘norm’

adjust(prediction, series)

Adjust a probabilistic prediction interval or distribution.

Parameters

• prediction (dict,list) – the predicted data, according to the predict() method of the calibrated model.

• series (TimeSeries) – the series from which the prediction originates, as (optional) context.

apply(series, *args, **kwargs)

Disabled. Calibrators can be used only with the adjust() method.

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series)

Call the model evaluate logic on a series.

Parameters

series (TimeSeries) – the series on which to evaluate the model.

Returns

the evaluation results.

Return type

dict

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

predict(series, *args, **kwargs)

Disabled. Calibrators can be used only with the wrap() or adjust() methods.

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.calibrators.ErrorPredictionCalibrator

Bases: Calibrator

A calibration model based on the error prediction.

This calibrator makes use of an error predictor which takes as input the same input of the model being calibrated (i.e. the forecasting window), thus allowing to adapt the uncertainty estimates to the local context.

Uncertainty is then expressed with a Normal distribution computed by reversing the expected absolute error formula with respect to the standard deviation.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

fit(series, model, verbose, error_metric='AE', error_predictor='default', **kwargs)

Fit the calibrator using the given error predictor.

All the parameters starting with the error_predictor_ prefix are forwarded to the error predictor initialization (without the prefix), and all the parameters starting with the error_predictor_fit_ prefix are forwarded to the error predictor fit() method (without the prefix).

Parameters

• series (TimeSeries) – the series to use for calibration.

• model (Model) – the model being calibrated.

• error_metric (str) – the error metric to calibrate for. Defaults to AE. Supported values are: SE, AE, APE, ALE, E, PE and LE.

• error_predictor – (str, Model): the model used to predict the error. Besides specific models, any Forecaster will work. The default corresponds to a LSTMForecaster.

• **kwargs – extra arguments to be forwarded to the error predictor as introduced above.

adjust(prediction, series)

Adjust a probabilistic prediction interval or distribution.

Parameters

• prediction (dict,list) – the predicted data, according to the predict() method of the calibrated model.

• series (TimeSeries) – the series from which the prediction originates, as (optional) context.

apply(series, *args, **kwargs)

Disabled. Calibrators can be used only with the adjust() method.

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series)

Call the model evaluate logic on a series.

Parameters

series (TimeSeries) – the series on which to evaluate the model.

Returns

the evaluation results.

Return type

dict

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

predict(series, *args, **kwargs)

Disabled. Calibrators can be used only with the wrap() or adjust() methods.

timeseria.models.forecasters module

Forecasting models.

class timeseria.models.forecasters.Forecaster

Bases: Model

A generic forecasting model. Besides the predict() and apply() methods, it also has a forecast() method which, in case of nested data structures (i.e. DataPoint or DataSlot) allows to get the full forecasted points or slots instead of just the raw, inner data values returned by the predict().

Series resolution and data labels consistency are enforced between all methods and save/load operations.

window = None

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

predict(series, steps)

Call the model predict logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the predict logic.

• steps – (int): the number of steps to predict. Defaults to 1.

Returns

the predicted data.

Return type

dict or list

forecast(series, steps=1, context_data=None, **kwargs)

Forecast n steps-ahead data points or slots.

Parameters

• series (TimeSeries) – the series from which to perform the forecast.

• steps – (int): the number of steps to forecast. Defaults to 1.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the forecasted data.

Return type

DataTimePoint or DataTimeSlot or list

apply(series, steps=1, inplace=False, context_data=None, **kwargs)

Apply the forecast on the given series for n steps-ahead.

Parameters

• series (TimeSeries) – the series on which to apply the model logic.

• steps – (int): the number of steps to forecast. Defaults to 1.

• inplace (bool) – if to apply the forecast in-place on the series. Default to False.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the series with the results of applying the model.

Return type

TimeSeries

evaluate(series, steps=1, error_metrics=['RMSE', 'MAE'], return_evaluation_series=False, plot_evaluation_series=False, evaluation_series_error_metrics='auto', plot_error_distribution=False, error_distribution_metrics='auto', confidence_metrics=['EC'], confidence_interval=[0.05, 0.95], verbose=False)

Evaluate the model on a series.

Parameters

• steps (int) – how many steps-ahead to evaluate the model on.

• error_metrics (list) – the (aggregated) error metrics to use for the evaluation. Defaults to RMSE and MAE. Supported values (as list) are: MSE, RMSE, MAE, MaxAE, MAPE, MaxAPE, MALE and MaxALE.

• return_evaluation_series (bool) – if to return the series used for the evaluation, with the the predicted values and the punctual errors.

• plot_evaluation_series (bool) – if to plot the series used for the evaluation, with the the predicted values and the punctual errors.

• evaluation_series_error_metrics (list) – the (punctual) error metrics to be included in the evaluation series. Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE, or None.

• plot_error_distribution (bool) – if to plot the error distribution.

• error_distribution_metrics (list) – the (punctual) error metrics to be used for generating the error distribution(s). Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE.

• confidence_metrics (list) – the probabilistic error metrics to use if the model supports probabilistic predictions. Defaults to CE. Supported values (as list) are: EC, ECE, ECPE; respectively for Empirical Coverage, Empirical Coverage Error, and Empirical Coverage Percentage Error.

• confidence_interval (list) – The confidence interval to use for the evaluation. Default to [0.05, 0.95].

• verbose (bool) – if to print the evaluation progress (one dot = 10% done).

Returns

the evaluation results.

Return type

dict

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

fit(series, verbose=False)

Fit the model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• verbose (str) – if to be verbose when fitting.

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

class timeseria.models.forecasters.PeriodicAverageForecaster(window='auto')

Bases: Forecaster

A forecasting model based on periodic averages, offsetted with respect to a given window.

Parameters

• path (str) – a path from which to load a saved model. Will override all other init settings.

• window (int) – the window length. If set to auto, then it will be automatically handled based on the time series periodicity.

property window

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

fit(series, periodicity='auto', dst_affected=False, data_loss_limit=1.0, probabilistic=False, verbose=False)

Fit the model on a series.

Parameters

• periodicity (int) – the periodicty of the series. If set to auto then it will be automatically detected using a FFT.

• dst_affected (bool) – if the model should take into account DST effects.

• data_loss_limit (float) – discard from the fit elements with a data loss greater than or equal to this limit.

• probabilistic (bool) – if to make the forecaster probabilistic.

• verbose (bool) – not supported, has no effect.

predict(series, steps=1)

Predict n steps ahead from the given series.

Parameters

• series (TimeSeries) – the series on which to apply the predict logic.

• steps – (int): the number of steps to forecast. Defaults to 1.

Returns

the predicted data.

Return type

dict or list

apply(series, steps=1, inplace=False, context_data=None, **kwargs)

Apply the forecast on the given series for n steps-ahead.

Parameters

• series (TimeSeries) – the series on which to apply the model logic.

• steps – (int): the number of steps to forecast. Defaults to 1.

• inplace (bool) – if to apply the forecast in-place on the series. Default to False.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the series with the results of applying the model.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series, steps=1, error_metrics=['RMSE', 'MAE'], return_evaluation_series=False, plot_evaluation_series=False, evaluation_series_error_metrics='auto', plot_error_distribution=False, error_distribution_metrics='auto', confidence_metrics=['EC'], confidence_interval=[0.05, 0.95], verbose=False)

Evaluate the model on a series.

Parameters

• steps (int) – how many steps-ahead to evaluate the model on.

• error_metrics (list) – the (aggregated) error metrics to use for the evaluation. Defaults to RMSE and MAE. Supported values (as list) are: MSE, RMSE, MAE, MaxAE, MAPE, MaxAPE, MALE and MaxALE.

• return_evaluation_series (bool) – if to return the series used for the evaluation, with the the predicted values and the punctual errors.

• plot_evaluation_series (bool) – if to plot the series used for the evaluation, with the the predicted values and the punctual errors.

• evaluation_series_error_metrics (list) – the (punctual) error metrics to be included in the evaluation series. Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE, or None.

• plot_error_distribution (bool) – if to plot the error distribution.

• error_distribution_metrics (list) – the (punctual) error metrics to be used for generating the error distribution(s). Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE.

• confidence_metrics (list) – the probabilistic error metrics to use if the model supports probabilistic predictions. Defaults to CE. Supported values (as list) are: EC, ECE, ECPE; respectively for Empirical Coverage, Empirical Coverage Error, and Empirical Coverage Percentage Error.

• confidence_interval (list) – The confidence interval to use for the evaluation. Default to [0.05, 0.95].

• verbose (bool) – if to print the evaluation progress (one dot = 10% done).

Returns

the evaluation results.

Return type

dict

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

forecast(series, steps=1, context_data=None, **kwargs)

Forecast n steps-ahead data points or slots.

Parameters

• series (TimeSeries) – the series from which to perform the forecast.

• steps – (int): the number of steps to forecast. Defaults to 1.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the forecasted data.

Return type

DataTimePoint or DataTimeSlot or list

property id

A unique identifier for the model. Only for parametric models.

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.forecasters.ProphetForecaster

Bases: Forecaster, _ProphetModel

A forecasting model based on Prophet. Prophet (from Facebook) implements a procedure for forecasting time series data based on an additive model where non-linear trends are fit with yearly, weekly, and daily seasonality, plus holiday effects.

window = None

fit(series, verbose=False)

Fit the model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• verbose (str) – if to be verbose when fitting.

predict(data, steps=1)

Call the model predict logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the predict logic.

• steps – (int): the number of steps to predict. Defaults to 1.

Returns

the predicted data.

Return type

dict or list

apply(series, steps=1, inplace=False, context_data=None, **kwargs)

Apply the forecast on the given series for n steps-ahead.

Parameters

• series (TimeSeries) – the series on which to apply the model logic.

• steps – (int): the number of steps to forecast. Defaults to 1.

• inplace (bool) – if to apply the forecast in-place on the series. Default to False.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the series with the results of applying the model.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series, steps=1, error_metrics=['RMSE', 'MAE'], return_evaluation_series=False, plot_evaluation_series=False, evaluation_series_error_metrics='auto', plot_error_distribution=False, error_distribution_metrics='auto', confidence_metrics=['EC'], confidence_interval=[0.05, 0.95], verbose=False)

Evaluate the model on a series.

Parameters

• steps (int) – how many steps-ahead to evaluate the model on.

• error_metrics (list) – the (aggregated) error metrics to use for the evaluation. Defaults to RMSE and MAE. Supported values (as list) are: MSE, RMSE, MAE, MaxAE, MAPE, MaxAPE, MALE and MaxALE.

• return_evaluation_series (bool) – if to return the series used for the evaluation, with the the predicted values and the punctual errors.

• plot_evaluation_series (bool) – if to plot the series used for the evaluation, with the the predicted values and the punctual errors.

• evaluation_series_error_metrics (list) – the (punctual) error metrics to be included in the evaluation series. Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE, or None.

• plot_error_distribution (bool) – if to plot the error distribution.

• error_distribution_metrics (list) – the (punctual) error metrics to be used for generating the error distribution(s). Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE.

• confidence_metrics (list) – the probabilistic error metrics to use if the model supports probabilistic predictions. Defaults to CE. Supported values (as list) are: EC, ECE, ECPE; respectively for Empirical Coverage, Empirical Coverage Error, and Empirical Coverage Percentage Error.

• confidence_interval (list) – The confidence interval to use for the evaluation. Default to [0.05, 0.95].

• verbose (bool) – if to print the evaluation progress (one dot = 10% done).

Returns

the evaluation results.

Return type

dict

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

forecast(series, steps=1, context_data=None, **kwargs)

Forecast n steps-ahead data points or slots.

Parameters

• series (TimeSeries) – the series from which to perform the forecast.

• steps – (int): the number of steps to forecast. Defaults to 1.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the forecasted data.

Return type

DataTimePoint or DataTimeSlot or list

property id

A unique identifier for the model. Only for parametric models.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.forecasters.ARIMAForecaster(p=1, d=1, q=0)

Bases: Forecaster, _ARIMAModel

A forecasting model based on ARIMA. AutoRegressive Integrated Moving Average models are a generalization of an AutoRegessive Moving Average (ARMA) model, which provide a description of a (weakly) stationary stochastic process in terms of two polynomials, one for the autoregression (AR) and the second for the moving average (MA). The “I” indicates that the data values have been replaced with the difference between their values and the previous values.

Parameters

• p (int) – the order of the AR term.

• d (int) – the number of differencing required to make the time series stationary.

• q (int) – the order of the MA term.

window = 0

fit(series, verbose=False)

Fit the model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• verbose (str) – if to be verbose when fitting.

predict(series, steps=1)

Call the model predict logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the predict logic.

• steps – (int): the number of steps to predict. Defaults to 1.

Returns

the predicted data.

Return type

dict or list

apply(series, steps=1, inplace=False, context_data=None, **kwargs)

Apply the forecast on the given series for n steps-ahead.

Parameters

• series (TimeSeries) – the series on which to apply the model logic.

• steps – (int): the number of steps to forecast. Defaults to 1.

• inplace (bool) – if to apply the forecast in-place on the series. Default to False.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the series with the results of applying the model.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series, steps=1, error_metrics=['RMSE', 'MAE'], return_evaluation_series=False, plot_evaluation_series=False, evaluation_series_error_metrics='auto', plot_error_distribution=False, error_distribution_metrics='auto', confidence_metrics=['EC'], confidence_interval=[0.05, 0.95], verbose=False)

Evaluate the model on a series.

Parameters

• steps (int) – how many steps-ahead to evaluate the model on.

• error_metrics (list) – the (aggregated) error metrics to use for the evaluation. Defaults to RMSE and MAE. Supported values (as list) are: MSE, RMSE, MAE, MaxAE, MAPE, MaxAPE, MALE and MaxALE.

• return_evaluation_series (bool) – if to return the series used for the evaluation, with the the predicted values and the punctual errors.

• plot_evaluation_series (bool) – if to plot the series used for the evaluation, with the the predicted values and the punctual errors.

• evaluation_series_error_metrics (list) – the (punctual) error metrics to be included in the evaluation series. Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE, or None.

• plot_error_distribution (bool) – if to plot the error distribution.

• error_distribution_metrics (list) – the (punctual) error metrics to be used for generating the error distribution(s). Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE.

• confidence_metrics (list) – the probabilistic error metrics to use if the model supports probabilistic predictions. Defaults to CE. Supported values (as list) are: EC, ECE, ECPE; respectively for Empirical Coverage, Empirical Coverage Error, and Empirical Coverage Percentage Error.

• confidence_interval (list) – The confidence interval to use for the evaluation. Default to [0.05, 0.95].

• verbose (bool) – if to print the evaluation progress (one dot = 10% done).

Returns

the evaluation results.

Return type

dict

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

forecast(series, steps=1, context_data=None, **kwargs)

Forecast n steps-ahead data points or slots.

Parameters

• series (TimeSeries) – the series from which to perform the forecast.

• steps – (int): the number of steps to forecast. Defaults to 1.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the forecasted data.

Return type

DataTimePoint or DataTimeSlot or list

property id

A unique identifier for the model. Only for parametric models.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.forecasters.AARIMAForecaster

Bases: Forecaster, _ARIMAModel

A forecasting model based on Auto-ARIMA. Auto-ARIMA models set automatically the best values for the p, d and q parameters, trying different values and checking which ones perform better.

window = 0

fit(series, verbose=False, **kwargs)

Fit the model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• verbose (str) – if to be verbose when fitting.

predict(series, steps=1)

Call the model predict logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the predict logic.

• steps – (int): the number of steps to predict. Defaults to 1.

Returns

the predicted data.

Return type

dict or list

apply(series, steps=1, inplace=False, context_data=None, **kwargs)

Apply the forecast on the given series for n steps-ahead.

Parameters

• series (TimeSeries) – the series on which to apply the model logic.

• steps – (int): the number of steps to forecast. Defaults to 1.

• inplace (bool) – if to apply the forecast in-place on the series. Default to False.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the series with the results of applying the model.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series, steps=1, error_metrics=['RMSE', 'MAE'], return_evaluation_series=False, plot_evaluation_series=False, evaluation_series_error_metrics='auto', plot_error_distribution=False, error_distribution_metrics='auto', confidence_metrics=['EC'], confidence_interval=[0.05, 0.95], verbose=False)

Evaluate the model on a series.

Parameters

• steps (int) – how many steps-ahead to evaluate the model on.

• error_metrics (list) – the (aggregated) error metrics to use for the evaluation. Defaults to RMSE and MAE. Supported values (as list) are: MSE, RMSE, MAE, MaxAE, MAPE, MaxAPE, MALE and MaxALE.

• return_evaluation_series (bool) – if to return the series used for the evaluation, with the the predicted values and the punctual errors.

• plot_evaluation_series (bool) – if to plot the series used for the evaluation, with the the predicted values and the punctual errors.

• evaluation_series_error_metrics (list) – the (punctual) error metrics to be included in the evaluation series. Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE, or None.

• plot_error_distribution (bool) – if to plot the error distribution.

• error_distribution_metrics (list) – the (punctual) error metrics to be used for generating the error distribution(s). Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE.

• confidence_metrics (list) – the probabilistic error metrics to use if the model supports probabilistic predictions. Defaults to CE. Supported values (as list) are: EC, ECE, ECPE; respectively for Empirical Coverage, Empirical Coverage Error, and Empirical Coverage Percentage Error.

• confidence_interval (list) – The confidence interval to use for the evaluation. Default to [0.05, 0.95].

• verbose (bool) – if to print the evaluation progress (one dot = 10% done).

Returns

the evaluation results.

Return type

dict

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

forecast(series, steps=1, context_data=None, **kwargs)

Forecast n steps-ahead data points or slots.

Parameters

• series (TimeSeries) – the series from which to perform the forecast.

• steps – (int): the number of steps to forecast. Defaults to 1.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the forecasted data.

Return type

DataTimePoint or DataTimeSlot or list

property id

A unique identifier for the model. Only for parametric models.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.forecasters.LSTMForecaster(window=3, features=['values'], neurons=128, keras_model=None, window_mask=None)

Bases: Forecaster, _KerasModel

A forecasting model based on a LSTM neural network. LSTMs are artificial neutral networks particularly well suited for time series forecasting tasks.

Parameters

• window (int) – the window length. Defaults to 3.

• features (list) – which features to use. Supported values are: values (use the data values), diffs (use the diffs between the values), and hours (use the hours of the timestamp). Defaults to ['values'].

• neurons (int) – how many neurons to use for the LSTM neural network hidden layer. Defaults to 128.

• keras_model (keras.Model) – an optional external Keras Model architecture. Will cause the neurons argument to be discarded. Defaults to None.

• window_mask (int) – how many elements to dismiss at the end of the window. If provided, has to be negative. Defaults to None.

property window

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

fit(series, epochs=30, normalize=True, normalization='minmax', source='all', target='all', with_context=False, loss='MSE', data_loss_limit=1.0, reproducible=False, probabilistic=False, verbose=False, **kwargs)

Fit the model on a series.

Parameters

• series (series) – the series on which to fit the model.

• epochs (int) – for how many epochs to train. Defaults to 30.

• normalize (bool) – if to normalize the data between 0 and 1 or not. Enabled by default.

• source (str,list) – what data labels to use, defaults to all.

• target (str,list) – what data labels to target, defaults to all.

• with_context (bool) – if to use context (current timestep) data. Not enabled by default.

• loss (str) – the error metric to minimize while fitting (a.k.a. the loss or objective function). Supported values are: MSE, RMSE, MSLE, MAE and MAPE, any other value supported by Keras as loss function or any callable object. Defaults to MSE.

• data_loss_limit (float) – discard from the fit elements with a data loss greater than or equal to this limit. Defaults to 1.

• reproducible (bool) – if to make the fit deterministic. Not enabled by default.

• probabilistic (bool) – if to make the forecaster probabilistic.

• verbose (bool) – if to print the training output in the process. Not enabled by default.

fit_update(series, epochs=30, normalize=True, normalization='minmax', source='all', target='all', with_context=False, loss='MSE', data_loss_limit=1.0, reproducible=False, probabilistic=False, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (series) – the series on which to fit the model.

• epochs (int) – for how many epochs to train. Defaults to 30.

• normalize (bool) – if to normalize the data between 0 and 1 or not. Enabled by default.

• source (str,list) – what data labels to use, defaults to all.

• target (str,list) – what data labels to target, defaults to all.

• with_context (bool) – if to use context (current timestep) data. Not enabled by default.

• loss (str) – the error metric to minimize while fitting (a.k.a. the loss or objective function). Supported values are: MSE, RMSE, MSLE, MAE and MAPE, any other value supported by Keras as loss function or any callable object. Defaults to MSE.

• data_loss_limit (float) – discard from the fit elements with a data loss greater than or equal to this limit. Defaults to 1.

• reproducible (bool) – if to make the fit deterministic. Not enabled by default.

• verbose (bool) – if to print the training output in the process. Not enabled by default.

predict(series, steps=1, context_data=None, samples='auto', verbose=False)

Call the model predict logic on a series.

Parameters

• series (series) – the series on which to perform the predict.

• steps (int) – the number of steps to forecast. Defaults to 1.

• context_data (dict) – the data to use as context for the prediction.

• samples (int, str) – how many samples to use in probabilistic mode.

• verbose (bool) – if to print the predict output in the process.

Returns

the predicted data.

Return type

dict or list

apply(series, steps=1, inplace=False, context_data=None, **kwargs)

Apply the forecast on the given series for n steps-ahead.

Parameters

• series (TimeSeries) – the series on which to apply the model logic.

• steps – (int): the number of steps to forecast. Defaults to 1.

• inplace (bool) – if to apply the forecast in-place on the series. Default to False.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the series with the results of applying the model.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series, steps=1, error_metrics=['RMSE', 'MAE'], return_evaluation_series=False, plot_evaluation_series=False, evaluation_series_error_metrics='auto', plot_error_distribution=False, error_distribution_metrics='auto', confidence_metrics=['EC'], confidence_interval=[0.05, 0.95], verbose=False)

Evaluate the model on a series.

Parameters

• steps (int) – how many steps-ahead to evaluate the model on.

• error_metrics (list) – the (aggregated) error metrics to use for the evaluation. Defaults to RMSE and MAE. Supported values (as list) are: MSE, RMSE, MAE, MaxAE, MAPE, MaxAPE, MALE and MaxALE.

• return_evaluation_series (bool) – if to return the series used for the evaluation, with the the predicted values and the punctual errors.

• plot_evaluation_series (bool) – if to plot the series used for the evaluation, with the the predicted values and the punctual errors.

• evaluation_series_error_metrics (list) – the (punctual) error metrics to be included in the evaluation series. Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE, or None.

• plot_error_distribution (bool) – if to plot the error distribution.

• error_distribution_metrics (list) – the (punctual) error metrics to be used for generating the error distribution(s). Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE.

• confidence_metrics (list) – the probabilistic error metrics to use if the model supports probabilistic predictions. Defaults to CE. Supported values (as list) are: EC, ECE, ECPE; respectively for Empirical Coverage, Empirical Coverage Error, and Empirical Coverage Percentage Error.

• confidence_interval (list) – The confidence interval to use for the evaluation. Default to [0.05, 0.95].

• verbose (bool) – if to print the evaluation progress (one dot = 10% done).

Returns

the evaluation results.

Return type

dict

property fit_history

forecast(series, steps=1, context_data=None, **kwargs)

Forecast n steps-ahead data points or slots.

Parameters

• series (TimeSeries) – the series from which to perform the forecast.

• steps – (int): the number of steps to forecast. Defaults to 1.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the forecasted data.

Return type

DataTimePoint or DataTimeSlot or list

property id

A unique identifier for the model. Only for parametric models.

plot_fit_history(what='auto')

class timeseria.models.forecasters.LinearRegressionForecaster(window=3, features=['values'])

Bases: Forecaster, _KerasModel

A forecasting model based on linear regression.

Parameters

• window (int) – the window length. Defaults to 3.

• features (list) – which features to use. Supported values are: values (use the data values), diffs (use the diffs between the values), and hours (use the hours of the timestamp). Defaults to [values]

property window

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

fit(series, data_loss_limit=1.0, verbose=False)

Fit the model on a series.

Parameters

• series (series) – the series on which to fit the model.

• data_loss_limit (float) – discard from the fit elements with a data loss greater than or equal to this limit. Defaults to 1.

• verbose (bool) – not supported, has no effect.

predict(series, steps=1, verbose=False)

Call the model predict logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the predict logic.

• steps – (int): the number of steps to predict. Defaults to 1.

Returns

the predicted data.

Return type

dict or list

apply(series, steps=1, inplace=False, context_data=None, **kwargs)

Apply the forecast on the given series for n steps-ahead.

Parameters

• series (TimeSeries) – the series on which to apply the model logic.

• steps – (int): the number of steps to forecast. Defaults to 1.

• inplace (bool) – if to apply the forecast in-place on the series. Default to False.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the series with the results of applying the model.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series, steps=1, error_metrics=['RMSE', 'MAE'], return_evaluation_series=False, plot_evaluation_series=False, evaluation_series_error_metrics='auto', plot_error_distribution=False, error_distribution_metrics='auto', confidence_metrics=['EC'], confidence_interval=[0.05, 0.95], verbose=False)

Evaluate the model on a series.

Parameters

• steps (int) – how many steps-ahead to evaluate the model on.

• error_metrics (list) – the (aggregated) error metrics to use for the evaluation. Defaults to RMSE and MAE. Supported values (as list) are: MSE, RMSE, MAE, MaxAE, MAPE, MaxAPE, MALE and MaxALE.

• return_evaluation_series (bool) – if to return the series used for the evaluation, with the the predicted values and the punctual errors.

• plot_evaluation_series (bool) – if to plot the series used for the evaluation, with the the predicted values and the punctual errors.

• evaluation_series_error_metrics (list) – the (punctual) error metrics to be included in the evaluation series. Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE, or None.

• plot_error_distribution (bool) – if to plot the error distribution.

• error_distribution_metrics (list) – the (punctual) error metrics to be used for generating the error distribution(s). Defaults to auto. Supported values (as list) are: SE, AE, APE, ALE, E, PE and LE.

• confidence_metrics (list) – the probabilistic error metrics to use if the model supports probabilistic predictions. Defaults to CE. Supported values (as list) are: EC, ECE, ECPE; respectively for Empirical Coverage, Empirical Coverage Error, and Empirical Coverage Percentage Error.

• confidence_interval (list) – The confidence interval to use for the evaluation. Default to [0.05, 0.95].

• verbose (bool) – if to print the evaluation progress (one dot = 10% done).

Returns

the evaluation results.

Return type

dict

property fit_history

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

forecast(series, steps=1, context_data=None, **kwargs)

Forecast n steps-ahead data points or slots.

Parameters

• series (TimeSeries) – the series from which to perform the forecast.

• steps – (int): the number of steps to forecast. Defaults to 1.

• contxt_data (dict) – any context data for partial forecasting. Defaults to None.

Returns

the forecasted data.

Return type

DataTimePoint or DataTimeSlot or list

property id

A unique identifier for the model. Only for parametric models.

plot_fit_history(what='auto')

timeseria.models.reconstructors module

Data reconstructions models.

class timeseria.models.reconstructors.Reconstructor

Bases: Model

A generic reconstruction model. This class of models work on reconstructing missing data, or in other words to fill gaps. Gaps need a “next” element after their end to be defined, which can bring much more information to the model with respect to a forecasting task.

window = None

apply(series, data_loss_threshold=1.0, inplace=False)

Call the model apply logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the model logic.

• data_loss_threshold (float) – the data loss threshold above which the reconstructor should kick-in. Defaults to 1.0 (reconstructs only full data losses).

Returns

the series with the results of applying the model.

Return type

TimeSeries

predict(series, from_i, to_i)

Call the model predict logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the predict logic.

• from_i (int) – the start of the gap where to predict the reconstruction.

• to_i (int) – the end of the gap where to predict the reconstruction.

Returns

the predicted data.

Return type

dict

evaluate(series, steps='auto', limit=None, data_loss_threshold=1.0, metrics=['RMSE', 'MAE'], details=False)

Evaluate the model on a series.

Parameters

• steps (int, list) – a single value or a list of values for how many steps (intended as missing data points or slots) to reconstruct in the evaluation. Defaults to automatic detection based on the model.

• limit (int) – set a limit for the time data elements to use for the evaluation.

• data_loss_threshold (float) – the data_loss index threshold required for the reconstructor to kick-in.

• metrics (list) – the error metrics to use for the evaluation. Supported values are: RMSE (Root Mean Square Error), MAE (Mean Absolute Error), and MAPE (Mean Absolute percentage Error).

• details (bool) – if to add intermediate steps details to the evaluation results.

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

fit(series, verbose=False)

Fit the model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• verbose (str) – if to be verbose when fitting.

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.reconstructors.LinearInterpolationReconstructor

Bases: Reconstructor

A reconstruction model based on linear interpolation.

The main difference between an interpolator and a reconstructor is that interpolators are used in the transformations, before resampling or aggregating and thus must support variable-resolution time series, while reconstructors are applied after resampling or aggregating, when data has been made already uniform.

In general, in Timeseria a reconstructor modifies (by reconstructing) data which is already present but that cannot be trusted, either because it was created with a high data loss from a transformation or because of other domain-specific factors, while an interpolator creates the missing samples of the underlying signal which are required for the transformations to work.

Interpolators can be then seen as special case of data reconstruction models, that on one hand implement a simpler logic, but that on the other must provide support for time-based math in order or to be able to work on variable-resolution time series.

This reconstructor wraps a linear interpolator in order to perform the data reconstruction, and can be useful for setting a baseline when evaluating other, more sophisticated, data reconstruction models.

window = 1

predict(series, from_i, to_i)

Call the model predict logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the predict logic.

• from_i (int) – the start of the gap where to predict the reconstruction.

• to_i (int) – the end of the gap where to predict the reconstruction.

Returns

the predicted data.

Return type

dict

apply(series, data_loss_threshold=1.0, inplace=False)

Call the model apply logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the model logic.

• data_loss_threshold (float) – the data loss threshold above which the reconstructor should kick-in. Defaults to 1.0 (reconstructs only full data losses).

Returns

the series with the results of applying the model.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series, steps='auto', limit=None, data_loss_threshold=1.0, metrics=['RMSE', 'MAE'], details=False)

Evaluate the model on a series.

Parameters

• steps (int, list) – a single value or a list of values for how many steps (intended as missing data points or slots) to reconstruct in the evaluation. Defaults to automatic detection based on the model.

• limit (int) – set a limit for the time data elements to use for the evaluation.

• data_loss_threshold (float) – the data_loss index threshold required for the reconstructor to kick-in.

• metrics (list) – the error metrics to use for the evaluation. Supported values are: RMSE (Root Mean Square Error), MAE (Mean Absolute Error), and MAPE (Mean Absolute percentage Error).

• details (bool) – if to add intermediate steps details to the evaluation results.

fit(series, verbose=False)

Fit the model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• verbose (str) – if to be verbose when fitting.

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.reconstructors.PeriodicAverageReconstructor

Bases: Reconstructor

A reconstruction model based on periodic averages.

window = 1

fit(series, periodicity='auto', dst_affected=False, offset_method='average', data_loss_limit=1.0, verbose=False)

Fit the reconstructor on some data.

Parameters

• periodicity (int) – the periodicty of the time series. If set to auto then it will be automatically detected using a FFT.

• dst_affected (bool) – if the model should take into account DST effects.

• offset_method (str) – how to offset the reconstructed data in order to align it to the missing data gaps. Supported values are average to use the average gap value, or extremes to use its extremes.

• data_loss_limit (float) – discard from the fit elements with a data loss greater than or equal to this limit.

• verbose (bool) – not supported, has no effect.

predict(series, from_i, to_i)

Call the model predict logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the predict logic.

• from_i (int) – the start of the gap where to predict the reconstruction.

• to_i (int) – the end of the gap where to predict the reconstruction.

Returns

the predicted data.

Return type

dict

apply(series, data_loss_threshold=1.0, inplace=False)

Call the model apply logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the model logic.

• data_loss_threshold (float) – the data loss threshold above which the reconstructor should kick-in. Defaults to 1.0 (reconstructs only full data losses).

Returns

the series with the results of applying the model.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series, steps='auto', limit=None, data_loss_threshold=1.0, metrics=['RMSE', 'MAE'], details=False)

Evaluate the model on a series.

Parameters

• steps (int, list) – a single value or a list of values for how many steps (intended as missing data points or slots) to reconstruct in the evaluation. Defaults to automatic detection based on the model.

• limit (int) – set a limit for the time data elements to use for the evaluation.

• data_loss_threshold (float) – the data_loss index threshold required for the reconstructor to kick-in.

• metrics (list) – the error metrics to use for the evaluation. Supported values are: RMSE (Root Mean Square Error), MAE (Mean Absolute Error), and MAPE (Mean Absolute percentage Error).

• details (bool) – if to add intermediate steps details to the evaluation results.

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

class timeseria.models.reconstructors.ProphetReconstructor

Bases: Reconstructor, _ProphetModel

A reconstruction model based on Prophet. Prophet (from Facebook) implements a procedure for forecasting time series data based on an additive model where non-linear trends are fit with yearly, weekly, and daily seasonality, plus holiday effects.

window = 0

fit(series, verbose=False)

Fit the model on a series.

Parameters

• series (TimeSeries) – the series on which to fit the model.

• verbose (str) – if to be verbose when fitting.

predict(series, from_i, to_i)

Call the model predict logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the predict logic.

• from_i (int) – the start of the gap where to predict the reconstruction.

• to_i (int) – the end of the gap where to predict the reconstruction.

Returns

the predicted data.

Return type

dict

apply(series, data_loss_threshold=1.0, inplace=False)

Call the model apply logic on a series.

Parameters

• series (TimeSeries) – the series on which to apply the model logic.

• data_loss_threshold (float) – the data loss threshold above which the reconstructor should kick-in. Defaults to 1.0 (reconstructs only full data losses).

Returns

the series with the results of applying the model.

Return type

TimeSeries

calibrate(series, calibrator='default', verbose=False, **kwargs)

Calibrate the model using a given calibrator. Will make any prediction probabilistic, according to the calibration logic.

Parameters

• series (TimeSeries) – the series to use for the calibration.

• calibrator (str, Calibrator) – the calibrator class. Defaults to ErrorDistributionCalibrator.

• verbose (string) – if to make the calibration process verbose. Defaults to False.

• **kwargs – calibrator-specific parameters.

cross_validate(series, rounds=10, return_full_evaluations=False, **kwargs)

Cross validate the model on a series, by default with 10 fit/evaluate rounds.

All the parameters starting with the fit_ prefix are forwarded to the model fit() method (without the prefix), and all the parameters starting with the evaluate_ prefix are forwarded to the model evaluate() method (without the prefix).

Parameters

• rounds (int) – how many rounds of cross validation to run.

• return_full_evaluations (bool) – if to return the full evaluations, one for each round.

Returns

the cross validation results.

Return type

dict

evaluate(series, steps='auto', limit=None, data_loss_threshold=1.0, metrics=['RMSE', 'MAE'], details=False)

Evaluate the model on a series.

Parameters

• steps (int, list) – a single value or a list of values for how many steps (intended as missing data points or slots) to reconstruct in the evaluation. Defaults to automatic detection based on the model.

• limit (int) – set a limit for the time data elements to use for the evaluation.

• data_loss_threshold (float) – the data_loss index threshold required for the reconstructor to kick-in.

• metrics (list) – the error metrics to use for the evaluation. Supported values are: RMSE (Root Mean Square Error), MAE (Mean Absolute Error), and MAPE (Mean Absolute percentage Error).

• details (bool) – if to add intermediate steps details to the evaluation results.

fit_update(series, verbose=False, **kwargs)

Update the model fit on a series.

Parameters

• series (TimeSeries) – the series on which to update the fit of the model.

• verbose (str) – if to be verbose when fitting.

property id

A unique identifier for the model. Only for parametric models.

classmethod load(path)

Instantiate the model loading its parameters from a path.

Parameters

path (str) – the path from which to load the model.

Returns

the model instance.

Return type

Model

save(path)

Save the model in the given path. The model is saved in “directory format”, meaning that a new directory will be created containing the data for the model.

Parameters

path (str) – the path where to save the model.

Module contents