Table of Contents

Class VectorAutoRegressionModel<T>

Namespace
AiDotNet.TimeSeries
Assembly
AiDotNet.dll

Implements a Vector Autoregression (VAR) model for multivariate time series forecasting.

public class VectorAutoRegressionModel<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
VectorAutoRegressionModel<T>
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>>
Derived
Inherited Members
Extension Methods

Remarks

The Vector Autoregression (VAR) model is a multivariate extension of the univariate autoregressive model. It captures linear dependencies among multiple time series variables, where each variable is modeled as a function of past values of itself and past values of other variables in the system.

For Beginners: A VAR model helps you forecast multiple related time series at once, accounting for how they influence each other.

For example, if you're analyzing economic data, a VAR model could simultaneously forecast:

  • GDP growth
  • Unemployment rate
  • Inflation rate

While accounting for relationships like:

  • How unemployment affects future GDP
  • How GDP affects future inflation
  • How each variable's past values affect its own future

Think of it as a system that recognizes the interconnected nature of multiple time series and uses these connections to make better forecasts for all variables simultaneously.

Constructors

VectorAutoRegressionModel(VARModelOptions<T>)

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

public VectorAutoRegressionModel(VARModelOptions<T> options)

Parameters

options VARModelOptions<T>

The configuration options for the VAR model.

Remarks

For Beginners: When you create a VAR model, you need to specify several options:

  • Output Dimension: How many different time series you're modeling together
  • Lag: How many past time periods to consider for each variable

For example, if you're modeling quarterly economic indicators with:

  • 3 variables (GDP, unemployment, inflation)
  • Lag of 4 (consider the past year of data)

The constructor initializes the model structure based on these specifications. The coefficients matrix will have dimensions based on the output dimension and lag, with each row representing one equation in the system.

Properties

Coefficients

Gets the coefficient matrix of the VAR model.

public Matrix<T> Coefficients { get; }

Property Value

Matrix<T>

Methods

CreateInstance()

Creates a new instance of the VectorAutoRegressionModel class.

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

Returns

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

A new instance of the VectorAutoRegressionModel 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 brand new, untrained copy of the VAR model with all the same configuration settings as the original. It's like getting a clean template based on your original specifications.

This is primarily used when you want to:

  • Create a copy of your model to experiment with different training approaches
  • Clone the model as part of serialization/deserialization
  • Make a deep copy that's completely independent of the original

The new model will have the same structure (number of variables and lag order) but won't have any trained coefficients until you train it.

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.

It reads:

  • The VAR model options (lag order and output dimension)
  • The coefficient matrix
  • The intercept terms
  • The residuals

All values are read in the same order they were written, converting from double precision back to the generic type T used in the model.

After deserialization, the model is ready to make predictions without needing to be retrained. This is particularly useful for:

  • Deploying models to production environments
  • Sharing models between different applications
  • Saving computation time by not having to retrain complex models

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 the model performs on data it hasn't seen during training.

It calculates several error metrics:

  • MSE (Mean Squared Error): The average squared difference between predictions and actual values

    • Lower is better
    • Penalizes large errors more heavily

  • RMSE (Root Mean Squared Error): The square root of MSE

    • Lower is better
    • In the same units as the original data

  • MAE (Mean Absolute Error): The average absolute difference

    • Lower is better
    • Less sensitive to outliers than MSE

  • MAPE (Mean Absolute Percentage Error): The average percentage difference

    • Lower is better
    • Useful for comparing across different scales

These metrics help you understand how accurate your model is and compare it to other models.

Forecast(Matrix<T>, int)

Generates multi-step forecasts for all variables in the VAR system.

public Matrix<T> Forecast(Matrix<T> historyMatrix, int steps)

Parameters

historyMatrix Matrix<T>

Matrix containing historical observations for all variables.

steps int

Number of steps to forecast.

Returns

Matrix<T>

Matrix of forecasted values where each row is a time step and each column is a variable.

Remarks

This method generates multi-step ahead forecasts for all variables in the VAR system. For each forecast step, it uses previously forecasted values as inputs for the next step.

For Beginners: This method lets you forecast multiple time periods into the future for all variables in your system. For example, you could forecast GDP, unemployment, and inflation for the next 4 quarters.

It works like this:

  1. It starts with your historical data for all variables
  2. It predicts the next period for all variables
  3. It adds these predictions to the history
  4. It uses this updated history to predict the next period
  5. It repeats steps 3-4 until it reaches the requested forecast horizon

This approach is called "iterative forecasting" and it allows the model to capture how variables interact over multiple time periods. Note that forecast uncertainty typically increases the further ahead you predict.

Exceptions

InvalidOperationException

Thrown when the model has not been trained.

ArgumentException

Thrown when history matrix dimensions don't match model configuration or steps is not positive.

GetModelMetadata()

Gets metadata about the VAR model.

public override ModelMetadata<T> GetModelMetadata()

Returns

ModelMetadata<T>

A ModelMetaData object containing information about the model.

Remarks

This method provides comprehensive metadata about the VAR model, including configuration parameters, model coefficients, and serialized model data.

For Beginners: This method returns important information about your VAR model in a structured format. The metadata includes:

  • The type of model (VAR)
  • Configuration details (like lag order and number of variables)
  • The coefficients that describe relationships between variables
  • Serialized model data for storage or transfer

This information is useful for documentation, model management, and comparing different models. It provides a complete snapshot of the model's structure and parameters.

ImpulseResponseAnalysis(int)

Analyzes the dynamic relationships between variables in the VAR system.

public Dictionary<string, Matrix<T>> ImpulseResponseAnalysis(int horizon)

Parameters

horizon int

The number of steps for the impulse response functions.

Returns

Dictionary<string, Matrix<T>>

A dictionary of impulse response matrices, one for each variable.

Remarks

This method computes impulse response functions to analyze how shocks to one variable affect all variables in the system over time.

For Beginners: One of the most valuable aspects of VAR models is understanding how variables affect each other over time. This method helps you see these relationships.

It calculates what would happen to all variables if you introduced a one-time shock (increase or decrease) to one variable. For example:

  • What happens to unemployment and inflation if GDP suddenly increases by 1%?
  • How long do these effects last?
  • Do they fade away or persist?

The results show how shocks propagate through the system over several time periods, helping you understand the dynamic relationships between your variables.

The output contains impulse response functions for each variable, showing how a shock to that variable affects all variables in the system over the specified time horizon.

Exceptions

InvalidOperationException

Thrown when the model has not been trained.

ArgumentException

Thrown when horizon is not positive.

Predict(Matrix<T>)

Generates forecasts using the trained VAR model.

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

Parameters

input Matrix<T>

The input matrix containing the most recent observations of all variables.

Returns

Vector<T>

A vector of forecasted values for all variables.

Remarks

For Beginners: This method uses the trained VAR model to predict the next values for all variables.

It works by:

  1. Checking that the input has the correct dimensions
  2. Starting with the intercept terms for each variable
  3. Adding the weighted contributions of past values according to the estimated coefficients

For example, in a 3-variable system (GDP, unemployment, inflation) with 2 lags, the prediction for GDP might be:

GDP_next = 0.5 + 0.7GDP_t + 0.2GDP_{t-1} - 0.3Unemployment_t - 0.1Unemployment_{t-1} + 0.1Inflation_t + 0.05Inflation_{t-1}

The model makes similar calculations for unemployment and inflation, producing forecasts for all variables simultaneously.

Exceptions

ArgumentException

Thrown when input dimensions don't match the model configuration.

PredictSingle(Vector<T>)

Predicts a single value from one of the variables in the VAR system.

public override T PredictSingle(Vector<T> input)

Parameters

input Vector<T>

Vector of input features for prediction.

Returns

T

The predicted value for the specified variable.

Remarks

This method generates a prediction for a single variable in the VAR system based on the lagged values provided in the input vector.

For Beginners: The VAR model is designed to predict multiple related time series at once, but sometimes you might only need a prediction for one specific variable (like just GDP, not unemployment or inflation).

This method lets you predict one variable based on past values of all variables. The input should contain:

  • The variable index you want to predict (which of your time series)
  • The recent history of all variables in your system

The method uses the equation specifically estimated for that variable, applying the learned coefficients to calculate the next value.

For example, if you want to predict GDP (variable 0), it will use the equation: GDP_next = intercept + coefficient1GDP_t-1 + coefficient2Unemployment_t-1 + ...

Exceptions

InvalidOperationException

Thrown when the model has not been trained.

ArgumentException

Thrown when the input vector has incorrect length or the variableIndex is out of range.

Reset()

Resets the VAR model to its untrained state.

public override void Reset()

Remarks

This method clears all trained parameters and returns the model to its initial state.

For Beginners: This method resets the model to its initial state, clearing all the coefficients and other parameters that were learned during training.

It's useful when you want to:

  • Retrain the model with different data
  • Try different model specifications
  • Clear the model's memory to free up resources

After calling this method, the model will need to be trained again before it can be used for predictions.

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 VAR model options (lag order and output dimension)
  • The coefficient matrix that captures relationships between variables
  • The intercept terms for each equation
  • The residuals from the model fit

All numeric values are converted to double precision for consistent storage regardless of the generic type T used in the model.

After serializing, you can store the model and later deserialize it to make predictions without repeating the training process.

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

Implements the model-specific training logic for the VAR model.

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

Parameters

x Matrix<T>

The input matrix where each column represents a different time series variable.

y Vector<T>

The target values vector (not used in VAR models as they use the input matrix directly).

Remarks

This method handles the specific training logic for Vector Autoregression models. It validates input data, prepares lagged data, estimates coefficients, and calculates residuals.

For Beginners: This method does the actual work of training the VAR model. It follows these steps:

  1. It checks that your data has the right format and enough observations to work with
  2. It organizes the data to show how past values relate to current values
  3. For each variable (like GDP, unemployment, etc.), it finds the best equation that explains that variable based on past values of all variables
  4. It calculates how well these equations fit the data by measuring the errors

When training completes, the model has learned the mathematical relationships between all of your time series variables across time. Each equation shows how one variable depends on past values of itself and other variables.

Exceptions

ArgumentException

Thrown when input dimensions don't match the model configuration or there's insufficient data.

Edit this page