Table of Contents

Class UnobservedComponentsModel<T, TInput, TOutput>

Namespace
AiDotNet.TimeSeries
Assembly
AiDotNet.dll

Implements an Unobserved Components Model (UCM) for time series decomposition and forecasting.

public class UnobservedComponentsModel<T, TInput, TOutput> : TimeSeriesModelBase<T>, ITimeSeriesModel<T>, IFullModel<T, Matrix<T>, Vector<T>>, IModel<Matrix<T>, Vector<T>, ModelMetadata<T>>, IModelSerializer, ICheckpointableModel, IParameterizable<T, Matrix<T>, Vector<T>>, IFeatureAware, IFeatureImportance<T>, ICloneable<IFullModel<T, Matrix<T>, Vector<T>>>, IGradientComputable<T, Matrix<T>, Vector<T>>, IJitCompilable<T>

Type Parameters

T

The numeric type used for calculations (e.g., float, double, decimal).

TInput
TOutput
Inheritance
UnobservedComponentsModel<T, TInput, TOutput>
Implements
IFullModel<T, Matrix<T>, Vector<T>>
IModel<Matrix<T>, Vector<T>, ModelMetadata<T>>
IParameterizable<T, Matrix<T>, Vector<T>>
ICloneable<IFullModel<T, Matrix<T>, Vector<T>>>
IGradientComputable<T, Matrix<T>, Vector<T>>
Inherited Members
Extension Methods

Remarks

The Unobserved Components Model decomposes a time series into several distinct components: trend, seasonal, cycle, and irregular components. It uses state-space modeling and Kalman filtering to estimate these components, which can then be used for forecasting or understanding the underlying patterns in the data.

For Beginners: An Unobserved Components Model is like having X-ray vision for your time series data. It helps you see the hidden patterns that make up your data by breaking it down into several meaningful parts:

  1. Trend Component: The long-term direction of your data. Is it generally going up, down, or staying level over time? This is like the "big picture" movement.

  2. Seasonal Component: Regular patterns that repeat at fixed intervals, such as daily, weekly, monthly, or yearly cycles. For example, retail sales might spike every December for holiday shopping.

  3. Cycle Component: Longer-term ups and downs that don't have a fixed period, often related to business or economic cycles. Unlike seasonal patterns, these aren't tied to the calendar and can vary in length and intensity.

  4. Irregular Component: The random "noise" or unexpected fluctuations that don't fit into the other components. This captures events like unusual weather, one-time promotions, or other unpredictable factors.

The model uses a mathematical technique called Kalman filtering (a bit like a sophisticated version of moving averages) to separate these components from your data. Once separated, you can examine each component individually to better understand what's driving your time series, or recombine them to make forecasts.

This approach is particularly valuable because it:

  • Helps you understand the "why" behind your data's behavior
  • Allows you to forecast each component separately, improving accuracy
  • Makes it easier to spot unusual patterns or anomalies
  • Provides insights that simpler models might miss

Constructors

UnobservedComponentsModel(UnobservedComponentsOptions<T, TInput, TOutput>?)

Creates a new Unobserved Components Model with the specified options.

public UnobservedComponentsModel(UnobservedComponentsOptions<T, TInput, TOutput>? options = null)

Parameters

options UnobservedComponentsOptions<T, TInput, TOutput>

Options for configuring the model. If null, default options are used.

Remarks

For Beginners: This constructor sets up a new Unobserved Components Model with your chosen settings. It initializes all the internal structures needed for the model to work.

You can customize:

  • Whether to include cyclical patterns
  • How many seasonal periods to use (e.g., 7 for weekly, 12 for monthly, 4 for quarterly)
  • How many iterations to run when fitting the model
  • Whether to automatically optimize the model parameters

If you don't provide options, the model will use reasonable default settings.

Properties

SupportsJitCompilation

Gets whether this model supports JIT compilation.

public override bool SupportsJitCompilation { get; }

Property Value

bool

Returns true when the model has decomposed components. Prediction uses precomputed trend, seasonal, and cycle components.

Remarks

For Beginners: While UCM training uses Kalman filtering, prediction combines precomputed components and can be JIT compiled.

Methods

CreateInstance()

Creates a new instance of the UnobservedComponentsModel class.

protected override IFullModel<T, Matrix<T>, Vector<T>> CreateInstance()

Returns

IFullModel<T, Matrix<T>, Vector<T>>

A new instance of the UnobservedComponentsModel class.

Remarks

This factory method creates a new instance of the model with the same options as the current instance. It's used by Clone and DeepCopy methods.

For Beginners: This method creates a fresh copy of the model with the same settings but no trained components. It's like getting a blank copy of the original model's template.

This is used internally when you clone a model or make a deep copy. It ensures that the copy is of the exact same type as the original, with all the same configuration options.

DeserializeCore(BinaryReader)

Deserializes the model's state from a binary stream.

protected override void DeserializeCore(BinaryReader reader)

Parameters

reader BinaryReader

The binary reader to read from.

Remarks

For Beginners: This protected method loads a previously saved model from a file or stream.

Deserialization allows you to:

  1. Load a previously trained model
  2. Use it immediately without retraining
  3. Apply the exact same model to new data

The method loads:

  • The decomposed trend component
  • The seasonal component
  • The cycle component
  • The irregular component
  • Key model options

After deserialization, the model is ready to make predictions as if it had just been trained.

EvaluateModel(Matrix<T>, Vector<T>)

Evaluates the model's performance on test data.

public override Dictionary<string, T> EvaluateModel(Matrix<T> xTest, Vector<T> yTest)

Parameters

xTest Matrix<T>

Test input matrix containing time indices.

yTest Vector<T>

Test target vector containing actual values.

Returns

Dictionary<string, T>

Dictionary of evaluation metrics.

Remarks

For Beginners: This method measures how well the model performs by comparing its predictions against actual values from a test dataset.

It calculates several common error metrics:

  • MAE (Mean Absolute Error): The average absolute difference between predictions and actual values. Lower is better. If MAE = 5, your predictions are off by 5 units on average.

  • MSE (Mean Squared Error): The average of squared differences between predictions and actual values. Lower is better, but squaring emphasizes large errors. MSE is useful for optimization.

  • RMSE (Root Mean Squared Error): The square root of MSE, which gives errors in the same units as your original data. For example, if forecasting sales in dollars, RMSE is also in dollars.

  • R² (R-squared): The proportion of variance in the dependent variable explained by the model. Values range from 0 to 1, with higher values indicating better fit. An R² of 0.75 means the model explains 75% of the variation in the data.

These metrics together provide a comprehensive assessment of model performance.

ExportComputationGraph(List<ComputationNode<T>>)

Exports the UCM model as a computation graph for JIT compilation.

public override ComputationNode<T> ExportComputationGraph(List<ComputationNode<T>> inputNodes)

Parameters

inputNodes List<ComputationNode<T>>

A list to which input nodes will be added.

Returns

ComputationNode<T>

The output computation node representing the forecast.

Remarks

The computation graph represents: forecast = trend + seasonal + cycle

Forecast(int, int)

Forecasts multiple steps into the future using the decomposed components.

public Vector<T> Forecast(int horizon, int startIndex = -1)

Parameters

horizon int

The number of time steps to forecast.

startIndex int

The time index to start forecasting from (defaults to the end of the training data).

Returns

Vector<T>

A vector containing the forecasted values.

Remarks

This method generates forecasts for multiple future time points by extending each component (trend, seasonal, cycle) based on its natural pattern and properties.

For Beginners: This method predicts values for multiple future time points by:

  1. Extending the trend component using its growth pattern
  2. Repeating the seasonal component based on its period
  3. Continuing the cycle component based on its frequency
  4. Adding small random variations to represent the irregular component

For example, a 12-month forecast of retail sales might:

  • Continue the upward trend line
  • Repeat the December sales peak and summer slump
  • Account for the current phase of the business cycle
  • Include small random variations

The result is a comprehensive forecast that captures all the patterns identified in your historical data.

Exceptions

InvalidOperationException

Thrown when the model has not been trained.

ArgumentException

Thrown when horizon is not positive or startIndex is invalid.

GetComponents()

Gets the decomposed components of the time series.

public Dictionary<string, Vector<T>> GetComponents()

Returns

Dictionary<string, Vector<T>>

A dictionary containing the trend, seasonal, cycle, and irregular components.

Remarks

This method provides access to the individual decomposed components identified by the model.

For Beginners: This method gives you the separate pieces that make up your time series, like looking inside a watch to see all the gears and springs. You can examine:

  • The trend component: The overall direction (going up, down, or flat)
  • The seasonal component: Regular patterns tied to the calendar
  • The cycle component: Longer-term patterns not tied to fixed periods
  • The irregular component: Random variations or "noise"

This decomposition helps you understand what's really driving your data and makes it easier to interpret and forecast.

Exceptions

InvalidOperationException

Thrown when the model has not been trained.

GetModelMetadata()

Gets metadata about the model, including its type, components, and configuration.

public override ModelMetadata<T> GetModelMetadata()

Returns

ModelMetadata<T>

A ModelMetaData object containing information about the model.

Remarks

This method returns detailed metadata about the Unobserved Components Model, including its type, trained components (trend, seasonal, cycle), and configuration options. This metadata can be used for model selection, comparison, documentation, and serialization purposes.

For Beginners: This provides a summary of your model's settings and what it has learned.

The metadata includes:

  • The type of model (Unobserved Components Model)
  • Information about each component (trend, seasonal, cycle, irregular)
  • Configuration settings like seasonal period and whether cycles are included
  • A serialized version of the entire model

This information is useful for:

  • Keeping track of different models you've created
  • Comparing model configurations
  • Documenting which settings worked best
  • Sharing model information with others

Predict(Matrix<T>)

Makes predictions using the trained model.

public override Vector<T> Predict(Matrix<T> input)

Parameters

input Matrix<T>

Input matrix containing time indices for prediction.

Returns

Vector<T>

Vector of predicted values.

Remarks

For Beginners: This method generates predictions for future time points based on the decomposed components identified during training.

For each time point in the input:

  1. It calls the PredictSingle method to generate a single prediction
  2. It combines the trend, seasonal, cycle, and irregular components

The predictions incorporate all the patterns identified in your data, including:

  • The long-term trend direction
  • Seasonal patterns that repeat at fixed intervals
  • Cyclical patterns with varying periods
  • A reasonable amount of random variation

These comprehensive predictions reflect the full structure of your time series.

PredictSingle(Vector<T>)

Generates a prediction for a single input vector.

public override T PredictSingle(Vector<T> input)

Parameters

input Vector<T>

A vector containing the time index and any additional features.

Returns

T

The predicted value for the specified time point.

Remarks

This method combines the trend, seasonal, cycle, and irregular components to produce a prediction for a single time point.

For Beginners: This method makes a prediction for a single point in time by adding together all the components the model has identified in your data:

  • Trend component: The long-term direction (going up, down, or flat)
  • Seasonal component: Regular patterns tied to the calendar (like weekly or yearly cycles)
  • Cycle component: Longer-term patterns not tied to fixed periods (like business cycles)
  • Irregular component: Random variations or "noise" in the data

For example, if forecasting retail sales, the prediction might combine:

  • An upward trend (business growth)
  • A seasonal peak (December holiday shopping)
  • A downward cycle (current economic recession)
  • Some random variation

The result gives you a comprehensive forecast that accounts for all identified patterns.

Exceptions

InvalidOperationException

Thrown when the model has not been trained.

ArgumentException

Thrown when the input index is invalid or out of range.

Reset()

Resets the model to its untrained state.

public override void Reset()

Remarks

This method clears all trained parameters and decomposed components, returning the model to its initial state.

For Beginners: This method clears all the learning the model has done, basically giving you a fresh start. It's like erasing the whiteboard so you can use the same model to analyze a different time series.

After calling this method, you'll need to train the model again before making predictions.

SerializeCore(BinaryWriter)

Serializes the model's state to a binary stream.

protected override void SerializeCore(BinaryWriter writer)

Parameters

writer BinaryWriter

The binary writer to write to.

Remarks

For Beginners: This protected method saves the model's internal state to a file or stream.

Serialization allows you to:

  1. Save a trained model to disk
  2. Load it later without having to retrain
  3. Share the model with others

The method saves the essential components of the model:

  • The decomposed trend component
  • The seasonal component
  • The cycle component
  • The irregular component
  • Key model options

This allows the model to be fully reconstructed later.

TrainCore(Matrix<T>, Vector<T>)

Implements the model-specific training logic for the Unobserved Components Model.

protected override void TrainCore(Matrix<T> x, Vector<T> y)

Parameters

x Matrix<T>

The input features matrix (typically time indices).

y Vector<T>

The target values (time series data).

Remarks

This method handles the core training process for the UCM model, orchestrating the initialization, Kalman filtering, smoothing, and parameter optimization steps.

For Beginners: This method coordinates the learning process for the model. It manages the different steps that transform your raw time series data into separate components (trend, seasonal, cycle, and irregular).

The process follows these main steps:

  1. It makes initial guesses about the components using simple techniques
  2. It sets up the mathematical structures needed for the Kalman filter
  3. It runs the Kalman filter to refine these initial estimates
  4. It applies the Kalman smoother to further improve the estimates using future information
  5. It checks if the estimates have stabilized (converged)
  6. If requested, it optimizes the model parameters to better fit your specific data

When the training completes, your time series will be fully decomposed into its component parts, which can then be used for analysis or forecasting.

Exceptions

ArgumentException

Thrown when the input data is invalid.

Edit this page