Theta

Model

DashAI.back.models.forecasting.Theta

---

Forecast by blending the long-term trend with the recent level.

The Theta method splits the series into two lines. The first is a straight line fitted to the whole history, its long-term direction. The second keeps the history's short-term swings, amplified around that line. The straight line is extended into the future, the second line is forecast with simple exponential smoothing, and the two forecasts are combined.

Hyndman and Billah showed that the result is simple exponential smoothing with a drift of half the slope of the straight line. That damped trend is why the method holds up so well: it follows the direction of a series without projecting all of it. It won the M3 forecasting competition and is a standard benchmark since.

The theta parameter sets how much of the trend the forecast follows: 1 gives no drift, 2 is the classical method, larger values follow more of the slope.

A seasonal component is removed by classical decomposition before the fit and put back on the forecast. When one is selected it is always applied: statsmodels would otherwise run a test first and skip the season without a word when the test does not find it.

It uses no exogenous variables and only follows a linear trend.

References

• [1] https://www.statsmodels.org/stable/generated/statsmodels.tsa.forecasting.theta.ThetaModel.html
• [2] https://otexts.com/fpp3/the-theta-method.html

Parameters

seasonal : string, default=none

Whether to remove a repeating pattern before forecasting and put it back after. 'add' when the swing is about the same size each cycle, 'mul' when it grows with the level (needs positive values), 'none' for a series with no season.

season_length : integer, default=1

How many observations make up one full cycle: 12 for monthly data repeating yearly, 7 for daily data repeating weekly.

theta : number, default=2.0

How much of the long-term trend the forecast follows. 1 ignores the trend and forecasts a flat line from the recent level; 2, the classical method, follows half of it; larger values follow more of it.

Methods

calculate_metrics(self, split: DashAI.back.core.enums.metrics.SplitEnum = <SplitEnum.VALIDATION: 'validation'>, level: DashAI.back.core.enums.metrics.LevelEnum = <LevelEnum.LAST: 'last'>, log_index: int = None, x_data: 'DashAIDataset' = None, y_data: 'DashAIDataset' = None, fold_index: int = None, inner_fold_index: int = None)

Defined on BaseModel

Calculate metrics for a data split and save them to the database.

Parameters

split : SplitEnum

The data split to evaluate (TRAIN, VALIDATION, or TEST). Defaults to SplitEnum.VALIDATION.

level : LevelEnum

The metric granularity level (LAST, TRIAL, STEP, or BATCH). Defaults to LevelEnum.LAST.

log_index : int, optional

Explicit step index for the metric entry. If None, the next step index is computed automatically. Defaults to None.

x_data : DashAIDataset, optional

Input features. If None, the dataset stored in the model for the given split is used. Defaults to None.

y_data : DashAIDataset, optional

Target labels. If None, the labels stored in the model for the given split are used. Defaults to None.

Returns

Dict[str, float] or None

What was written, so a caller that also wants the numbers does not have to score the same split twice. None when nothing was written: no run to write against, or nothing to score.

compute_metrics(self, split: DashAI.back.core.enums.metrics.SplitEnum = <SplitEnum.VALIDATION: 'validation'>, x_data: 'DashAIDataset' = None, y_data: 'DashAIDataset' = None) -> Optional[Dict[str, float]]

Defined on BaseModel

Score a data split with this model's metrics, without persisting.

Parameters

split : SplitEnum

The data split to evaluate. Defaults to SplitEnum.VALIDATION.

x_data : DashAIDataset, optional

Input features. Defaults to the split stored on the model.

y_data : DashAIDataset, optional

Target labels. Defaults to the split stored on the model.

Returns

Dict[str, float] or None

Metric name to score. A metric that scored a non-finite value is absent from the mapping rather than present with a NaN, so the mapping is empty when every metric returned one. None when there is nothing to score at all: no metrics configured, or no data for this split. Callers that need a particular metric must therefore check that it is there. A metric with no value on the data (UndefinedMetricError) is absent the same way.

fit(self, y: Sequence[float], x: Optional[Any] = None) -> 'SingleSeriesForecastingModel'

Defined on SingleSeriesForecastingModel

Fit the model on the series, in time order.

Parameters

y : sequence of float

The series, one value per step of its grid.

x : array-like, optional

Exogenous variables, one row per step. Refused by a model that declares EXOGENOUS = "none", and required by one that declares "required".

Returns

SingleSeriesForecastingModel

The fitted model.

get_credential(self, name: str)

Defined on ConfigObject

Resolve a registered credential component by name.

Parameters

name : str

Credential component class name (e.g. "HuggingFaceCredential").

Returns

BaseCredential

An instance of the requested credential component.

get_metadata(cls) -> Dict[str, Any]

Defined on SingleSeriesForecastingModel

The model's metadata, with what it does with exogenous variables.

get_schema(cls) -> dict

Defined on ConfigObject

Generates the component related Json Schema.

Returns

dict

Dictionary representing the Json Schema of the component.

load(filename: str) -> Any

Defined on SingleSeriesForecastingModel

Deserialise a model from disk using joblib.

Parameters

filename : str

Path to the file previously written by :meth:save.

Returns

SingleSeriesForecastingModel

The loaded model instance.

predict(self, h: int, x_future: Optional[Any] = None, levels: Optional[Sequence[int]] = None) -> DashAI.back.models.forecasting.single_series_forecasting_model.Forecast

Defined on SingleSeriesForecastingModel

Forecast the h steps that follow the fitted series.

Parameters

h : int

How many steps to forecast, at least 1.

x_future : array-like, optional

Exogenous variables for the forecast steps, one row per step.

levels : sequence of int, optional

Prediction interval levels, in percent, each between 0 and 100.

Returns

Forecast

The point forecast and, if levels were asked for, the intervals.

predict_prepared(self, features: Any) -> Any

Defined on BaseModel

Predict from data that is already in this model's feature space.

Parameters

features : pandas.DataFrame or numpy.ndarray

Feature matrix as returned by prepare_dataset(..., is_fit=False). No further preparation is applied to it.

Returns

Any

The same kind of output as predict: predicted values for regressors, class probabilities for DashAI classifiers.

predict_proba_prepared(self, features: Any) -> Any

Defined on BaseModel

Return class probabilities for data already in the feature space.

Parameters

features : pandas.DataFrame or numpy.ndarray

Feature matrix as returned by prepare_dataset(..., is_fit=False).

Returns

numpy.ndarray

Array of shape (n_samples, n_classes) with class probabilities.

prepare_dataset(self, dataset: 'DashAIDataset', is_fit: bool = False) -> 'DashAIDataset'

Defined on BaseModel

Hook for model specific preprocessing of input features.

Parameters

dataset : DashAIDataset

The input dataset to preprocess.

is_fit : bool

Whether the call is part of a fitting phase. Defaults to False.

Returns

DashAIDataset

The preprocessed dataset ready to be fed into the model.

prepare_output(self, dataset: 'DashAIDataset', is_fit: bool = False) -> 'DashAIDataset'

Defined on BaseModel

Hook for model-specific preprocessing of output targets.

Parameters

dataset : DashAIDataset

The output dataset (target labels) to preprocess.

is_fit : bool

Whether the call is part of a fitting phase. Defaults to False.

Returns

DashAIDataset

The preprocessed output dataset.

save(self, filename: str) -> None

Defined on SingleSeriesForecastingModel

Serialise the model to disk using joblib.

Parameters

filename : str

Destination file path where the model will be written.

train(self, x_train: 'DashAIDataset', y_train: 'DashAIDataset', x_validation: 'DashAIDataset' = None, y_validation: 'DashAIDataset' = None) -> 'SingleSeriesForecastingModel'

Defined on SingleSeriesForecastingModel

Fit on the series held by y_train, ignoring every other input.

Parameters

x_train : DashAIDataset

Ignored: the model never sees dates.

y_train : DashAIDataset

One column holding the series, in time order.

x_validation, y_validation : DashAIDataset, optional

Ignored.

Returns

SingleSeriesForecastingModel

The fitted model.

validate_and_transform(self, raw_data: dict) -> dict

Defined on ConfigObject

It takes the data given by the user to initialize the model and returns it with all the objects that the model needs to work.

Parameters

raw_data : dict

A dictionary with the data provided by the user to initialize the model.

Returns

dict

A validated dictionary with the necessary objects.

Compatible with

• SingleSeriesForecastingTask