Tensor PLS-like regression — tpls • tensorOmics

Developed @ Melbourne Integrative Genomics. Intuition: Fourier-based m transforms compact the data across time points, but preserve the information association for each sample and each feature. In doing so, pls works by calculating the singular vectors associated with a 'global' (across time points) top singular value, and deflating just that relevant face.

tpls(
  x,
  y,
  ncomp = NULL,
  m = NULL,
  minv = NULL,
  mode = "regression",
  center = TRUE,
  matrix_output = TRUE,
  transform_y = NULL,
  face_scaling = NULL,
  bpparam = NULL
)

Arguments

x: Tensor input.
y: Tensor input, or a vector / n x q matrix for a response fixed per subject (see transform_y).
ncomp: The estimated number of components. ncomp must be explicitly set as an integer in tpls.
m: A function which applies an orthogonal tensor tubal transform.
minv: The inverse of m.
mode: Currently supports tensor analogues of canonical ("canonical"), regression ("regression"), and svd ("tsvdm") PLS variants. Defaults to "regression".
center: If set to false, the data tensor will not be centralized into Mean Deviation Form (see Mor et al. 2022). By default, the mean horizontal slice of the input tensor(s) are subtracted, so that all of the horizontal slices sum to 0, analgous to centering matrix data.
matrix_output: Note: FALSE ONLY AFFECTS THE OUTPUT IN "tsvdm" MODE. TRUE by default. Collects the top singular vectors across the tensor, organized by the magnitude of the corresponding singular vector, and place them into the columns of a matrix. Corresponds to the 'matrix compression' type of scheme described in Mor et al. 2022.
transform_y: Whether to m-transform the response with x. NULL by default, which decides from the shape of y: a vector or an n x q matrix is a response fixed per subject, such as an endpoint measured once, and is not transformed, so that every face of x is compared with the response itself; an order-3 tensor is transformed. A response that is constant over time and transformed is non-zero on the first face only, which under the default DCT holds the subject time averages. An untransformed response is deflated on every face after each component. TRUE copies a subject-fixed response over time and transforms it; FALSE needs a response that is the same at every time point.
face_scaling: How faces compete when each component picks one. "frobenius" divides each face's score, the largest singular value of t(xhat_f) yhat_f, by the Frobenius norms of xhat_f and yhat_f, so that faces compete on a common scale. "none" compares the raw scores, which favours the face with most variance; under the default DCT that is face 1, which also holds the between-subject variation. It affects which face is chosen only. NULL by default: "frobenius" for an untransformed response, "none" otherwise.
bpparam: A BiocParallelParam-class object indicating the type of parallelisation. Does not have any effect if transform functions explicitly set using m, minv.

Value

A list containing:

ncomp: The number of components used.
x: The centered input tensor X.
y: The centered input tensor Y.
mode: The PLS mode used: "canonical", "regression", or "tsvdm".
transform_y: Whether the response was m-transformed.
face_scaling: How faces were compared: "frobenius" or "none".
x_loadings: Matrix of X loadings (p x ncomp), or loadings tensor if mode = "tsvdm" AND matrix_output = FALSE.
y_loadings: Matrix of Y loadings (q x ncomp), or loadings tensor if mode = "tsvdm" AND matrix_output = FALSE.
x_projected: Matrix of X projections (n x ncomp), or proections tensor when mode = "tsvdm" AND matrix_output = FALSE.
y_projected: Matrix of Y projections (n x ncomp), or proections tensor when mode = "tsvdm" AND matrix_output = FALSE.
features: Vector of selected feature indices per component (only when matrix_output = TRUE).
faces: Vector of selected tensor face indices per component (only when matrix_output = TRUE).
center: Whether x and y were centered.
mean_slice_x, mean_slice_y: The mean horizontal slices subtracted from x (p x t) and y (q x t), or NULL if they were not centered.
m, minv: The transform pair used.
x_reg_coefs: The X deflation coefficients of each component (p x ncomp), NULL in tsvdm mode.
y_reg_coefs: In regression mode, the coefficients of Y on the X variates of each component (q x ncomp), which deflate Y; NULL in canonical and tsvdm modes.

Author

Brendan Lu