Package {ARInfoLSTM}

Out-of-Sample Accuracy for AiL Forecasts

Description

Compares AiL out-of-sample forecasts against actual values that arrived after training. Returns RMSE, MAE, SMAPE, and MAPE.

Usage

AccuracyAiL(fit, actual, lambda = NULL, verbose = TRUE)

Arguments

Value

Data frame with columns: Lambda, h, RMSE, MAE, SMAPE, MAPE. Also prints a formatted accuracy table to the console. The data frame has a "comparison" attribute with step-by-step Actual vs Forecast vs Error columns.

Examples

y   <- cumsum(rnorm(60, 0.5, 2))
fit <- AiL(y, mode = "manual", lag = 3, arima_order = c(1,1,1),
           hidden_size = 4, num_layers = 1, lr = 0.01,
           epochs = 20, patience = 5,
           lambda_list = c(0.5), verbose = FALSE)

# Simulate actual future values
new_data <- cumsum(rnorm(12, 0.5, 2)) + tail(y, 1)

acc <- AccuracyAiL(fit, actual = new_data)
print(acc)

# Step-by-step comparison table
attr(acc, "comparison")

ARIMA-Informed LSTM (AiL)

Description

Trains an LSTM on the FULL dataset using the ARIMA-informed composite loss:

  Loss = (1-lambda) * MSE(y_hat, y) + lambda * MSE(y_hat, y_ARIMA)

Trains on ALL data — no train/test split. Use predictAiL() for out-of-sample forecasting. An internal 20 percent validation split handles early stopping.

Usage

AiL(
  data,
  mode = c("auto", "manual"),
  arima_order  = NULL,      # NULL = auto.arima | c(p,d,q) = manual
  lag,                      # COMPULSORY
  hidden_size = 32,
  num_layers = 1,
  lr = 0.001,
  dropout = 0.0,
  epochs = 500,
  patience = 30,
  tune_epochs = 50,
  batch_size = 16,
  lambda_list = seq(0.1, 0.9, 0.1),
  hidden_grid = c(8, 16, 24, 32, 40),
  layers_grid = c(1, 2),
  lr_grid = c(0.001, 0.003, 0.005),
  dropout_grid = c(0.0, 0.1, 0.2),
  verbose = TRUE,
  seed = 42L
)

Arguments

Value

S3 object of class "AiL" with elements:

results

Named list per lambda. Each contains: tr_rmse, tr_mae, tr_mape, tr_smape, tr_preds, tr_actuals, val_rmse, loss_hist, time, lambda, model. Best lambda selected by Training RMSE.

best_model

Complete summary of best lambda model containing: lambda, hyperparams, arima order, metrics (RMSE/MAE/MAPE/SMAPE), predictions (Actual vs Predicted data frame), loss_history, model object.

arima

ARIMA order and fitted values on full data.

best_hp

Best LSTM hyperparameters found.

tuning_log

Grid-search log (auto mode only).

meta

Settings: lag, lambda_list, mode, best_lam_nm, selection="Train RMSE".

data_info

data, N, scaler, last_seq_scaled, lag.

Examples

y <- cumsum(rnorm(60, 0.5, 2))

# Auto mode -- train on full data (small grid for a fast example)
fit <- AiL(y, mode = "auto", lag = 3,
           hidden_grid = c(4, 8), layers_grid = c(1L),
           lr_grid = c(0.01), dropout_grid = c(0.0),
           tune_epochs = 5, epochs = 20, patience = 5,
           lambda_list = c(0.5), verbose = FALSE)
print(fit)
summary(fit)

# Forecast 12 steps ahead (out-of-sample)
fc <- predictAiL(fit, h = 12)
print(fc)

# Plot: historical + forecast (single point, no CI)
plotAiL(fit, h = 12)

# Lambda RMSE bar chart
plotlambda(fit)

# Manual mode (skips grid search -- fastest option)
fit2 <- AiL(y, mode = "manual",
            lag         = 3,            # compulsory
            arima_order = c(1,1,1),     # manual ARIMA order
            hidden_size = 4, num_layers = 1,
            lr = 0.01, epochs = 20, patience = 5,
            verbose = FALSE)
predictAiL(fit2, h = 6)

# If actual new data arrives -- accuracy check
new_data <- rnorm(12)
AccuracyAiL(fit, actual = new_data)
plotAiL(fit, h = 12, actual = new_data)

Accuracy Table for AiL Model

Description

Accuracy Table for AiL Model

Usage

accuracy.AiL(x)

Arguments

Value

Data frame with columns: Model, Lambda, RMSE, MAE, MAPE, SMAPE.

Plot AiL Forecast

Description

Plots three things in one chart:

1. Actual full training data (dark line).

2. Model in-sample predictions on training data (blue line).

3. Out-of-sample h-step forecast (red solid line).

If actual future values are provided via actual, they are overlaid as a green line for direct comparison with the red forecast.

Usage

plotAiL(fit, h = 12, lambda = NULL, actual = NULL,
        newdata = NULL,n_hist = NULL)

Arguments

Value

A ggplot2 object (invisibly).

Examples

y   <- cumsum(rnorm(60, 0.5, 2))
fit <- AiL(y, mode = "manual", lag = 3, arima_order = c(1,1,1),
           hidden_size = 4, num_layers = 1, lr = 0.01,
           epochs = 20, patience = 5,
           lambda_list = c(0.5), verbose = FALSE)

# Forecast only
plotAiL(fit, h = 12)

# Show only last 50 historical points
plotAiL(fit, h = 12, n_hist = 50)

# With actual future values overlaid (green)
new_data <- cumsum(rnorm(12, 0.5, 2)) + tail(y, 1)
plotAiL(fit, h = 12, actual = new_data)

Plot Training RMSE Across All Lambda Values

Description

Bar chart showing Training RMSE for each lambda value tested. The best lambda (lowest Training RMSE) is highlighted in gold. A red dashed horizontal line marks the minimum Training RMSE. Best lambda is selected by Training RMSE (consistent with AiL()).

Usage

plotlambda(fit)

Arguments

Value

A ggplot2 object (invisibly).

Examples

y   <- cumsum(rnorm(60, 0.5, 2))
fit <- AiL(y, mode = "manual", lag = 3, arima_order = c(1,1,1),
           hidden_size = 4, num_layers = 1, lr = 0.01,
           epochs = 20, patience = 5,
           lambda_list = c(0.3, 0.7), verbose = FALSE)

plotlambda(fit)
# Gold bar  = best lambda (lowest Training RMSE)
# Red dashed = minimum Training RMSE line

Out-of-Sample Forecast from a Fitted AiL Model

Description

Forecasts h steps ahead using recursive one-step prediction.

Usage

predictAiL(fit, h = 1, lambda = NULL, newdata = NULL)

Arguments

Value

Data frame with columns:

h

Forecast horizon step (1, 2, ..., h).

time_idx

Time index (N + 1, N + 2, ..., N + h).

forecast

Point forecast (mean).

Examples

y   <- cumsum(rnorm(60, 0.5, 2))
fit <- AiL(y, mode = "manual", lag = 3, arima_order = c(1,1,1),
           hidden_size = 4, num_layers = 1, lr = 0.01,
           epochs = 20, patience = 5,
           lambda_list = c(0.3, 0.7), verbose = FALSE)

# Forecast 12 steps ahead with best lambda
fc <- predictAiL(fit, h = 12)
print(fc)

# Forecast with specific lambda
fc3 <- predictAiL(fit, h = 6, lambda = 0.3)

# Update starting sequence with new observations, then forecast
new_obs <- rnorm(5, mean = tail(y,1), sd = 2)
fc_new  <- predictAiL(fit, h = 12, newdata = new_obs)

Print method for AiL_forecast

Description

Print method for AiL_forecast

Usage

## S3 method for class 'AiL_forecast'
print(x, ...)

Arguments

Value

Invisibly returns x.