Class StateSpaceModel<T>

Namespace

AiDotNet.TimeSeries

Assembly

AiDotNet.dll

Implements a State Space Model for time series analysis and forecasting.

public class StateSpaceModel<T> : 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 data type used for calculations (e.g., float, double).

Inheritance

object

TimeSeriesModelBase<T>

StateSpaceModel<T>

Implements

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>

Inherited Members

TimeSeriesModelBase<T>.Options

TimeSeriesModelBase<T>.NumOps

TimeSeriesModelBase<T>.Engine

TimeSeriesModelBase<T>.ModelParameters

TimeSeriesModelBase<T>.IsTrained

TimeSeriesModelBase<T>.LastEvaluationMetrics

TimeSeriesModelBase<T>.ValidateOptions(TimeSeriesRegressionOptions<T>)

TimeSeriesModelBase<T>.Train(Matrix<T>, Vector<T>)

TimeSeriesModelBase<T>.ValidateTrainingInputs(Matrix<T>, Vector<T>)

TimeSeriesModelBase<T>.ValidatePredictionInput(Matrix<T>)

TimeSeriesModelBase<T>.CalculateErrorMetrics(Vector<T>, Vector<T>)

TimeSeriesModelBase<T>.Serialize()

TimeSeriesModelBase<T>.Deserialize(byte[])

TimeSeriesModelBase<T>.GetParameters()

TimeSeriesModelBase<T>.WithParameters(Vector<T>)

TimeSeriesModelBase<T>.ApplyParameters(Vector<T>)

TimeSeriesModelBase<T>.GetActiveFeatureIndices()

TimeSeriesModelBase<T>.IsFeatureUsed(int)

TimeSeriesModelBase<T>.GetFeatureImportance(int)

TimeSeriesModelBase<T>.SetParameters(Vector<T>)

TimeSeriesModelBase<T>.SetActiveFeatureIndices(IEnumerable<int>)

TimeSeriesModelBase<T>.GetFeatureImportance()

TimeSeriesModelBase<T>.DeepCopy()

TimeSeriesModelBase<T>.Clone()

TimeSeriesModelBase<T>.Reset()

TimeSeriesModelBase<T>.Clip(T, T, T)

TimeSeriesModelBase<T>.Forecast(Vector<T>, int)

TimeSeriesModelBase<T>.PrepareForecastFeatures(List<T>, int)

TimeSeriesModelBase<T>.ParameterCount

TimeSeriesModelBase<T>.SaveModel(string)

TimeSeriesModelBase<T>.LoadModel(string)

TimeSeriesModelBase<T>.DefaultLossFunction

TimeSeriesModelBase<T>.ComputeGradients(Matrix<T>, Vector<T>, ILossFunction<T>)

TimeSeriesModelBase<T>.ApplyGradients(Vector<T>, T)

TimeSeriesModelBase<T>.SaveState(Stream)

TimeSeriesModelBase<T>.LoadState(Stream)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

DistributedExtensions.AsDistributedForHighBandwidth<T, TInput, TOutput>(IFullModel<T, TInput, TOutput>, ICommunicationBackend<T>)

DistributedExtensions.AsDistributedForLowBandwidth<T, TInput, TOutput>(IFullModel<T, TInput, TOutput>, ICommunicationBackend<T>)

DistributedExtensions.AsDistributed<T, TInput, TOutput>(IFullModel<T, TInput, TOutput>, ICommunicationBackend<T>)

DistributedExtensions.AsDistributed<T, TInput, TOutput>(IFullModel<T, TInput, TOutput>, IShardingConfiguration<T>)

Remarks

State Space Models represent time series data as a system with hidden states that evolve over time according to probabilistic rules. They are powerful tools for modeling complex dynamic systems and can handle missing data, multiple variables, and non-stationary patterns.

For Beginners: A State Space Model is like tracking the position of a moving object when you can only see its shadow. The actual position (state) is hidden, but you can observe its effects (the shadow).

For example, if you're tracking the economy, you might not directly observe the "true state" of the economy, but you can see indicators like GDP, unemployment rates, etc. The State Space Model helps infer the hidden state from these observations and predict future values.

The model has two main components:

1. A transition equation that describes how the hidden state evolves over time
2. An observation equation that relates the hidden state to what we actually observe

This implementation uses the Kalman filter and smoother algorithms to estimate the hidden states and learn the model parameters from data.

Constructors

StateSpaceModel(StateSpaceModelOptions<T>)

Initializes a new instance of the StateSpaceModel class with the specified options.

public StateSpaceModel(StateSpaceModelOptions<T> options)

Parameters

options StateSpaceModelOptions<T>

The configuration options for the state space model.

Properties

SupportsJitCompilation

Gets whether this model supports JIT compilation.

public override bool SupportsJitCompilation { get; }

Property Value

bool

Returns true when the model has been trained with valid state matrices. State Space Model prediction is a simple matrix operation: state = T @ state, output = H @ state.

Remarks

For Beginners: JIT compilation optimizes the state space prediction by precompiling the matrix operations for state transitions and observations. This provides faster inference for real-time forecasting.

Methods

CreateInstance()

Creates a new instance of the State Space Model with the same options.

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

Returns

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

A new instance of the State Space Model.

Remarks

This method creates a new instance of the State Space Model with the same configuration options as the current instance. This new instance is not trained and will need to be trained on data.

For Beginners: This method creates a fresh copy of the model with the same settings but no training.

It's useful when you want to:

• Create multiple versions of the same model
• Train models on different data sets
• Experiment with ensemble models (combining multiple models)
• Compare different training approaches with the same model structure

The new model copy will have identical configuration options but will need to be trained from scratch on your data.

DeserializeCore(BinaryReader)

Deserializes the model's core parameters from a binary reader.

protected override void DeserializeCore(BinaryReader reader)

Parameters

reader BinaryReader

The binary reader to read from.

Remarks

For Beginners: Deserialization is the process of loading a previously saved model from disk. This method reads the model's parameters from a file and reconstructs the model exactly as it was when it was saved.

This allows you to train a model once and then use it many times without retraining. It's like writing down a recipe so you can make the same dish again later without having to figure out the ingredients and proportions from scratch.

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

Evaluates the performance of the trained model on test data.

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

Parameters

xTest Matrix<T>

The input features matrix for testing.

yTest Vector<T>

The actual target values for testing.

Returns

Dictionary<string, T>

A dictionary containing evaluation metrics.

Remarks

For Beginners: This method tests how well our model performs by comparing its predictions to actual values. It calculates several error metrics:

• MSE (Mean Squared Error): The average of the squared differences between predictions and actual values
• RMSE (Root Mean Squared Error): The square root of MSE, which gives an error in the same units as the data
• MAE (Mean Absolute Error): The average of the absolute differences between predictions and actual values
• MAPE (Mean Absolute Percentage Error): The average percentage difference between predictions and actual values

Lower values for these metrics indicate better model performance.

ExportComputationGraph(List<ComputationNode<T>>)

Exports the State Space 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 the state space equations: - State transition: state_new = T @ state - Observation: output = H @ state_new

For Beginners: This converts the state space model into an optimized computation graph. For single-step prediction: 1. Apply transition matrix to current state 2. Apply observation matrix to get prediction

Expected speedup: 2-5x for inference after JIT compilation.

GetModelMetadata()

Gets metadata about the model, including its type, parameters, 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 State Space Model, including its type, configuration, and trained parameters. This metadata can be used for model selection, comparison, documentation, and serialization purposes.

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

The metadata includes:

• The type of model (State Space Model)
• Information about the dimensions of the state and observation spaces
• Details about the key matrices that define the model's behavior
• Configuration settings like learning rate and convergence criteria
• 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>)

Generates predictions using the trained state space model.

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

Parameters

input Matrix<T>

The input features matrix for which predictions are to be made.

Returns

Vector<T>

A vector of predicted values.

Remarks

For Beginners: This method predicts future values by:

1. Starting with our initial state estimate
2. Using the transition matrix to predict how the state will evolve at each time step
3. Using the observation matrix to convert these state predictions into observable predictions

It's like predicting where the shadow will appear based on our understanding of how the object moves. We don't directly predict the shadow; we predict the object's position and then calculate where its shadow would be.

PredictSingle(Vector<T>)

Predicts a single value based on the input vector.

public override T PredictSingle(Vector<T> input)

Parameters

input Vector<T>

The input vector containing features for prediction.

Returns

T

The predicted value for the given input.

Remarks

This method generates a prediction for a single input vector by propagating the state and transforming it to the observation space.

For Beginners: This method generates a single prediction from your input features. It works by:

1. Checking that the model is properly initialized and ready to make predictions
2. Creating a matrix from your input vector (since the internal methods expect matrices)
3. Using the model's understanding of how the hidden state evolves to make a prediction
4. Transforming this predicted state into an observable prediction

The result is a value that represents the model's best guess for the target variable given the input features, based on the patterns it learned during training.

Exceptions

InvalidOperationException

Thrown when the model has not been properly initialized.

SerializeCore(BinaryWriter)

Serializes the model's core parameters to a binary writer.

protected override void SerializeCore(BinaryWriter writer)

Parameters

writer BinaryWriter

The binary writer to write to.

Remarks

For Beginners: Serialization is the process of converting the model's state into a format that can be saved to disk. This allows you to save a trained model and load it later without having to retrain it.

This method saves:

• The dimensions of the state and observation vectors
• The transition and observation matrices
• The process and observation noise matrices
• The initial state vector
• Other parameters like learning rate and convergence settings

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

Core implementation of the training logic for the State Space Model.

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

Parameters

x Matrix<T>

The input features matrix.

y Vector<T>

The target values vector.

Remarks

This method implements the core training logic for the State Space Model using the Expectation-Maximization (EM) algorithm with Kalman filtering and smoothing.

For Beginners: This is the engine behind the training process. It follows these steps:

1. First, it combines your input features and target values into a matrix of observations
2. Then it runs the EM algorithm, which alternates between:
   • Estimating the hidden states using the Kalman filter and smoother (the E-step)
   • Updating the model parameters based on these estimated states (the M-step)
3. It keeps refining its estimates until the parameters stop changing significantly or until it reaches the maximum number of iterations

This process allows the model to learn both how the hidden state evolves and how it relates to the observations, which is essential for making accurate predictions.