Package 'dipca'

Compact DiCCA with AR/ARMA/ARIMA inner models (measurement-space update)

Description

Implements the measurement-space DiCCA alternating scheme with an inner AR/ARMA/ARIMA model fitted on each component. The deflation step follows Dong & Qin (2018): $X \leftarrow X - t p^\top$ with $p = X^\top t / (t^\top t)$.

Usage

arima_dicca(
  X,
  n_comp,
  burnin = 0,
  center = TRUE,
  scale = FALSE,
  inner = c("arma", "arima", "ar"),
  order_mode = c("select_once", "fixed", "auto_each"),
  max_iter = 200L,
  max_iter_one = 100L,
  tol = 1e-06,
  order = NULL,
  pmax = 5L,
  qmax = 5L,
  verbose = 1L,
  fit_every = Inf,
  experimental = FALSE
)

Arguments

X	numeric matrix (T x m), rows are time, columns variables.
n_comp	number of dynamic latent variables to extract.
burnin	integer lag order $s$ (>=1). Historically the compact routine used a burn-in; we treat this as the lag order for consistency with the main dicca() function.
center	logical; center columns before fitting.
scale	logical; scale to unit variance if TRUE.
inner	one of "ar", "arma", or "arima" (experimental; see experimental argument).
order_mode	how to handle ARIMA orders across iterations: "select_once" (default) selects once per component and reuses; "fixed" requires the order argument; "auto_each" re-selects at every iteration.
max_iter	integer maximum outer iterations for each component.
max_iter_one	retained for backwards compatibility; the effective iteration cap is min(max_iter, max_iter_one).
tol	numeric convergence tolerance on the objective.
order	optional list(p=, d=, q=) when order_mode = "fixed".
pmax, qmax	upper bounds when auto-selecting orders.
verbose	integer verbosity (>=0).
fit_every	integer; refit the inner model every fit_every iterations (default: Inf, fit only once).
experimental	logical; when TRUE enables the experimental inner = "arima" pathway, otherwise requesting "arima" will error unless the option options(dipca.experimental_arima = TRUE) has been set.

Value

a list with fields: W, P, T, models, info, R, method; with class 'dicca_model'.

---

Dynamic-Inner Canonical Correlation Analysis (DiCCA) Extract dynamic latent variables by maximizing correlation between each latent series and its AR(s) prediction (canonical correlation form). This follows Dong & Qin (2018 IFAC) iteration and deflation.

Description

Dynamic-Inner Canonical Correlation Analysis (DiCCA) Extract dynamic latent variables by maximizing correlation between each latent series and its AR(s) prediction (canonical correlation form). This follows Dong & Qin (2018 IFAC) iteration and deflation.

Usage

dicca(
  X,
  s,
  l,
  preproc = multivarious::center(),
  tol = 1e-07,
  max_iter = 1000,
  n_init = 4,
  verbose = 0,
  seed = NULL,
  inner = c("classic", "ar", "arma", "arima")
)

DiCCA(
  X,
  s,
  l,
  preproc = multivarious::center(),
  tol = 1e-07,
  max_iter = 1000,
  n_init = 4,
  verbose = 0,
  seed = NULL,
  inner = c("classic", "ar", "arma", "arima")
)

Arguments

X	numeric matrix (T x m), time by variables.
s	integer lag order (>=1).
l	integer number of components to extract.
preproc	a pre_processor object from the multivarious package. Default is center() which centers columns. Use prep(pass()) for no preprocessing.
tol	numeric outer tolerance (||w_{k+1}-w_k||_inf).
max_iter	integer max outer iterations per component.
n_init	integer random restarts per component; best objective kept.
verbose	integer verbosity (0=quiet).
seed	optional RNG seed.
inner	one of "classic" (DiCCA coordinate updates), or compact variants "ar", "arma", "arima" (the latter is experimental and requires options(dipca.experimental_arima = TRUE)) which dispatch to the compact ARIMA-DiCCA routine.

Details

One-component iteration: see DiCCA Eqs. (4)–(8): beta = (T_s^T T_s)^{-1} T_s^T t_{s+1}; beta <- beta / sqrt(t_{s+1}^T T_s beta); X_beta = sum_i beta_i X_{s+1-i}; w <- (X_{s+1}^T X_{s+1} + X_beta^T X_beta)^+ [X_{s+1}^T (T_s beta) + X_beta^T t_{s+1}], then normalize w. After each component, deflate X by X <- X - t p^T with p = X^T t / (t^T t). A joint VAR(s) is fit on the extracted score matrix for prediction utilities.

Value

A bi_projector object of class dicca with fields:

• v - weight matrix (m x l)

• s - score matrix (T x l)

• sdev - standard deviations of components

• preproc - fitted preprocessor

• loadings - loading matrix (m x l)

• betas - beta coefficients (l x s)

• theta - VAR coefficients ((l*s) x l) [classic only]

• R2 - R² values per component

• lag_order - lag parameter s

• obj_history - convergence history

• iters_per_component - iterations per component

• compact_models - per-component ARIMA models (compact variants only)

• compact_info - compact model metadata (compact variants only)

References

Dong & Qin (2018) Dynamic-Inner Canonical Correlation and Causality Analysis for High Dimensional Time Series Data, IFAC ADCHEM.

Examples

set.seed(1)
X <- matrix(rnorm(200), 100, 4)
fit <- dicca(X, s = 1, l = 2, inner = "classic", n_init = 1, max_iter = 100)
fit$R2

---

One-step-ahead prediction of DLVs (diagonal G(B))

Description

One-step-ahead prediction of DLVs (diagonal G(B))

Usage

dicca_predict_scores(model, scores)

Arguments

model	a fitted DiCCA model object with compact inner models
scores	numeric matrix of observed scores to predict from

Value

matrix of predicted scores

---

Transform new data to Di(L)V scores using a fitted compact DiCCA model

Description

Transform new data to Di(L)V scores using a fitted compact DiCCA model

Usage

dicca_scores(model, Xnew)

Arguments

model	a fitted DiCCA model object
Xnew	numeric matrix of new data to transform

Value

matrix of scores

---

Dynamic Inner PCA (DiPCA)

Description

Fit dynamic inner principal components using the fast coordinate-maximization algorithm with optional inner power iterations for the w-update.

Usage

dipca(
  X,
  s,
  l,
  preproc = multivarious::center(),
  tol = 1e-07,
  max_iter = 1000,
  n_init = 4,
  algorithm = c("I", "II"),
  inner_power = 50,
  inner_tol = 1e-08,
  verbose = 0,
  seed = NULL
)

DiPCA(
  X,
  s,
  l,
  preproc = multivarious::center(),
  tol = 1e-07,
  max_iter = 1000,
  n_init = 4,
  algorithm = c("I", "II"),
  inner_power = 50,
  inner_tol = 1e-08,
  verbose = 0,
  seed = NULL
)

dipca_fit(
  X,
  s,
  l,
  preproc = multivarious::center(),
  tol = 1e-07,
  max_iter = 1000,
  n_init = 4,
  algorithm = c("I", "II"),
  inner_power = 50,
  inner_tol = 1e-08,
  verbose = 0,
  seed = NULL
)

Arguments

X	numeric matrix of shape (T, m), time by variables.
s	integer, lag order (>=1).
l	integer, number of components to extract.
preproc	a pre_processor object from the multivarious package. Default is center() which centers columns. Use prep(pass()) for no preprocessing.
tol	numeric, outer stopping tolerance on the eigen residual $||d - \lambda w||_\infty$.
max_iter	integer, maximum outer iterations.
n_init	integer, random restarts per component.
algorithm	"I" (one power step) or "II" (inner power iterations).
inner_power	integer, max inner power iterations (algorithm "II").
inner_tol	numeric, tolerance for inner power iteration.
verbose	integer, verbosity (0=quiet).
seed	optional integer RNG seed for reproducibility.

Details

The implementation follows the DiPCA objective and iteration given in Dong & Qin (2018, Table 2; Eqs 8–18) and the coordinate-maximization interpretation and residual criterion $||d - \lambda w||_\infty$ in Shin et al. (2020). The code avoids forming $Y_i$ explicitly; all updates are realized via matvecs with lagged blocks $X_{s+1-i}$.

Value

A bi_projector object of class dipca with fields:

• v - weight matrix (m x l)

• s - score matrix (T x l)

• sdev - standard deviations of components

• preproc - fitted preprocessor

• loadings - loading matrix (m x l)

• betas - beta coefficients (l x s)

• theta - VAR coefficients ((l*s) x l)

• lag_order - lag parameter s

• obj_history - convergence history

• iters_per_component - iterations per component

Examples

set.seed(1)
X <- matrix(rnorm(200), 100, 4)
fit <- dipca(X, s = 1, l = 2, n_init = 1, max_iter = 100)
head(multivarious::scores(fit))

---

Dynamic-inner Partial Least Squares (DiPLS)

Description

Fit the Dynamic-inner PLS algorithm of Dong & Qin (2018) to jointly model input block $X_t$ and output block $Y_t$. The outer loop updates the dynamic weights $w$, $q$, and FIR coefficients $\beta$ following Appendix A of the paper, while the inner model is estimated either as a FIR filter (default) or an ARX refinement.

Usage

dipls(
  X,
  Y,
  n_comp,
  s,
  preproc_x = multivarious::center(),
  preproc_y = NULL,
  mode = c("fir", "arx"),
  max_iter = 200L,
  tol = 1e-07,
  verbose = 1L
)

Arguments

X	numeric matrix with T rows (time) and m columns (inputs).
Y	numeric matrix with T rows and p columns (outputs).
n_comp	integer number of dynamic latent components to extract.
s	non-negative integer lag order for the inner model.
preproc_x	a pre_processor object from the multivarious package for the X block. Default is center() which centers columns. Use prep(pass()) for no preprocessing.
preproc_y	a pre_processor object from the multivarious package for the Y block. If NULL (default), uses the same preprocessing as preproc_x.
mode	character, either "fir" for the basic DiPLS inner model or "arx" to augment with AR terms on $u$.
max_iter	integer, maximum outer iterations per component.
tol	numeric tolerance on the maximum change of $w$, $q$, and $\beta$ between outer iterations.
verbose	integer verbosity level (0 = quiet, 1 = per-component banner, >1 also logs iteration deltas).

Value

A cross_projector object of class dipls with fields:

• vx - X-block weight matrix (m x n_comp)

• vy - Y-block weight matrix (p x n_comp)

• preproc_x - fitted X-block preprocessor

• preproc_y - fitted Y-block preprocessor

• T - X-block score matrix (T x n_comp)

• U - Y-block score matrix (T x n_comp), first s rows are NA

• P - X-block loadings (m x n_comp)

• C - Y-block loadings (p x n_comp)

• inner - per-component inner model coefficients (list)

• R - X-block projection matrix

• lag_order - lag parameter s

• mode - inner model mode ("fir" or "arx")

• iterations - iteration counts per component

Examples

set.seed(1)
X <- matrix(rnorm(200), 100, 4)
Y <- matrix(rnorm(200), 100, 2)
fit <- dipls(X, Y, n_comp = 1, s = 1, mode = "fir", verbose = 0)
dim(predict(fit, X))

---

Project X to DiPLS scores

Description

Project X to DiPLS scores

Usage

dipls_scores(model, Xnew)

Arguments

model	fitted DiPLS object from dipls.
Xnew	numeric matrix with the same number of columns as the training X.

Value

Matrix of latent scores (rows correspond to observations).

---

Predict Method for DiCCA

Description

Temporal forecasting using the VAR model (classic) or per-component ARIMA models (compact).

Usage

## S3 method for class 'dicca'
predict(object, newdata = NULL, ...)

Arguments

object	A fitted dicca object (bi_projector with class "dicca")
newdata	New data matrix to predict from
...	Additional arguments (currently unused)

Details

This method projects new data to the latent space and applies the fitted temporal model (VAR for classic, ARIMA for compact variants).

Value

A list with components:

• scores - Observed latent scores

• scores_hat - Predicted latent scores

---

Predict Method for DiPCA

Description

Temporal forecasting using the VAR model fitted on latent scores.

Usage

## S3 method for class 'dipca'
predict(object, newdata, ...)

Arguments

object	A fitted dipca object (bi_projector with class "dipca")
newdata	New data matrix to predict from
...	Additional arguments (currently unused)

Details

This method projects new data to the latent space and applies the fitted VAR(s) model to generate one-step-ahead predictions. The first s time points have NA predictions since they require lagged values.

Value

A list with components:

• scores - Observed latent scores

• scores_hat - Predicted latent scores using VAR(s) model

---

Predict Y using a fitted DiPLS model

Description

Predict Y using a fitted DiPLS model

Usage

## S3 method for class 'dipls'
predict(object, newdata, ...)

Arguments

object	fitted "dipls" object.
newdata	matrix X or a list containing an element X.
...	unused.

Value

Matrix of one-step-ahead predictions for Y.

---

Residuals Method for DiCCA

Description

Compute temporal prediction residuals for DiCCA model.

Usage

## S3 method for class 'dicca'
residuals(object, newdata = NULL, ...)

Arguments

object	A fitted dicca object (bi_projector with class "dicca")
newdata	New data matrix (optional, uses fitted data if missing)
...	Additional arguments (currently unused)

Details

Computes both latent score prediction errors from the VAR/ARIMA model and data-space reconstruction errors (dynamic whitening filter output). The first s time points have NA residuals since predictions require lagged values.

Value

A list with components:

• v - Score-space residuals ($T_t - \hat{T}_t$)

• e_hat - Data-space reconstruction residuals ($X_t - \hat{X}_t$)

• scores - Observed latent scores

---

Residuals Method for DiPCA

Description

Compute temporal prediction residuals for DiPCA model.

Usage

## S3 method for class 'dipca'
residuals(object, newdata = NULL, ...)

Arguments

object	A fitted dipca object (bi_projector with class "dipca")
newdata	New data matrix (optional, uses fitted data if missing)
...	Additional arguments (currently unused)

Details

Computes both latent score prediction errors from the VAR model and data-space reconstruction errors. The first s time points have NA residuals since predictions require lagged values.

Value

A list with components:

• v - Score-space residuals ($T_t - \hat{T}_t$)

• e_hat - Data-space reconstruction residuals ($X_t - \hat{X}_t$)

• scores - Observed latent scores

---

Compute residuals for DiPLS model

Description

Compute residuals for DiPLS model

Usage

## S3 method for class 'dipls'
residuals(object, newdata = NULL, ...)

Arguments

object	fitted "dipls" object.
newdata	optional list with elements X and Y. If NULL, uses training data (if stored).
...	unused.

Value

Matrix of residuals (Y - Yhat).

---