Package 'multivarious'

Description

add a pre-processing stage

Usage

add_node(x, step, ...)

Arguments

Value

a new pre-processing pipeline with the added step

Description

Add a pre-processing node to a pipeline

Usage

## S3 method for class 'prepper'
add_node(x, step, ...)

Arguments

Description

Apply a specified rotation to the fitted model

Usage

apply_rotation(x, rotation_matrix, ...)

Arguments

Value

A modified object with updated components and scores after applying the specified rotation.

Description

apply a pre-processing transform

Usage

apply_transform(x, X, colind, ...)

Arguments

Value

the transformed data

Description

A bi_projector offers a two-way mapping from samples (rows) to scores and from variables (columns) to components. Thus, one can project from D-dimensional input space to d-dimensional subspace. And one can project (project_vars) from n-dimensional variable space to the d-dimensional component space. The singular value decomposition is a canonical example of such a two-way mapping.

Usage

bi_projector(v, s, sdev, preproc = prep(pass()), classes = NULL, ...)

Arguments

Value

A bi_projector object

Examples

X <- matrix(rnorm(200), 10, 20)
svdfit <- svd(X)

p <- bi_projector(svdfit$v, s = svdfit$u %*% diag(svdfit$d), sdev=svdfit$d)

Description

This function combines a set of bi_projector fits into a single bi_projector instance. The new instance's weights and associated scores are obtained by concatenating the weights and scores of the input fits.

Usage

bi_projector_union(fits, outer_block_indices = NULL)

Arguments

Value

A new bi_projector instance with concatenated weights, scores, and other properties from the input bi_projector instances.

Examples

X1 <- matrix(rnorm(5*5), 5, 5)
X2 <- matrix(rnorm(5*5), 5, 5)

bpu <- bi_projector_union(list(pca(X1), pca(X2)))

Description

Creates a 2D biplot for a pca object, using ggplot2 and ggrepel to show both sample scores (observations) and variable loadings (arrows).

Usage

## S3 method for class 'pca'
biplot(
  x,
  y = NULL,
  dims = c(1, 2),
  scale_arrows = 2,
  alpha_points = 0.6,
  point_size = 2,
  point_labels = NULL,
  var_labels = NULL,
  arrow_color = "red",
  text_color = "red",
  repel_points = TRUE,
  repel_vars = FALSE,
  ...
)

Arguments

Details

This function constructs a scatterplot of the PCA scores (observations) on two chosen components and overlays arrows for the loadings (variables). The arrow length and direction indicate how each variable contributes to those principal components. You can control arrow scaling with scale_arrows.

If your pca object includes an $explained_variance field (e.g., proportion of variance per component), those values will appear in the axis labels. Otherwise, the axes are labeled simply as "PC1", "PC2", etc.

Note: If you do not have ggrepel installed, you can set repel_points=FALSE and repel_vars=FALSE, or install ggrepel.

Value

A ggplot object.

Examples

data(iris)
X <- as.matrix(iris[,1:4])
pca_res <- pca(X, ncomp=2)

# Enhanced biplot with repelled text
biplot(pca_res, repel_points=TRUE, repel_vars=TRUE)

Description

extract the list of indices associated with each block in a multiblock object

Usage

block_indices(x, ...)

Arguments

Value

a list of block indices

Description

Extract the Block Indices from a Multiblock Projector

Usage

## S3 method for class 'multiblock_projector'
block_indices(x, i, ...)

Arguments

Value

The list of block indices.

Description

extract the lengths of each block in a multiblock object

Usage

block_lengths(x)

Arguments

Value

the block lengths

Description

Perform bootstrap resampling on a multivariate model to estimate the variability of components and scores.

Usage

bootstrap(x, nboot, ...)

## S3 method for class 'plsc'
bootstrap(x, nboot = 500, ...)

Arguments

Value

A list containing the bootstrap resampled components and scores for the model.

Description

Performs bootstrap resampling for Principal Component Analysis (PCA) based on the method described by Fisher et al. (2016), optimized for high-dimensional data (p >> n). This version is specifically adapted to work with the output object generated by the provided pca function (which returns a bi_projector object of class 'pca').

Usage

bootstrap_pca(
  x,
  nboot = 100,
  k = NULL,
  parallel = FALSE,
  cores = NULL,
  seed = NULL,
  epsilon = 1e-15,
  ...
)

Arguments

Details

This function implements the fast bootstrap PCA algorithm proposed by Fisher et al. (2016), adapted for the output structure of the provided pca function. The pca function returns an object containing:

• v: Loadings (coefficients, p x k) - equivalent to V in SVD Y = U D V'. Note the transpose difference from prcomp.

• s: Scores (n x k) - calculated as U %*% D.

• sdev: Singular values (vector of length k) - equivalent to d.

• u: Left singular vectors (n x k).

The bootstrap algorithm works by resampling the subjects (rows) and recomputing the SVD on a low-dimensional representation. Specifically, it computes the SVD of the resampled matrix ⁠D U' P^b⁠, where ⁠Y = U D V'⁠ is the SVD of the original (pre-processed) data, and P^b is a resampling matrix operating on the subjects (columns of U').

The SVD of the resampled low-dimensional matrix is ⁠svd(D U' P^b) = A^b S^b (R^b)'⁠. The bootstrap principal components (loadings) are then calculated as ⁠V^b = V A^b⁠, and the bootstrap scores are ⁠Scores^b = R^b S^b⁠.

Z-scores are provided as mean / sd.

Important Note: The algorithm assumes the data Y used for the original SVD (⁠Y = U D V'⁠) was appropriately centered (or pre-processed according to x$preproc). The bootstrap samples are generated based on the components derived from this pre-processed data.

Value

A list object of class bootstrap_pca_result containing:

References

Fisher, Aaron, Brian Caffo, Brian Schwartz, and Vadim Zipunnikov. 2016. "Fast, Exact Bootstrap Principal Component Analysis for P > 1 Million." Journal of the American Statistical Association 111 (514): 846–60. doi:10.1080/01621459.2015.1062383.

Examples

# Simulate data (p=50, n=20)
set.seed(123)
p_dim <- 50
n_obs <- 20
Y_mat <- matrix(rnorm(p_dim * n_obs), nrow = p_dim, ncol = n_obs)
# Transpose for pca function input (n x p)
X_mat <- t(Y_mat)

# Perform PCA using the provided pca function
# Use center() pre-processing
pca_res <- pca(X_mat, ncomp = 5, preproc = center(), method = "fast")

# Run bootstrap on the pca result
boot_res <- bootstrap_pca(pca_res, nboot = 5, k = 5, seed = 456)

# Explore results
print(dim(boot_res$z_loadings)) # p x k Z-scores for loadings (coefficients)
print(dim(boot_res$z_scores))   # n x k Z-scores for scores

Description

Provides bootstrap ratios (mean / sd) for X and Y loadings to assess stability, mirroring common practice in Behavior PLSC.

Usage

bootstrap_plsc(
  x,
  X,
  Y,
  nboot = 500,
  comps = ncomp(x),
  seed = NULL,
  parallel = FALSE,
  epsilon = 1e-09,
  ...
)

Arguments

Description

Bootstrap stability summaries for an effect operator

Usage

## S3 method for class 'effect_operator'
bootstrap(
  x,
  nboot,
  resample = c("auto", "rows", "subject"),
  parallel = FALSE,
  seed = NULL,
  ...
)

Arguments

Value

A bootstrap result object with loading and singular-value summaries. n_failed records the number of resamples that produced a rank-deficient or otherwise unfittable design; failed draws are skipped.

Note

Loadings are currently aligned to the reference solution by a per-axis sign flip. When more than one effect axis is retained, axes can rotate between bootstrap draws and a Procrustes-based alignment (see PRD section 10) would give tighter stability summaries. Not implemented in this pass.

Description

Reference implementation of two-block canonical correlation analysis that returns a cross_projector. The within-block covariance matrices are ridge-regularized before whitening, which keeps the fit well-defined even when $p > n$ or either block is rank-deficient.

Usage

cca(
  X,
  Y,
  ncomp = NULL,
  preproc_x = center(),
  preproc_y = center(),
  lambda = 1e-04,
  lambda_x = lambda,
  lambda_y = lambda,
  tol = sqrt(.Machine$double.eps),
  ...
)

Arguments

Value

A cross_projector with class "cca" containing canonical coefficients (vx, vy), block scores (sx, sy), canonical correlations (cor), and the regularized block covariance matrices used to fit the model.

Examples

set.seed(1)
X <- matrix(rnorm(120), 30, 4)
Y <- matrix(rnorm(90), 30, 3)
fit <- cca(X, Y, ncomp = 2)
fit$cor

Description

remove mean of all columns in matrix

Usage

center(preproc = prepper(), cmeans = NULL)

Arguments

Value

a prepper list

Description

Create a classifier from a given model object (e.g., projector). This classifier can generate predictions for new data points.

Usage

classifier(x, colind, ...)

## S3 method for class 'projector'
classifier(
  x,
  colind = NULL,
  labels,
  new_data = NULL,
  knn = 1,
  global_scores = TRUE,
  ...
)

Arguments

Value

A classifier function that can be used to make predictions on new data points.

See Also

Other classifier: classifier.multiblock_biprojector(), rf_classifier.projector()

Examples

# Assume proj is a fitted projector object
# Assume lbls are labels and dat is new data
# classifier(proj, labels = lbls, new_data = dat, knn = 3)

Description

Create a k-NN classifier for a discriminant projector

Usage

## S3 method for class 'discriminant_projector'
classifier(x, colind = NULL, knn = 1, ...)

Arguments

Value

a classifier object

Examples

# Assume dp is a fitted discriminant_projector object
# classifier(dp, knn = 5) # Basic example

Description

Constructs a k-Nearest Neighbors (k-NN) classifier based on a fitted multiblock_biprojector model object. The classifier uses the projected scores as the feature space for k-NN.

Usage

## S3 method for class 'multiblock_biprojector'
classifier(
  x,
  colind = NULL,
  labels,
  new_data = NULL,
  block = NULL,
  global_scores = TRUE,
  knn = 1,
  ...
)

Arguments

Details

Users can specify whether to use the globally projected scores stored within the model (global_scores = TRUE) or to generate reference scores by projecting provided new_data (global_scores = FALSE). Partial projections based on colind or block can be used when global_scores = FALSE or when new_data is provided alongside colind/block. Prediction behavior is further controlled by arguments passed to predict.classifier.

Value

An object of class multiblock_classifier, which also inherits from classifier.

See Also

Other classifier: classifier(), rf_classifier.projector()

Description

Calculates the effective coefficient matrix that maps from the original input space (of the first projector) to the final output space (of the last projector). This is done by multiplying the coefficient matrices of all projectors in the sequence.

Usage

## S3 method for class 'composed_projector'
coef(object, ...)

Arguments

Value

A matrix representing the combined coefficients.

Description

Extract coefficients from a cross_projector object

Usage

## S3 method for class 'cross_projector'
coef(object, source = c("X", "Y"), ...)

Arguments

Value

the coefficients

Description

Extracts the components (loadings) for a given block or the entire projector.

Usage

## S3 method for class 'multiblock_projector'
coef(object, block, ...)

Arguments

Value

A matrix of loadings.

Description

normalize each column by a scale factor.

Usage

colscale(preproc = prepper(), type = c("unit", "z", "weights"), weights = NULL)

Arguments

Value

a prepper list

Description

Extract the component matrix of a fit.

Usage

components(x, ...)

Arguments

Value

the component matrix

Description

Creates a composed_partial_projector object that applies partial projections sequentially. If multiple projectors are composed, the column indices (colind) used at each stage must be considered.

This infix operator provides syntactic sugar for composing projectors sequentially. It is an alias for compose_partial_projector.

Usage

compose_partial_projector(...)

lhs %>>% rhs

Arguments

Value

A composed_partial_projector object.

A composed_partial_projector object representing the combined sequence.

Description

Combine two projector models into a single projector by sequentially applying the first projector and then the second projector.

Usage

compose_projector(x, y, ...)

Arguments

Value

A new projector object representing the composed projector, which can be used to project data onto the combined subspace.

Description

concatenate a sequence of pre-processors, each applied to a block of data.

Usage

concat_pre_processors(preprocs, block_indices)

Arguments

Value

a new pre_processor object that applies the correct transformations blockwise

Examples

p1 <- prep(center())
p2 <- prep(center())

x1 <- rbind(1:10, 2:11)
x2 <- rbind(1:10, 2:11)

p1a <- init_transform(p1,x1)
p2a <- init_transform(p2,x2)

clist <- concat_pre_processors(list(p1,p2), list(1:10, 11:20))
t1 <- apply_transform(clist, cbind(x1,x2))

t2 <- apply_transform(clist, cbind(x1,x2[,1:5]), colind=1:15)

Description

Contrastive PCA++ (cPCA++) Performs Contrastive PCA++ (cPCA++) to find directions that capture variation enriched in a "foreground" dataset relative to a "background" dataset. This implementation follows the cPCA++ approach which directly solves the generalized eigenvalue problem Rf v = lambda Rb v, where Rf and Rb are the covariance matrices of the foreground and background data, centered using the background mean.

Usage

cPCAplus(
  X_f,
  X_b,
  ncomp = NULL,
  center_background = TRUE,
  lambda = 0,
  method = c("geigen", "sdiag", "corpcor"),
  strategy = c("auto", "feature", "sample"),
  verbose = getOption("multivarious.verbose", TRUE),
  sample_rank = NULL,
  sample_oversample = 10L,
  ...
)

Arguments

Details

Preprocessing: Following the cPCA++ paper, if center_background = TRUE, both X_f and X_b are centered by subtracting the column means calculated only from the background data X_b. This is crucial for isolating variance specific to X_f.

Core Algorithm (methods "geigen", "sdiag", strategy="feature"):

1. Center X_f and X_b using the mean of X_b.

2. Compute potentially shrunk $p \times p$ covariance matrices Rf (from centered X_f) and Rb (from centered X_b) using corpcor::cov.shrink.

3. Solve the generalized eigenvalue problem ⁠Rf v = lambda Rb v⁠ for the top ncomp eigenvectors v using geigen::geneig. These eigenvectors are the contrastive principal components (loadings).

4. Compute scores by projecting the centered foreground data onto the eigenvectors: S = X_f_centered %*% v.

Core Algorithm (Large-D / Sample Space Strategy, strategy="sample"): When $p \gg n$, forming $p \times p$ matrices Rf and Rb is infeasible. The "sample" strategy follows cPCA++ §3.2:

1. Center X_f and X_b using the mean of X_b.

2. Compute the SVD of centered $X_b = Ub Sb Vb^T$ (using irlba for efficiency).

3. Project centered X_f into the background's principal subspace: Zf = X_f_centered %*% Vb.

4. Form small $r \times r$ matrices: Rf_small = cov(Zf) and Rb_small = (1/(n_b-1)) * Sb^2.

5. Solve the small $r \times r$ GEVD: ⁠Rf_small w = lambda Rb_small w⁠ using geigen::geneig.

6. Lift eigenvectors back to feature space: v = Vb %*% w.

7. Compute scores: S = X_f_centered %*% v.

Alternative Algorithm (method "corpcor"):

1. Center X_f and X_b using the mean of X_b.

2. Compute Rb and its inverse square root Rb_inv_sqrt.

3. Whiten the foreground data: X_f_whitened = X_f_centered %*% Rb_inv_sqrt.

4. Perform standard PCA (stats::prcomp) on X_f_whitened.

5. The returned v and s are the loadings and scores in the whitened space. The loadings are not the generalized eigenvectors v. A specific class corpcor_pca is added to signal this.

Value

A bi_projector-like object with classes c("cPCAplus", "<method_class>", "bi_projector") containing:

v

Loadings matrix (features x ncomp). Interpretation depends on method (see Details).

s

Scores matrix (samples_f x ncomp).

sdev

Vector (length ncomp). Standard deviations (sqrt of generalized eigenvalues for geigen methods, PCA std devs for corpcor).

values

Vector (length ncomp). Generalized eigenvalues (for geigen methods) or PCA eigenvalues (for corpcor).

strategy

The strategy used ("feature" or "sample") if method was not "corpcor".

preproc

The initialized preprocessor object used.

method

The computation method used.

ncomp

The number of components computed.

nfeatures

The number of features.

References

Abid, A., Zhang, M. J., Bagaria, V. K., & Zou, J. (2018). Exploring patterns enriched in a dataset with contrastive principal component analysis. Nature Communications, 9(1), 2134.

Salloum, R., & Kuo, C. C. J. (2022). cPCA++: An efficient method for contrastive feature learning. Pattern Recognition, 124, 108378.

Wu, M., Sun, Q., & Yang, Y. (2025). PCA++: How Uniformity Induces Robustness to Background Noise in Contrastive Learning. arXiv preprint arXiv:2511.12278.

Woller, J. P., Menrath, D., & Gharabaghi, A. (2025). Generalized contrastive PCA is equivalent to generalized eigendecomposition. PLOS Computational Biology, 21(10), e1013555.

Examples

# Simulate data where foreground has extra variance in first few dimensions
set.seed(123)
n_f <- 100
n_b <- 150
n_features <- 50

# Background: standard normal noise
X_b <- matrix(rnorm(n_b * n_features), nrow=n_b, ncol=n_features)
colnames(X_b) <- paste0("Feat_", 1:n_features)

# Foreground: background noise + extra variance in first 5 features
X_f_signal <- matrix(rnorm(n_f * 5, mean=0, sd=2), nrow=n_f, ncol=5)
X_f_noise <- matrix(rnorm(n_f * (n_features-5)), nrow=n_f, ncol=n_features-5)
X_f <- cbind(X_f_signal, X_f_noise) + matrix(rnorm(n_f * n_features), nrow=n_f, ncol=n_features)
colnames(X_f) <- paste0("Feat_", 1:n_features)
rownames(X_f) <- paste0("SampleF_", 1:n_f)

# Apply cPCA++ (requires geigen and corpcor packages)
# install.packages(c("geigen", "corpcor"))
if (requireNamespace("geigen", quietly = TRUE) && requireNamespace("corpcor", quietly = TRUE)) {
  # Assuming helper constructors like bi_projector are available
  # library(multivarious) 

  res_cpca_plus <- cPCAplus(X_f, X_b, ncomp = 5, method = "geigen")

  # Scores for the foreground data (samples x components)
  print(head(res_cpca_plus$s))

  # Loadings (contrastive directions) (features x components)
  print(head(res_cpca_plus$v))
}


# Plot example (slow graphics)
if (requireNamespace("geigen", quietly = TRUE) && requireNamespace("corpcor", quietly = TRUE)) {
  set.seed(123)
  X_b <- matrix(rnorm(150 * 50), nrow=150, ncol=50)
  X_f <- cbind(matrix(rnorm(100*5, sd=2), 100, 5), matrix(rnorm(100*45), 100, 45))
  res <- cPCAplus(X_f, X_b, ncomp = 5, method = "geigen")
  plot(res$s[, 1], res$s[, 2],
       xlab = "Contrastive Component 1", ylab = "Contrastive Component 2",
       main = "cPCA++ Scores")
}

Description

A projector that reduces two blocks of data, X and Y, yielding a pair of weights for each component. This structure can be used, for example, to store weights derived from canonical correlation analysis.

Usage

cross_projector(
  vx,
  vy,
  preproc_x = prep(pass()),
  preproc_y = prep(pass()),
  ...,
  classes = NULL
)

Arguments

Details

This class extends projector and therefore basic operations such as project, shape, reprocess, and coef work, but by default, it is assumed that the X block is primary. To access Y block operations, an additional argument source must be supplied to the relevant functions, e.g., coef(fit, source = "Y")

Value

a cross_projector object

Examples

# Create two scaled matrices X and Y
X <- scale(matrix(rnorm(10 * 5), 10, 5))
Y <- scale(matrix(rnorm(10 * 5), 10, 5))

# Perform canonical correlation analysis on X and Y
cres <- cancor(X, Y)
sx <- X %*% cres$xcoef
sy <- Y %*% cres$ycoef

# Create a cross_projector object using the canonical correlation analysis results
canfit <- cross_projector(cres$xcoef, cres$ycoef, cor = cres$cor,
                          sx = sx, sy = sy, classes = "cancor")

Description

Generic function for performing cross-validation on various objects or data. Specific methods should be implemented for different data types or model types.

Usage

cv(x, folds, ...)

Arguments

Details

The specific implementation details, default functions, and relevant arguments vary by method.

Bi-Projector Method (cv.bi_projector): Relevant arguments: x, folds, max_comp, fit_fun, measure, measure_fun, return_models, ....

This method performs cross-validation specifically for bi_projector models (or models intended to be used like them, typically from unsupervised methods like PCA or SVD). For each fold, it fits a single model using the training data with the maximum number of components specified (max_comp). It then iterates from 1 to max_comp components:

1. It truncates the full model to k components using truncate(). (Requires a truncate method for the fitted model class).

2. It reconstructs the held-out test data using the k-component truncated model via reconstruct_new().

3. It calculates reconstruction performance metrics (e.g., MSE, R2) by comparing the original test data to the reconstruction using the measure argument or a custom measure_fun.

The fit_fun must accept an argument ncomp. Additional arguments in ... are passed to fit_fun and measure_fun.

The return value is a cv_fit object (a list with class cv_fit), where the $results element is a tibble. Each row corresponds to a fold, containing the fold index (fold) and a nested tibble (component_metrics). The component_metrics tibble has rows for each component evaluated (1 to max_comp) and columns for the component index (comp) plus all calculated metrics (e.g., mse, r2, mae) or error messages (comp_error). If return_models=TRUE, the full model fitted on the training data for each fold is included in a list column model_full.

Value

The structure of the return value depends on the specific S3 method. Typically, it will be an object containing the results of the cross-validation, such as performance metrics per fold or aggregated metrics.

See Also

cv_generic

Description

For each fold (train/test indices):

1. Subset data[train, ]

2. Fit a model with .fit_fun(train_data, ...)

3. Evaluate with .measure_fun(model, test_data, ...)

Usage

cv_generic(
  data,
  folds,
  .fit_fun,
  .measure_fun,
  fit_args = list(),
  measure_args = list(),
  backend = c("serial", "future"),
  ...
)

Arguments

Value

A tibble with columns:

Description

A discriminant_projector is an instance that extends bi_projector with a projection that maximizes class separation. This can be useful for dimensionality reduction techniques that take class labels into account, such as Linear Discriminant Analysis (LDA).

Usage

discriminant_projector(
  v,
  s,
  sdev,
  preproc = prep(pass()),
  labels,
  classes = NULL,
  ...
)

Arguments

Value

A discriminant_projector object.

See Also

bi_projector

Examples

# Simulate data and labels
set.seed(123)
X <- matrix(rnorm(100 * 10), 100, 10)
labels <- factor(rep(1:2, each = 50))

# Perform LDA and create a discriminant projector
lda_fit <- MASS::lda(X, labels)

dp <- discriminant_projector(lda_fit$scaling, X %*% lda_fit$scaling, sdev = lda_fit$svd, 
labels = labels)

Description

Extract a named effect from a fitted model

Usage

effect(x, term, ...)

Arguments

Value

An effect object, typically an effect_operator.

Description

Construct an effect operator

Usage

effect_operator(v, s, sdev, preproc = fit(pass(), matrix(0, 1, nrow(v))), ...)

Arguments

Value

An effect_operator.

Description

Calculate the importance of features in a model

Usage

feature_importance(x, ...)

Arguments

Value

the feature importance scores

Description

Estimates the importance of features or blocks of features for the classification performance using either a "marginal" (leave-one-block-out) or "standalone" (use-only-one-block) approach.

Usage

## S3 method for class 'classifier'
feature_importance(
  x,
  new_data,
  true_labels,
  ncomp = NULL,
  blocks = NULL,
  metric = c("cosine", "euclidean", "ejaccard"),
  fun = rank_score,
  fun_direction = c("lower_is_better", "higher_is_better"),
  approach = c("marginal", "standalone"),
  ...
)

Arguments

Details

Importance is measured by the change in a performance metric (fun) when features are removed (marginal) or used exclusively (standalone).

Value

A data.frame with columns block (character representation of feature indices in the block) and importance (numeric importance score). Higher importance values generally indicate more influential blocks, considering fun_direction.

See Also

rank_score, topk

Examples

# Assume clf is a fitted classifier object, dat is new data, true_lbls are correct labels for dat
# Assume blocks_list defines feature groups e.g., list(1:5, 6:10)
# feature_importance(clf, new_data = dat, true_labels = true_lbls, blocks = blocks_list)

Description

Learn preprocessing parameters from training data. This function fits the preprocessing pipeline to the provided data matrix, learning parameters such as means, standard deviations, or other transformation parameters.

Usage

fit(object, X, ...)

Arguments

Value

A fitted preprocessing object that can be used with transform() and inverse_transform()

See Also

fit_transform(), transform(), inverse_transform()

Examples

# Fit a centering preprocessor
X <- matrix(rnorm(100), 10, 10)
preproc <- center()
fitted_preproc <- fit(preproc, X)

# Transform new data
X_new <- matrix(rnorm(50), 5, 10)
X_transformed <- transform(fitted_preproc, X_new)

Description

Convenience function that fits a preprocessing pipeline to data and immediately applies the transformation. This is equivalent to calling fit() followed by transform() but is more efficient and convenient.

Usage

fit_transform(object, X, ...)

Arguments

Value

A list with two elements: preproc (the fitted preprocessor) and transformed (the transformed data)

See Also

fit(), transform(), inverse_transform()

Examples

# Fit and transform in one step
X <- matrix(rnorm(100), 10, 10)
preproc <- center()
result <- fit_transform(preproc, X)
fitted_preproc <- result$preproc
X_transformed <- result$transformed

Description

Get a fresh pre-processing node cleared of any cached data

Usage

fresh(x, ...)

Arguments

Value

a fresh pre-processing pipeline

Description

Computes the generalized eigenvalues and eigenvectors for the problem: A x = lambda B x. Supports multiple dense and iterative solvers with a unified eigenpair selection interface.

Usage

geneig(
  A = NULL,
  B = NULL,
  ncomp = 2,
  preproc = NULL,
  method = c("robust", "sdiag", "geigen", "rspectra", "subspace"),
  which = "LA",
  ...
)

Arguments

Value

A projector object with generalized eigenvectors and eigenvalues.

References

Golub, G. H. & Van Loan, C. F. (2013) Matrix Computations, 4th ed., Section 8.7 – textbook derivation for the "robust" (Cholesky) and "sdiag" (spectral) transforms.

Moler, C. & Stewart, G. (1973) "An Algorithm for Generalized Matrix Eigenvalue Problems". SIAM J. Numer. Anal., 10 (2): 241-256 – the QZ algorithm behind the geigen backend.

See also the geigen (CRAN) documentation.

See Also

projector for the base class structure.

Examples

# Simulate two matrices
set.seed(123)
A <- matrix(rnorm(50 * 50), 50, 50)
B <- matrix(rnorm(50 * 50), 50, 50)
A <- A %*% t(A) # Make A symmetric
B <- B %*% t(B) + diag(50) * 0.1 # Make B symmetric positive definite

# Solve generalized eigenvalue problem
result <- geneig(A = A, B = B, ncomp = 3)

Description

This function computes group means for each factor level of Y in the provided data matrix X.

Usage

group_means(Y, X)

Arguments

Value

a matrix with row names corresponding to factor levels of Y and column-wise means for each factor level

Examples

# Example data
X <- matrix(rnorm(50), 10, 5)
Y <- factor(rep(1:2, each = 5))

# Compute group means
gm <- group_means(Y, X)

Description

Identity basis specification

Usage

identity_basis()

Value

A basis specification for the unregularized feature space.

Description

Return the inverse projection matrix, which can be used to map back to data space. If the component matrix is orthogonal, then the inverse projection is the transpose of the component matrix.

Usage

inverse_projection(x, ...)

## S3 method for class 'projector'
inverse_projection(x, ...)

Arguments

Value

The inverse projection matrix.

See Also

project for projecting data onto the subspace.

Description

Calculates the pseudo-inverse of the composed projector, mapping from the final output space back towards the original input space. This is computed by multiplying the pseudo-inverses of the individual projector stages in reverse order: ⁠V_k+ %*% ... %*% V_2+ %*% V_1+⁠.

Usage

## S3 method for class 'composed_projector'
inverse_projection(x, ...)

Arguments

Details

Requires that each stage implements the inverse_projection method.

Value

A matrix representing the combined pseudo-inverse.

Description

This function obtains the matrix that maps factor scores in the latent space back into the original domain (X or Y). By default, we assume v_domain is not necessarily orthonormal or invertible, so we use a pseudoinverse approach (e.g. MASS::ginv).

Usage

## S3 method for class 'cross_projector'
inverse_projection(x, domain = c("X", "Y"), ...)

Arguments

Value

A matrix that, when multiplied by the factor scores, yields the reconstruction in the specified domain's original space.

Examples

# Suppose 'cp' is a cross_projector object. If we want the
# inverse for the Y domain:
#   inv_mat <- inverse_projection(cp, domain="Y")
# Then reconstruct:  Yhat <- Fscores %*% inv_mat

Description

Reverse the preprocessing transformation, converting transformed data back to the original scale. The preprocessing object must have been fitted before calling this function.

Usage

inverse_transform(object, X, ...)

Arguments

Value

The data matrix in original scale

See Also

fit(), fit_transform(), transform()

Examples

# Inverse transform data back to original scale
X <- matrix(rnorm(100), 10, 10)
preproc <- center()
fitted_preproc <- fit(preproc, X)
X_transformed <- transform(fitted_preproc, X)
X_reconstructed <- inverse_transform(fitted_preproc, X_transformed)

# X and X_reconstructed should be approximately equal
all.equal(X, X_reconstructed)

Description

test whether components are orthogonal

Usage

is_orthogonal(x, tol = 1e-06)

Arguments

Value

a logical value indicating whether the transformation is orthogonal

Description

We test if v^T * v = I (when rows >= cols) or v * v^T = I (when cols > rows).

Usage

## S3 method for class 'projector'
is_orthogonal(x, tol = 1e-06)

Arguments

Description

We measure how well the model can transfer from X->Y or Y->X, e.g. "x2y.mse".

Usage

measure_interblock_transfer_error(Xtrue, Ytrue, model, metrics = c("x2y.mse"))

Arguments

Details

The metric names are of the form "x2y.mse", "x2y.rmse", "y2x.r2", etc.

Value

A 1-row tibble with columns for each requested metric

Description

Given two numeric matrices Xtrue and Xrec, compute:

• MSE ("mse")

• RMSE ("rmse")

• R^2 ("r2")

• MAE ("mae")

Usage

measure_reconstruction_error(
  Xtrue,
  Xrec,
  metrics = c("mse", "rmse", "r2"),
  by_column = FALSE
)

Arguments

Value

A one-row tibble with columns matching metrics.

Description

Fit the row-side design geometry for operator-valued ANOVA. Supports fixed-effect designs (random = NULL) and grouped random-effects designs with a single grouping variable (random intercept and optional random slopes, shared-Omega across response features).

Usage

mixed_regress(
  Y,
  design = NULL,
  fixed,
  random = NULL,
  basis = identity_basis(),
  preproc = center(),
  term_scopes = NULL,
  exchangeability = NULL,
  ...
)

Arguments

Value

A mixed_fit object.

Description

Constructs a multiblock bi-projector using the given component matrix (v), score matrix (s), singular values (sdev), a preprocessing function, and a list of block indices. This allows for two-way mapping with multiblock data.

Usage

multiblock_biprojector(
  v,
  s,
  sdev,
  preproc = prep(pass()),
  ...,
  block_indices,
  classes = NULL
)

Arguments

Value

A multiblock_biprojector object.

See Also

bi_projector, multiblock_projector

Description

Constructs a multiblock projector using the given component matrix (v), a preprocessing function, and a list of block indices. This allows for the projection of multiblock data, where each block represents a different set of variables or features.

Usage

multiblock_projector(
  v,
  preproc = prep(pass()),
  ...,
  block_indices,
  classes = NULL
)

Arguments

Value

A multiblock_projector object.

See Also

projector

Examples

# Generate some example data
X1 <- matrix(rnorm(10 * 5), 10, 5)
X2 <- matrix(rnorm(10 * 5), 10, 5)
X <- cbind(X1, X2)

# Compute PCA on the combined data
pc <- pca(X, ncomp = 8)

# Create a multiblock projector using PCA components and block indices
mb_proj <- multiblock_projector(pc$v, block_indices = list(1:5, 6:10))

# Project multiblock data using the multiblock projector
mb_scores <- project(mb_proj, X)

Description

The number of data blocks in a multiblock element

Usage

nblocks(x)

Arguments

Value

the number of blocks

Description

This function returns the total number of components in the fitted model.

Usage

ncomp(x)

Arguments

Value

The number of components in the fitted model.

Examples

# Example using the svd_wrapper function
data(iris)
X <- as.matrix(iris[, 1:4])
fit <- svd_wrapper(X, ncomp = 3, preproc = center(), method = "base")
ncomp(fit) # Should return 3

Description

Approximate the eigen-decomposition of a large kernel matrix K using either the standard Nyström method (Williams & Seeger, 2001) or the Double Nyström method (Lim et al., 2015, Algorithm 3).

Usage

nystrom_approx(
  X,
  kernel_func = NULL,
  ncomp = NULL,
  landmarks = NULL,
  nlandmarks = 10,
  preproc = pass(),
  method = c("standard", "double"),
  center = FALSE,
  l = NULL,
  use_RSpectra = TRUE,
  ...
)

Arguments

Details

The Double Nyström method introduces an intermediate step that reduces the size of the decomposition problem, potentially improving efficiency and scalability.

Kernel Centering: Standard Kernel PCA requires the kernel matrix K to be centered in the feature space (Schölkopf et al., 1998). This implementation currently does not perform kernel centering by default (center=FALSE) due to computational complexity. Consequently, with non-linear kernels, the results approximate the eigen-decomposition of the uncentered kernel matrix, and are not strictly equivalent to Kernel PCA. If using a linear kernel, centering the input data X (e.g., using preproc=prep(center())) yields results equivalent to standard PCA, which is often sufficient.

Standard Nyström: Uses the method from Williams & Seeger (2001), including the sqrt(m/N) scaling for eigenvectors and N/m for eigenvalues (m landmarks, N samples).

Double Nyström: Implements Algorithm 3 from Lim et al. (2015).

Value

A bi_projector object with class "nystrom_approx" and additional fields:

v

The eigenvectors (N x ncomp) approximating the kernel eigenbasis.

s

The scores (N x ncomp) = v * diag(sdev), analogous to principal component scores.

sdev

The square roots of the eigenvalues.

preproc

The pre-processing pipeline used.

meta

A list containing parameters and intermediate results used (method, landmarks, kernel_func, etc.).

References

Schölkopf, B., Smola, A., & Müller, K. R. (1998). Nonlinear component analysis as a kernel eigenvalue problem. Neural computation, 10(5), 1299-1319.

Williams, C. K. I., & Seeger, M. (2001). Using the Nyström Method to Speed Up Kernel Machines. In Advances in Neural Information Processing Systems 13 (pp. 682-688).

Lim, D., Jin, R., & Zhang, L. (2015). An Efficient and Accurate Nystrom Scheme for Large-Scale Data Sets. Proceedings of the Twenty-Ninth AAAI Conference on Artificial Intelligence (pp. 2765-2771).

Examples

set.seed(123)
# Smaller example matrix
X <- matrix(rnorm(1000*300), 1000, 300)

# Standard Nyström
res_std <- nystrom_approx(X, ncomp=5, nlandmarks=50, method="standard")
print(res_std)

# Double Nyström
res_db <- nystrom_approx(X, ncomp=5, nlandmarks=50, method="double", l=20)
print(res_db)

# Projection (using standard result as example)
scores_new <- project(res_std, X[1:10,])
head(scores_new)

Description

Compute the inverse projection of a columnwise subset of the component matrix (e.g., a sub-block). Even when the full component matrix is orthogonal, there is no guarantee that the partial component matrix is orthogonal.

Usage

partial_inverse_projection(x, colind, ...)

Arguments

Value

A matrix representing the partial inverse projection.

Description

This function obtains the "inverse" mapping for a columnwise subset of the loading matrix in the specified domain. In practice, if v_mat is not orthonormal or not square, we use a pseudoinverse approach (via MASS::ginv).

Usage

## S3 method for class 'cross_projector'
partial_inverse_projection(x, colind, domain = c("X", "Y"), ...)

Arguments

Details

By default, this is a minimal-norm solution for partial columns of v_mat. If you need a different approach (e.g., ridge, direct solve, etc.), you can override this method in your specific class or code.

Value

A matrix of shape (length(colind) x p_block) that, when multiplied by factor scores restricted to colind columns, yields an (n x p_block) reconstruction in the original domain block.

Examples

# Suppose 'cp' is a cross_projector, and we want only columns 1:3 of
# the Y block factors. Then:
#   inv_mat_sub <- partial_inverse_projection(cp, colind=1:3, domain="Y")
# The shape will be (3 x pY), so factor_scores_sub (n x 3) %*% inv_mat_sub => (n x pY).

Description

This function computes a sub-block inversion of the regression coefficients, allowing you to focus on only certain columns (e.g. partial factors). If your coefficient matrix is not orthonormal or is not square, we use a pseudoinverse approach (via corpcor::pseudoinverse) to find a minimal-norm solution.

Usage

## S3 method for class 'regress'
partial_inverse_projection(x, colind, ...)

Arguments

Value

A matrix of shape (length(colind) x nrow(x$coefficients)). When multiplied by partial factor scores (n x length(colind)), it yields an (n x nrow(x$coefficients)) reconstruction in the original domain.

Description

Project a selected subset of column indices (colind) of new_data onto the subspace defined by the model x. Optionally do a ridge-regularized least-squares solve if columns are non-orthonormal.

Usage

partial_project(
  x,
  new_data,
  colind,
  least_squares = FALSE,
  lambda = 1e-06,
  ...
)

Arguments

Value

A numeric matrix (n x d) of factor scores in the model's subspace, for those columns only.

Description

Applies partial_project() through each projector in the composition. If colind is a single vector, it applies to the first projector only. Subsequent projectors apply full columns. If colind is a list, each element specifies the colind for the corresponding projector in the chain.

Usage

## S3 method for class 'composed_partial_projector'
partial_project(x, new_data, colind = NULL, ...)

Arguments

Value

The partially projected data after all projectors are applied.

Description

Projects new data from either the X or Y domain onto the latent subspace, considering only a specified subset of original features (colind).

Usage

## S3 method for class 'cross_projector'
partial_project(
  x,
  new_data,
  colind,
  least_squares = FALSE,
  lambda = 1e-06,
  source = c("X", "Y"),
  ...
)

Arguments

Value

A numeric matrix (n x d) of factor scores in the latent subspace.

Description

Create a new projector instance restricted to a subset of input columns. This function allows for the generation of a new projection object that focuses only on the specified columns, enabling the projection of data using a limited set of variables.

Usage

partial_projector(x, colind, ...)

Arguments

Value

A new projector instance, with the same class as the original object, that is restricted to the specified subset of input columns

See Also

bi_projector for an example of a class that implements a partial_projector method

Examples

# Example with the bi_projector class
X <- matrix(rnorm(10*20), 10, 20)
svdfit <- svd(X)
p <- bi_projector(svdfit$v, s = svdfit$u %*% diag(svdfit$d), sdev=svdfit$d)

# Create a partial projector using only the first 10 variables
colind <- 1:10
partial_p <- partial_projector(p, colind)

Description

pass simply passes its data through the chain

Usage

pass(preproc = prepper())

Arguments

Value

a prepper list

Description

Compute the directions of maximal variance in a data matrix using the Singular Value Decomposition (SVD).

Usage

pca(
  X,
  ncomp = min(dim(X)),
  preproc = center(),
  method = c("fast", "base", "irlba", "propack", "rsvd", "svds"),
  ...
)

Arguments

Value

A bi_projector object containing the PCA results.

See Also

svd_wrapper for details on SVD methods.

Examples

data(iris)
X <- as.matrix(iris[, 1:4])
res <- pca(X, ncomp = 4)
tres <- truncate(res, 3)

Description

Calculates Hotelling T^2 (score distance) and Q-residual (orthogonal distance) for each observation, given a chosen number of components.

Usage

pca_outliers(x, X, ncomp, cutoff = FALSE)

Arguments

Value

A data frame with columns T2 and Q, and optionally an outlier flag.

Description

Estimate confidence intervals for model parameters using permutation testing.

Usage

perm_ci(x, X, nperm, ...)

## S3 method for class 'pca'
perm_ci(x, X, nperm = 100, k = 4, distr = "gamma", parallel = FALSE, ...)

Arguments

Value

A list containing the estimated lower and upper bounds of the confidence intervals for model parameters.

Description

This generic function implements a permutation-based test to assess the significance of components or statistics in a fitted model. The actual procedure depends on the method defined for the specific model class. Typical usage:

Arguments

Details

1. Shuffle or permute the data in a way that breaks the structure of interest (e.g., shuffle labels for supervised methods, shuffle columns/rows for unsupervised).

2. Re-fit or re-project the model on the permuted data. Depending on the class, this can be done via a fit_fun or a class-specific approach.

3. Measure the statistic of interest (e.g., variance explained, classification accuracy, canonical correlation).

4. Compare the distribution of permuted statistics to the observed statistic to compute an empirical p-value.

S3 methods define the specific defaults and required signatures for the functions involved in shuffling, fitting, and measuring.

This function provides a framework for permutation testing in various multivariate models. The specific implementation details, default functions, and relevant arguments vary by method.

PCA Method (perm_test.pca): Relevant arguments: X, nperm, measure_fun, shuffle_fun, stepwise, parallel, alternative, alpha, comps, use_svd_solver, .... Assesses significance of variance explained by each PC (Vitale et al., 2017). Default statistic: F_a. Default shuffle: column-wise. Default uses P3 projection and sequential stopping with alpha.

Cross Projector Method (perm_test.cross_projector): Relevant arguments: X, Y, nperm, measure_fun, shuffle_fun, fit_fun, parallel, alternative, .... Tests the X-Y relationship. Default statistic: x2y.mse. Default shuffle: rows of Y. Default fit: stats::cancor.

Discriminant Projector Method (perm_test.discriminant_projector): Relevant arguments: X, nperm, measure_fun, shuffle_fun, fit_fun, predict_method, parallel, alternative, .... Tests class separation. Default statistic: prediction accuracy. Default shuffle: labels. Default fit: MASS::lda.

Multiblock Bi-Projector Method (perm_test.multiblock_biprojector): Relevant arguments: Xlist (optional), nperm, shuffle_fun, parallel, alternative, alpha, comps, use_rspectra, .... Tests consensus using fixed internal statistic (eigenvalue) on scores for each component. The statistic is the leading eigenvalue of the covariance matrix of block scores for a given component (T^T, where T columns are scores of block b on component k). By default, it shuffles rows within each block independently (either from Xlist if provided via ..., or using the internally stored scores). It performs sequential testing for components specified by comps using the stopping rule defined by alpha (both passed via ...).

Multiblock Projector Method (perm_test.multiblock_projector): Relevant arguments: Xlist (required), nperm, measure_fun, shuffle_fun, parallel, alternative, alpha, comps, .... Tests consensus using measure_fun (default: mean abs corr) on scores projected from Xlist using the original model x. Does not refit.

Value

The structure of the return value depends on the method:

cross_projector and discriminant_projector:

Returns an object of class perm_test, a list containing: statistic, perm_values, p.value, alternative, method, nperm, call.

pca, multiblock_biprojector, and multiblock_projector:

Returns an object inheriting from perm_test (classes perm_test_pca, perm_test_multiblock, or perm_test respectively for multiblock_projector), a list containing: component_results (data frame with observed stat, pval, CIs per component), perm_values (matrix of permuted stats), alpha (if applicable), alternative, method, nperm (vector of successful permutations per component), call.

References

Buja, A., & Eyuboglu, N. (1992). Remarks on parallel analysis. Multivariate Behavioral Research, 27(4), 509-540. (Relevant for PCA permutation concepts)

Vitale, R., Westerhuis, J. A., Næs, T., Smilde, A. K., de Noord, O. E., & Ferrer, A. (2017). Selecting the number of factors in principal component analysis by permutation testing— Numerical and practical aspects. Journal of Chemometrics, 31(10), e2937. doi:10.1002/cem.2937 (Specific to perm_test.pca)

See Also

pca, cross_projector, discriminant_projector, multiblock_biprojector, measure_interblock_transfer_error

Examples

# PCA Example
data(iris)
X_iris <- as.matrix(iris[,1:4])
mod_pca <- pca(X_iris, ncomp=4, preproc=center()) # Ensure centering

# Test first 3 components sequentially (faster with more nperm)
# Ensure a future plan is set for parallel=TRUE, e.g., future::plan("multisession")
res_pca <- perm_test(mod_pca, X_iris, nperm=50, comps=3, parallel=FALSE)
print(res_pca)

# PCA Example with row shuffling (tests different null hypothesis)
row_shuffle <- function(dat, ...) dat[sample(nrow(dat)), ]
res_pca_row <- perm_test(mod_pca, X_iris, nperm=50, comps=3,
                         shuffle_fun=row_shuffle, parallel=FALSE)
print(res_pca_row)

Description

Permutation test for an effect operator

Usage

## S3 method for class 'effect_operator'
perm_test(
  x,
  nperm = 999,
  scheme = c("reduced_model"),
  parallel = FALSE,
  alpha = 0.05,
  stepwise = TRUE,
  alternative = c("greater", "less", "two.sided"),
  refit_basis = FALSE,
  seed = NULL,
  ...
)

Arguments

Value

A permutation-test result object for effect operators.

Description

Uses row-wise permutation of the Y block to assess the significance of each latent variable (LV) in a fitted plsc model. The test statistic is the singular value of the cross-covariance matrix for each LV.

Usage

## S3 method for class 'plsc'
perm_test(
  x,
  X,
  Y,
  nperm = 1000,
  comps = ncomp(x),
  stepwise = TRUE,
  shuffle_fun = NULL,
  parallel = FALSE,
  alternative = c("greater", "less", "two.sided"),
  alpha = 0.05,
  ...
)

Arguments

Description

Reference implementation of symmetric brain-behavior PLS (a.k.a. Behavior PLSC). It finds paired weight vectors for X and Y that maximize their cross-block covariance, obtained from the SVD of the cross-covariance (or correlation) matrix $C_{XY} = X^\top Y / (n-1)$.

Usage

plsc(
  X,
  Y,
  ncomp = NULL,
  preproc_x = standardize(),
  preproc_y = standardize(),
  ...
)

Arguments

Value

A cross_projector with class "plsc" containing

• vx, vy: X and Y loading/weight matrices.

• sx, sy: subject scores for X and Y blocks.

• singvals: singular values of $C_{XY}$ (strength of each LV).

• explained_cov: proportion of cross-block covariance per LV.

• preproc_x, preproc_y: fitted preprocessors for reuse.

Examples

set.seed(1)
X <- matrix(rnorm(80), 20, 4)
Y <- matrix(rnorm(60), 20, 3)
fit <- plsc(X, Y, ncomp = 3)
fit$singvals

Description

Predicts class labels and probabilities for new data using a fitted classifier object. It performs k-Nearest Neighbors (k-NN) classification in the projected component space.

Usage

## S3 method for class 'classifier'
predict(
  object,
  new_data,
  ncomp = NULL,
  colind = NULL,
  metric = c("euclidean", "cosine", "ejaccard"),
  normalize_probs = FALSE,
  prob_type = c("knn_proportion", "avg_similarity"),
  ...
)

Arguments

Details

The function first projects the new_data into the component space defined by the classifier's internal projector. If colind is specified, a partial projection using only those features is performed. This projection is then compared to the reference scores stored within the classifier object (object$scores) using the specified metric. The k-NN algorithm identifies the k nearest reference samples (based on similarity or distance) and predicts the class via majority vote. Probabilities are estimated based on the average similarity/distance to each class among the neighbors or all reference points.

Value

A list containing:

See Also

classifier.projector, classifier.multiblock_biprojector, partial_project

Other classifier predict: predict.rf_classifier()

Examples

# Assume clf is a fitted classifier object (e.g., from classifier.projector)
# Assume new_dat is a matrix of new observations
# preds <- predict(clf, new_data = new_dat, metric = "cosine")
# print(preds$class)
# print(preds$prob)

Description

This produces class predictions or posterior-like scores for new data. We first project the data into the subspace defined by x$v, then either:

1. LDA approach (method="lda"), which uses a (simplified) linear discriminant formula or distance to class means in the subspace combined with prior probabilities.

2. Euclid approach (method="euclid"), which uses plain Euclidean distance to each class mean in the subspace.

We return either a type="class" label or type="prob" posterior-like matrix.

Usage

## S3 method for class 'discriminant_projector'
predict(
  object,
  new_data,
  method = c("lda", "euclid"),
  type = c("class", "prob"),
  colind = NULL,
  ...
)

Arguments

Value

If type="class", a factor vector of length n (predicted classes). If type="prob", an (n x #classes) numeric matrix of posterior-like values, with row names matching new_data if available.

Predict method for a discriminant_projector

This produces class predictions or posterior-like scores for new data, based on:

• LDA approach (method="lda"), which uses a linear discriminant formula with a pooled covariance matrix if x\$Sigma is given, or the identity matrix if Sigma=NULL. If that covariance matrix is not invertible, a pseudo-inverse is used and a warning is emitted.

• Euclid approach (method="euclid"), which uses plain Euclidean distance to each class mean in the subspace.

We return either a type="class" label or type="prob" posterior-like matrix.

If type="class", a factor vector of length n (predicted classes). If type="prob", an (n x #classes) numeric matrix of posterior-like values.

Description

Predicts class labels and probabilities for new data using a fitted rf_classifier object. This method projects the new_data into the component space and then uses the stored randomForest model to predict outcomes.

Usage

## S3 method for class 'rf_classifier'
predict(object, new_data, ncomp = NULL, colind = NULL, ...)

Arguments

Value

A list containing:

See Also

rf_classifier.projector, predict.randomForest

Other classifier predict: predict.classifier()

Description

prepare a dataset by applying a pre-processing pipeline

Usage

prep(x, ...)

Arguments

Value

the pre-processed data

Description

This helper function provides a simple interface for the common preprocessing workflow: fit a preprocessor to data and return both the fitted preprocessor and the transformed data.

Usage

preprocess(preproc, X, ...)

Arguments

Value

A list with two elements:

See Also

fit(), fit_transform(), transform(), inverse_transform()

Examples

# Simple preprocessing workflow
X <- matrix(rnorm(100), 10, 10)
result <- preprocess(center(), X)
fitted_preproc <- result$preproc
X_centered <- result$transformed

# Equivalent to:
# fitted_preproc <- fit(center(), X)
# X_centered <- transform(fitted_preproc, X)

Description

Computes the principal angles between two subspaces defined by the columns of two orthonormal matrices Q1 and Q2.

Usage

prinang(Q1, Q2)

Arguments

Value

A numeric vector containing the principal angles in radians, sorted in ascending order. The number of angles is min(p, q).

Examples

# Example: Angle between xy-plane and a plane rotated 45 degrees around x-axis
Q1 <- cbind(c(1,0,0), c(0,1,0)) # xy-plane basis
theta <- pi/4
R <- matrix(c(1, 0, 0, 0, cos(theta), sin(theta), 0, -sin(theta), cos(theta)), 3, 3)
Q2 <- R %*% Q1 # Rotated basis
angles_rad <- prinang(Q1, Q2)
angles_deg <- angles_rad * 180 / pi
print(angles_deg) # Should be approximately 0 and 45 degrees

# Example with PCA loadings (after ensuring orthonormality if needed)
# Assuming pca1$v and pca2$v are loading matrices (variables x components)
# Orthonormalize them first if they are not already (e.g., from standard SVD)
# Q1 <- qr.Q(qr(pca1$v[, 1:3]))
# Q2 <- qr.Q(qr(pca2$v[, 1:3]))
# prinang(Q1, Q2)

Description

Principal angles (two sub‑spaces)

Usage

principal_angles(fit1, fit2, k = NULL)

Arguments

Value

numeric vector of principal angles (radians, length = k)

Description

Pretty Print S3 Method for bi_projector Class

Usage

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

Arguments

Value

Invisible bi_projector object

Description

Display a human-readable summary of a classifier object.

Usage

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

Arguments

Value

classifier object.

Examples

# Assume clf is a fitted classifier object
# print(clf)

Description

Print a concat_pre_processor object

Usage

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

Arguments

Description

Display a summary of a multiblock_biprojector object.

Usage

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

Arguments

Value

Invisible multiblock_biprojector object.

Description

Provide a color-enhanced summary of the PCA object, including dimensions, variance explained, and a quick component breakdown.

Usage

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

Arguments

Description

Provides a concise summary of the permutation test results.

Usage

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

Arguments

Value

Invisibly returns the input object x.

Description

Provides a concise summary of the PCA permutation test results.

Usage

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

Arguments

Value

Invisibly returns the input object x.

Description

Display information about a pre_processor using cli-based formatting.

Usage

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

Arguments

Description

Uses cli to produce a colorful and readable representation of the pipeline steps.

Usage

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

Arguments

Description

Display a human-readable summary of a regress object using crayon formatting, including information about the method and dimensions.

Usage

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

Arguments

Description

Display a human-readable summary of an rf_classifier object.

Usage

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

Arguments

Value

rf_classifier object.

Examples

# Assume rf_clf is a fitted rf_classifier object
# print(rf_clf)

Description

Project one or more samples onto a subspace. This function takes a model fit and new observations, and projects them onto the subspace defined by the model. This allows for the transformation of new data into the same lower-dimensional space as the original data.

Usage

project(x, new_data, ...)

Arguments

Value

A matrix or vector of the projected observations, where rows represent observations and columns represent the lower-dimensional space

See Also

bi_projector for an example of a class that implements a project method

Other project: project.cross_projector(), project_block(), project_vars()

Examples

# Example with the bi_projector class
X <- matrix(rnorm(10*20), 10, 20)
svdfit <- svd(X)
p <- bi_projector(svdfit$v, s = svdfit$u %*% diag(svdfit$d), sdev=svdfit$d)

# Project new_data onto the same subspace as the original data
new_data <- matrix(rnorm(5*20), 5, 20)
projected_data <- project(p, new_data)

Description

When observations are concatenated into "blocks", it may be useful to project one block from the set. This function facilitates the projection of a specific block of data onto a subspace. It is a convenience method for multi-block fits and is equivalent to a "partial projection" where the column indices are associated with a given block.

Usage

project_block(x, new_data, block, least_squares, ...)

Arguments

Value

A matrix or vector of the projected data for the specified block

See Also

project for the generic projection function

Other project: project(), project.cross_projector(), project_vars()

Description

Projects the new data onto the subspace defined by a specific block of variables.

Usage

## S3 method for class 'multiblock_projector'
project_block(x, new_data, block, least_squares = FALSE, ...)

Arguments

Value

The projected scores for the specified block.

Description

This function projects one or more variables onto a subspace. It is often called supplementary variable projection and can be computed for a biorthogonal decomposition, such as Singular Value Decomposition (SVD).

Usage

project_vars(x, new_data, ...)

Arguments

Value

A matrix or vector of the projected variables in the subspace

See Also

project for the generic projection function for samples

Other project: project(), project.cross_projector(), project_block()

Description

project a cross_projector instance

Usage

## S3 method for class 'cross_projector'
project(x, new_data, source = c("X", "Y"), ...)

Arguments

Value

the projected data

See Also

Other project: project(), project_block(), project_vars()

Description

Project new data using a Nyström approximation model

Usage

## S3 method for class 'nystrom_approx'
project(x, new_data, ...)

Arguments

Value

A matrix of projected scores.

Description

A projector maps a matrix from an N-dimensional space to d-dimensional space, where d may be less than N. The projection matrix, v, is not necessarily orthogonal. This function constructs a projector instance which can be used for various dimensionality reduction techniques like PCA, LDA, etc.

Usage

projector(v, preproc = prep(pass()), ..., classes = NULL)

Arguments

Value

An instance of type projector.

Description

Computes the rank score (normalized rank of the true class probability) for each observation. Lower rank scores indicate better predictions (true class has higher probability).

Usage

rank_score(prob, observed)

Arguments

Value

A data.frame with columns prank (the normalized rank score) and observed (the input labels).

See Also

Other classifier evaluation: topk()

Examples

probs <- matrix(c(0.1, 0.9, 0.8, 0.2), 2, 2, byrow=TRUE,
               dimnames = list(NULL, c("A", "B")))
obs <- factor(c("B", "A"))
rank_score(probs, obs)

Description

Reconstruct a data set from its (possibly) low-rank representation. This can be useful when analyzing the impact of dimensionality reduction or when visualizing approximations of the original data.

Usage

reconstruct(x, ...)

Arguments

Value

A reconstructed data set based on the selected components, rows, and columns

See Also

bi_projector for an example of a two-way mapping model that can be reconstructed

Other reconstruct: reconstruct_new()