Project a Table- or Feature-Level Covariate (generic)

Generic for projecting a table-level or feature-level covariate into the space of a fitted model, treating it as a supplementary variable without re-fitting the model.

Convenience wrapper for `project_covariate(..., side = "table")`.

Convenience wrapper for `project_covariate(..., side = "feature")`.

This function projects a table-level or feature-level covariate into the space of a fitted `covstatis` model, treating it as a supplementary variable without re-fitting the model.

Usage

project_covariate(x, y, side = c("table", "feature"), ...)

project_table_covariate(x, y, ...)

project_feature_covariate(x, y, ...)

# S3 method for class 'covstatis'
project_covariate(
  x,
  y,
  side = c("table", "feature"),
  what = NULL,
  scale = c("cosine", "beta"),
  ...
)

Arguments

x: A fitted model object (e.g., `covstatis`).
y: Numeric vector representing the covariate. Its length depends on `side`: one value per table/block for `side = "table"`, or one value per feature for `side = "feature"`.
side: Which side the covariate belongs to: `"table"` for one value per input table/block, or `"feature"` for one value per matrix feature.
...: other arguments passed to methods.
what: For `side = "table"`, `"dimension"` (default) returns cosine / β per compromise dimension and `"feature"` returns a feature-wise pattern. `"observation"` is accepted as a backwards-compatible alias for `"feature"`. For `side = "feature"`, only `"dimension"` is currently supported.
scale: `"cosine"` (−1…1) or `"beta"` (regression coeff.).

Value

The return value depends on the method, but is typically a projection of the covariate onto the model's components or a spatial pattern.

If `what = "dimension"`, a named numeric vector of length `ncomp(x)`. If `side = "table"` and `what = "feature"`, a `p × ncomp` matrix.

Details

The interpretation of the output depends on `side`: - **Table-side covariate**: `y` has length equal to the number of input tables/blocks. Dimension-wise output quantifies how strongly the covariate aligns with the RV/table-space axes. Feature-wise output is a weighted sum of partial factor scores and gives a feature pattern associated with the covariate. - **Feature-side covariate**: `y` has length equal to the matrix dimension (`p`). Dimension-wise output quantifies how strongly the covariate aligns with the compromise feature-space axes.

Examples

# Create a list of correlation matrices
Xs <- lapply(1:5, function(i) matrix(rnorm(10*10), 10, 10))
Xs <- lapply(Xs, cor)

# Apply COVSTATIS
res <- covstatis(Xs, ncomp=3)

# Table-side covariate: one value per table/block
y <- rnorm(length(Xs))

# Project the covariate to get dimension-wise coordinates
dim_cos <- project_table_covariate(res, y, what = "dimension", scale = "cosine")

# Project the covariate to get a feature-wise pattern
feature_beta <- project_table_covariate(res, y, what = "feature", scale = "beta")

# Feature-side covariate: one value per feature/row-column entity
z <- rnorm(nrow(Xs[[1]]))
feature_dim_cos <- project_feature_covariate(res, z, scale = "cosine")