UnobservedComponentsModel<T, TInput, TOutput>
Models & Types · AiDotNet.TimeSeries
Implements an Unobserved Components Model (UCM) for time series decomposition and forecasting.
Inheritance: TimeSeriesModelBase<T> → UnobservedComponentsModel<T, TInput, TOutput>
Implements: IGeneratedParameterRegistrar<T>
How It Works
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:
- 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.
- 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.
- 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.
- 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
Example
var trainingMatrix = new Matrix<double>(new double[,] { { 1.0 }, { 2.0 }, { 3.0 }, { 4.0 } });
var trainingLabels = new Vector<double>(new double[] { 112, 118, 132, 129 });
// Decompose time series into unobserved trend, cycle, and seasonal components
var result = new AiModelBuilder<double, Matrix<double>, Vector<double>>()
.ConfigureModel(new UnobservedComponentsModel<double, Matrix<double>, Vector<double>>(
new UnobservedComponentsOptions<double, Matrix<double>, Vector<double>>()))
.Build(trainingMatrix, trainingLabels);
Vector<double> forecast = result.Forecast(horizon: 24);
Constructors
| Constructor | Summary |
|---|---|
UnobservedComponentsModel(UnobservedComponentsOptions<T, TInput, TOutput> options) |
Creates a new Unobserved Components Model with the specified options. |
Methods
| Method | Summary |
|---|---|
Dictionary<string, T> EvaluateModel(Matrix<T> xTest, Vector<T> yTest) |
Evaluates the model’s performance on test data. |
Dictionary<string, Vector<T>> GetComponents() |
Gets the decomposed components of the time series. |
ModelMetadata<T> GetModelMetadata() |
Gets metadata about the model, including its type, components, and configuration. |
T PredictSingle(Vector<T> input) |
Generates a prediction for a single input vector. |
Vector<T> Forecast(int horizon, int startIndex) |
Forecasts multiple steps into the future using the decomposed components. |
Vector<T> Predict(Matrix<T> input) |
Makes predictions using the trained model. |
void Reset() |
Resets the model to its untrained state. |