Table of Contents

Class TransferFunctionModel<T>

Namespace
AiDotNet.TimeSeries
Assembly
AiDotNet.dll

Implements a Transfer Function Model for time series analysis, which combines ARIMA modeling with external input variables to capture dynamic relationships between multiple time series.

public class TransferFunctionModel<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
TransferFunctionModel<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>>
Inherited Members
Extension Methods

Remarks

The Transfer Function Model extends traditional ARIMA models by incorporating the effects of external input variables. It models the relationship between an output time series and one or more input time series, accounting for both immediate and lagged effects.

For Beginners: A Transfer Function Model helps you understand how one time series affects another over time.

For example, you might want to know:

  • How advertising spending affects sales (with delays of days or weeks)
  • How temperature changes affect energy consumption
  • How interest rate changes impact housing prices

This model captures both:

  • The internal patterns of your target variable (like sales following their own seasonal patterns)
  • The external influence of input variables (like how advertising boosts sales)

It's particularly useful when you know there are external factors influencing your target variable and you want to quantify their effects, including any time delays in those effects.

Constructors

TransferFunctionModel(TransferFunctionOptions<T, Matrix<T>, Vector<T>>?)

Initializes a new instance of the TransferFunctionModel class with optional configuration options.

public TransferFunctionModel(TransferFunctionOptions<T, Matrix<T>, Vector<T>>? options = null)

Parameters

options TransferFunctionOptions<T, Matrix<T>, Vector<T>>

The configuration options for the Transfer Function Model. If null, default options are used.

Remarks

For Beginners: When you create a Transfer Function Model, you can customize it with various options:

  • AR Order: How many past values of the output series to consider
  • MA Order: How many past error terms to consider
  • Input Lag Order: How many past values of the input series to consider
  • Output Lag Order: How many additional past values of the output to consider
  • Optimizer: The algorithm used to find the best parameter values

The constructor initializes all the parameters that will be estimated during training. These parameters start empty and will be filled with values during the training process.

Methods

CreateInstance()

Creates a new instance of the Transfer Function 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 Transfer Function Model.

Remarks

This method creates a new instance of the Transfer Function 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.

It reads:

  • The AR parameters
  • The MA parameters
  • The input lag parameters
  • The output lag parameters
  • The model configuration options

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 works by:

  1. Using the model to make predictions on the test data
  2. Comparing these predictions to the actual test values
  3. Calculating various error metrics to quantify the accuracy

The metrics calculated include:

  • MAE (Mean Absolute Error): The average absolute difference between predictions and actual values

    • Lower is better
    • Easy to interpret: "On average, predictions are off by X units"

  • MSE (Mean Squared Error): The average squared difference

    • 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

  • R² (R-squared): The proportion of variance explained by the model

    • Ranges from 0 to 1 (higher is better)
    • 0.7 means the model explains 70% of the variation in the data

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

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 Transfer Function Model, including its type, parameters (AR, MA, input lags, output lags), and configuration options. 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 (Transfer Function Model)
  • Information about each set of parameters and how many there are
  • Configuration settings like AR order, MA order, etc.
  • 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 forecasts using the trained Transfer Function Model.

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

Parameters

input Matrix<T>

The input features matrix containing external variables.

Returns

Vector<T>

A vector of forecasted values.

Remarks

For Beginners: This method uses the trained model to predict values for new input data.

For each time point, it:

  1. Considers the AR terms (past values of the output)
  2. Adds the MA terms (past prediction errors)
  3. Adds the effects of the input variables at various lags
  4. Adds the effects of additional output lags

The result is a forecast that accounts for both:

  • The internal patterns of the output series
  • The influence of the input variables

This is useful for scenarios like predicting sales based on advertising spend, where you want to account for both the natural sales patterns and the boost from ads.

PredictSingle(Vector<T>)

Generates a prediction for a single 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.

Remarks

This method generates a single prediction based on the input vector, using the trained model parameters to combine autoregressive, moving average, and transfer function components.

For Beginners: This method creates a prediction for a single point in time based on your input data.

It combines several components to make this prediction:

  1. The effect of past values of the output variable (AR component)
  2. The effect of past prediction errors (MA component)
  3. The effect of the input variables at different time lags
  4. The effect of additional past output values

The method checks if the model has been trained first and then carefully applies each component to generate an accurate prediction. This is particularly useful when you need just one prediction rather than a whole series.

Exceptions

InvalidOperationException

Thrown when the model hasn't been trained.

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 AR parameters (how past output values affect current values)
  • The MA parameters (how past errors affect current values)
  • The input lag parameters (how past input values affect current output)
  • The output lag parameters (how additional past output values affect current output)
  • The model configuration options (AR order, MA order, etc.)

After serializing, you can store the model and later deserialize it to make predictions without repeating the training process, which can save significant time for complex models.

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

The core implementation of the training process for the Transfer Function Model.

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

Parameters

x Matrix<T>

The input features matrix containing external variables.

y Vector<T>

The output time series data to model.

Remarks

This method implements the training process for the Transfer Function Model, handling validation, initialization, parameter optimization, and residual computation.

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

  1. First, it checks that your input and output data have the right dimensions
  2. Then, it stores the output data for later use
  3. Next, it creates initial values for all model parameters
  4. It then finds the optimal values for these parameters to best fit your data
  5. Finally, it calculates how well these parameters worked by computing the errors

Each step builds on the previous one to create a model that understands both:

  • How your target variable changes over time on its own
  • How your input variables influence your target variable

Exceptions

ArgumentException

Thrown when the input matrix rows don't match the output vector length.

Edit this page