Table of Contents

Class ARIMAXModel<T>

Namespace
AiDotNet.TimeSeries
Assembly
AiDotNet.dll

Implements an ARIMAX (AutoRegressive Integrated Moving Average with eXogenous variables) model for time series forecasting.

public class ARIMAXModel<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 type used for calculations (e.g., float, double, decimal).

Inheritance
ARIMAXModel<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

ARIMAX extends the ARIMA model by including external (exogenous) variables that might influence the time series. The model combines: - AR (AutoRegressive): Uses the dependent relationship between an observation and lagged observations - I (Integrated): Uses differencing to make the time series stationary - MA (Moving Average): Uses the dependency between an observation and residual errors - X (eXogenous): Incorporates external variables that may influence the time series

For Beginners: ARIMAX is an advanced technique for forecasting time series data (data collected over time like daily temperatures, stock prices, or monthly sales) that takes into account both the history of the series itself AND external factors that might influence it.

Think of it like this:

  • Basic forecasting might just look at past sales to predict future sales
  • ARIMAX also considers things like holidays, promotions, or economic indicators that might affect sales

The model has four components:

  1. AutoRegressive (AR): Uses past values of the series itself (like yesterday's temperature to predict today's)
  2. Integrated (I): Transforms the data by looking at differences between values to remove trends
  3. Moving Average (MA): Looks at past prediction errors to improve future predictions
  4. eXogenous (X): Includes external factors that might affect the series (like whether it's a holiday)

The "X" is what makes ARIMAX different from ARIMA - it can include information from outside the time series itself.

Constructors

ARIMAXModel(ARIMAXModelOptions<T>?)

Creates a new ARIMAX model with the specified options.

public ARIMAXModel(ARIMAXModelOptions<T>? options = null)

Parameters

options ARIMAXModelOptions<T>

Options for the ARIMAX model, including AR order, MA order, differencing order, and exogenous variables. If null, default options are used.

Remarks

For Beginners: This constructor creates a new ARIMAX model. You can customize the model by providing options:

  • AROrder: How many past values to consider (like using yesterday and the day before to predict today)
  • MAOrder: How many past prediction errors to consider
  • DifferenceOrder: How many times to difference the data to remove trends
  • ExogenousVariables: How many external factors to include in the model

If you don't provide options, default values will be used, but it's usually best to choose values that make sense for your specific data.

Methods

ApplyParameters(Vector<T>)

Applies the provided parameters to the model.

protected override void ApplyParameters(Vector<T> parameters)

Parameters

parameters Vector<T>

The vector of parameters to apply.

Remarks

For Beginners: This method updates all the numerical values that determine how the model behaves. It's like replacing all the settings that control how the model makes predictions.

Clone()

Creates a deep copy of the current model.

public override IFullModel<T, Matrix<T>, Vector<T>> Clone()

Returns

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

A new instance of the ARIMAX model with the same state and parameters.

Remarks

This method creates a complete copy of the model, including its configuration and trained parameters.

For Beginners: This method creates an exact duplicate of your trained model.

Unlike CreateInstance(), which creates a blank model with the same settings, Clone() creates a complete copy including:

  • The model configuration (AR order, MA order, etc.)
  • All trained coefficients (AR, MA, exogenous)
  • Differencing information and intercept value

This is useful for:

  • Creating a backup before experimenting with a model
  • Using the same trained model in multiple scenarios
  • Creating ensemble models that use variations of the same base model

CreateInstance()

Creates a new instance of the ARIMAX model.

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

Returns

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

A new ARIMAX model with the same options as this one.

Remarks

For Beginners: This method creates a blank copy of this ARIMAX model. It's used internally by methods like DeepCopy and Clone to create a new model with the same configuration but without copying the trained parameters.

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 private 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 all components that were saved during serialization: AR coefficients, MA coefficients, exogenous coefficients, differencing information, intercept value, and model options. This fully reconstructs the model exactly as it was when saved.

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>

Matrix of exogenous variables for testing.

yTest Vector<T>

Actual values for testing.

Returns

Dictionary<string, T>

A 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:

  • MSE (Mean Squared Error): Average of squared differences between predictions and actual values. Lower is better, but squares the errors, so large errors have a bigger impact.

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

  • MAE (Mean Absolute Error): Average of absolute differences between predictions and actual values. Easier to interpret than MSE and treats all sizes of errors equally.

  • MAPE (Mean Absolute Percentage Error): Average of percentage differences between predictions and actual values. Useful for understanding the relative size of errors compared to the actual values.

Lower values for all these metrics indicate better performance.

GetActiveFeatureIndices()

Gets the indices of exogenous features actively used by the model.

public override IEnumerable<int> GetActiveFeatureIndices()

Returns

IEnumerable<int>

A collection of indices representing the active features.

Remarks

For Beginners: This method tells you which external factors have the strongest influence on the model's predictions.

GetModelMetadata()

Gets metadata about the ARIMAX model.

public override ModelMetadata<T> GetModelMetadata()

Returns

ModelMetadata<T>

A ModelMetaData object containing information about the model.

Remarks

For Beginners: This method provides important information about the ARIMAX model that can help you understand its characteristics and behavior.

The metadata includes:

  • The type of model (ARIMAX)
  • The actual coefficients and parameters the model has learned
  • State information needed for predictions

This complete picture of the model is useful for analysis, debugging, and potentially transferring the model's knowledge to other systems.

IsFeatureUsed(int)

Determines if a specific exogenous feature is actively used by the model.

public override bool IsFeatureUsed(int featureIndex)

Parameters

featureIndex int

The index of the feature to check.

Returns

bool

True if the feature is actively used; otherwise, false.

Remarks

For Beginners: This method tells you whether a specific external factor has a meaningful influence on the model's predictions.

Predict(Matrix<T>)

Makes predictions using the trained ARIMAX model.

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

Parameters

xNew Matrix<T>

Matrix of exogenous variables for the periods to be predicted.

Returns

Vector<T>

A vector of predicted values.

Remarks

For Beginners: This method uses the trained model to forecast future values of your time series. The prediction process:

  1. Starts with the intercept (baseline value)
  2. Adds the effects of external factors (like holidays, promotions, etc.)
  3. Adds the effects of past observations (AR component)
  4. Adds the effects of past prediction errors (MA component)
  5. If differencing was used in training, "undoes" the differencing to get predictions in the original scale

The xNew parameter must contain the external factors for the future periods you want to predict. If you don't know these future external factors, you would need to predict them separately or make reasonable assumptions.

Predict(Tensor<T>)

Makes predictions using the trained ARIMAX model with tensor input.

public Tensor<T> Predict(Tensor<T> input)

Parameters

input Tensor<T>

Tensor containing exogenous variables for the periods to be predicted.

Returns

Tensor<T>

A tensor of predicted values.

Remarks

For Beginners: This overload allows the model to work with tensor data formats. It converts the tensor to a matrix and then uses the standard prediction method.

PredictSingle(Vector<T>)

Predicts a single value based on a single vector of exogenous variables.

public override T PredictSingle(Vector<T> input)

Parameters

input Vector<T>

Vector of exogenous variables for a single time point.

Returns

T

The predicted value for that time point.

Remarks

This method provides a convenient way to get a prediction for a single time point without having to create a matrix with a single row.

For Beginners: This is a shortcut for getting just one prediction.

Instead of providing a table of inputs for multiple time periods, you can provide just one set of external factors and get back a single prediction.

For example, if you want to predict tomorrow's sales based on tomorrow's weather, promotions, and other factors, this method lets you do that directly.

Under the hood, it:

  1. Takes your single set of external factors
  2. Creates a small table with just one row
  3. Gets a prediction using the main prediction engine
  4. Returns that single prediction to you

Reset()

Resets the model to its untrained state.

public override void Reset()

Remarks

This method clears all trained parameters, effectively resetting the model to its initial state.

For Beginners: This method erases all the learned patterns from your model.

After calling this method:

  • All coefficients are reset to zero
  • The intercept is reset to zero
  • The differencing information is cleared

The model behaves as if it was never trained, and you would need to train it again before making predictions. This is useful when you want to:

  • Experiment with different training data on the same model
  • Retrain a model from scratch with new parameters
  • Reset a model that might have been trained incorrectly

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 private 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 all essential components: AR coefficients, MA coefficients, exogenous coefficients, differencing information, intercept value, and model options. This allows the model to be fully reconstructed later.

Train(Tensor<T>, Tensor<T>)

Trains the ARIMAX model with tensor input data.

public void Train(Tensor<T> input, Tensor<T> expectedOutput)

Parameters

input Tensor<T>

Tensor containing exogenous variables.

expectedOutput Tensor<T>

Tensor containing time series values to model.

Remarks

For Beginners: This method allows the model to be trained with tensor data formats. It converts the tensors to matrix and vector formats and then uses the standard training method.

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

Implements the core training algorithm for the ARIMAX model.

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

Parameters

x Matrix<T>

Matrix of exogenous variables (external factors that may influence the time series).

y Vector<T>

Vector of time series values to be modeled and predicted.

Remarks

This method contains the implementation details of the training process, handling differencing, model fitting, and parameter updates.

For Beginners: This is the engine room of the training process.

While the public Train method provides a high-level interface, this method does the actual work:

  1. Differences the data (if needed) to remove trends
  2. Fits the ARIMAX model components (external factors, AR, and MA)
  3. Updates model parameters as needed

Think of it as the detailed step-by-step recipe that the chef follows when you order a meal.

Edit this page