Class DynamicRegressionWithARIMAErrors<T>

Namespace

AiDotNet.TimeSeries

Assembly

AiDotNet.dll

Implements a Dynamic Regression model with ARIMA errors for time series forecasting.

public class DynamicRegressionWithARIMAErrors<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

object

TimeSeriesModelBase<T>

DynamicRegressionWithARIMAErrors<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>.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)

TimeSeriesModelBase<T>.SupportsJitCompilation

TimeSeriesModelBase<T>.ExportComputationGraph(List<ComputationNode<T>>)

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

This model combines regression analysis with ARIMA (AutoRegressive Integrated Moving Average) error modeling. It first models the relationship between the target variable and external predictors using regression, then applies ARIMA modeling to the residuals to capture temporal patterns in the error terms.

For Beginners: Dynamic Regression with ARIMA Errors is like having two powerful forecasting tools working together:

1. Regression Component: This part captures how external factors (like temperature, price changes, or marketing campaigns) affect what you're trying to predict. For example, if you're forecasting ice cream sales, this component would measure how much each degree of temperature increases sales.

2. ARIMA Error Component: After accounting for external factors, there are often still patterns in the data that the regression alone can't explain. The ARIMA component captures these patterns by looking at:

   • Past values (AR - AutoRegressive)
   • Trends removed through differencing (I - Integrated)
   • Past prediction errors (MA - Moving Average)

When combined, these components create a powerful forecasting model that can:

• Account for the impact of known external factors
• Capture complex temporal patterns in the data
• Handle both stationary and non-stationary time series
• Provide more accurate forecasts than either approach alone

This model is particularly useful when you have both:

• External variables that influence your target variable
• Temporal patterns that persist in the data after accounting for these external influences

Constructors

DynamicRegressionWithARIMAErrors(DynamicRegressionWithARIMAErrorsOptions<T>)

Creates a new Dynamic Regression with ARIMA Errors model with the specified options.

public DynamicRegressionWithARIMAErrors(DynamicRegressionWithARIMAErrorsOptions<T> options)

Parameters

options DynamicRegressionWithARIMAErrorsOptions<T>

Options for configuring the model, including AR order, MA order, differencing order, and external regressors.

Remarks

For Beginners: This constructor creates a new instance of the model with the specified settings.

The options include:

• 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
• ExternalRegressors: How many external variables to include in the model
• Regularization: What method to use to prevent the model from becoming too complex

These settings should be chosen based on your specific data and forecasting needs.

Methods

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 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 regression coefficients
• All trained AR and MA coefficients
• 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 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 model with the same configuration options.

Remarks

This method creates a new, uninitialized instance of the model with the same options.

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

Think of this like creating a new blank notebook with the same paper quality, size, and number of pages as another notebook, but without copying any of the written content.

This is used internally by the framework to create new model instances when needed, such as when cloning a model or creating ensemble models.

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 protected 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 essential components that were saved during serialization:

• Regression coefficients
• AR coefficients
• MA coefficients
• Differencing information
• Intercept value
• Model options

After deserialization, the model is ready to make predictions as if it had just been trained.

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 external regressors for testing.

yTest Vector<T>

Actual target values for testing.

Returns

Dictionary<string, T>

A dictionary of evaluation metrics (MSE, RMSE, MAE, MAPE).

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 squaring emphasizes large errors.

• RMSE (Root Mean Squared Error): Square root of MSE, which gives errors in the same units as your original data. For example, if forecasting sales 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 error sizes equally.

• MAPE (Mean Absolute Percentage Error): Average of percentage differences between predictions and actual values. Useful for understanding relative size of errors. For example, MAPE = 5% means predictions are off by 5% on average.

Lower values for all these metrics indicate better performance.

Forecast(Vector<T>, int, Matrix<T>)

Forecasts future values based on a history of time series data and exogenous variables.

public Vector<T> Forecast(Vector<T> history, int horizon, Matrix<T> exogenousVariables)

Parameters

history Vector<T>

The historical time series data.

horizon int

The number of future periods to predict.

exogenousVariables Matrix<T>

Matrix of external regressors for future periods.

Returns

Vector<T>

A vector of predicted values for future periods.

Remarks

This method generates forecasts for future time periods based on the trained model, historical data, and external variables.

For Beginners: This method predicts future values based on past data.

Given:

• A series of past observations (the "history")
• The number of future periods to predict (the "horizon")
• External factors that might affect predictions (exogenous variables)

This method:

1. Uses the regression component to capture the effects of external factors
2. Uses the ARIMA component to capture time-dependent patterns
3. Combines these components to generate comprehensive forecasts
4. If differencing was used, it properly undoes the differencing to get results in the original scale

For example, if you have sales data for Jan-Jun and want to predict Jul-Sep, this method will use both the external factors (like promotions, holidays) and the historical patterns to create accurate forecasts.

GetModelMetadata()

Gets metadata about the trained model.

public override ModelMetadata<T> GetModelMetadata()

Returns

ModelMetadata<T>

A ModelMetaData object containing information about the model.

Remarks

This method provides comprehensive information about the model, including its type, parameters, and configuration.

For Beginners: This method returns a complete description of your trained model.

The metadata includes:

• The type of model (Dynamic Regression with ARIMA Errors)
• The coefficients for external factors (regression component)
• The coefficients for time-dependent patterns (AR and MA components)
• The configuration options you specified when creating the model
• A serialized version of the entire model that can be saved

This is useful for:

• Understanding what patterns the model has learned
• Documenting how the model was configured
• Saving the model's state for later analysis
• Comparing different models to choose the best one

Predict(Matrix<T>)

Makes predictions using the trained model.

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

Parameters

xNew Matrix<T>

Matrix of external regressors for the periods to be predicted.

Returns

Vector<T>

Vector of predicted values.

Remarks

For Beginners: This method uses the trained model to forecast future values.

For each future time point:

1. It starts with the intercept (baseline value)
2. Adds the effects of external factors (regression component)
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, it "undoes" the differencing to get predictions in the original scale

The combination of regression and ARIMA components allows the model to make forecasts that account for both external influences and internal time-dependent patterns.

PredictSingle(Vector<T>)

Predicts a single value based on a single input vector of external regressors.

public override T PredictSingle(Vector<T> input)

Parameters

input Vector<T>

Vector of external regressors 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 promotions, weather forecast, and other factors, this method lets you do that directly.

Under the hood, it:

1. Takes your single set of inputs
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 regression coefficients are reset to zero
• All AR coefficients are reset to zero
• All MA coefficients are reset to zero
• The differencing information is cleared
• The intercept is reset to zero

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 protected 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 of the model:

• Regression coefficients
• AR coefficients
• MA coefficients
• Differencing information
• Intercept value
• Model options

This allows the model to be fully reconstructed later.

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

Implements the core training algorithm for the Dynamic Regression with ARIMA Errors model.

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

Parameters

x Matrix<T>

Feature matrix of external regressors.

y Vector<T>

Target vector of time series values.

Remarks

This method contains the implementation details of the training process, handling differencing, regression modeling, and ARIMA parameter estimation.

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. Performs differencing to remove trends (if specified)
2. Fits the regression model to capture external factor effects
3. Calculates residuals (what the regression couldn't explain)
4. Fits the ARIMA model to these residuals
5. Finalizes all model parameters

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