MLPCA: Principal Component Analysis

MLPCAR Documentation

Principal Component Analysis

Description

Fits PCA to a data matrix, retaining the top-M principal components. Centering/normalization is applied to X in-place at construction time (the R matrix or the memory-mapped file itself, no copy) and undone by restore(), which may be called before or after fit() and is idempotent; an object that is garbage-collected without restore() writes X back in its finalizer (the same rule as the T-solvers).

Details

Wraps the C++ PCA class. The instance is bound to X at creation (mirroring the C++ constructor); fit() is single-use. The fit result is cached internally; use the get_*() accessors or pass X_new to transform() for out-of-sample scoring.

Methods

Public methods


MLPCA$new()

Initialize PCA bound to X. Centering/normalization is applied to X in-place immediately.

Usage
MLPCA$new(X, M, center = TRUE, normalize = TRUE, n_threads = NULL)
Arguments
X

A numeric matrix (n x p), or an mmap_matrix ("readwrite": the file is modified). Modified in place when centering/normalizing; call restore() to undo.

M

Integer, number of principal components.

center

Logical, whether to center X in-place (default: TRUE).

normalize

Logical, whether to scale the columns of X in-place (default: TRUE).

n_threads

Integer, the thread budget of the matrix products of fit() and transform() (NULL, the default: the library's default budget, trex_get_num_threads(), initially 1).


MLPCA$fit()

Fit the PCA bound at construction time (single-use).

Usage
MLPCA$fit()
Returns

Invisible self for method chaining.


MLPCA$transform()

Project new data onto the fitted principal subspace.

Usage
MLPCA$transform(X_new)
Arguments
X_new

A numeric matrix (n_new x p), or an mmap_matrix (zero-copy). The stored training means/norms are applied before projection.

Returns

Score matrix (n_new x M).


MLPCA$restore()

Restore X to its original values (un-center/un-scale).

Usage
MLPCA$restore()
Returns

Invisible self.


MLPCA$get_scores()

Get the PC score matrix from the fit() call.

Usage
MLPCA$get_scores()
Returns

Score matrix (n x M), or NULL if fit() not yet called.


MLPCA$get_loadings()

Get loading matrix from the fit() call.

Usage
MLPCA$get_loadings()
Returns

Loading matrix (p x M), or NULL if fit() not yet called.


MLPCA$get_explained_variance()

Get explained variance per component from the fit() call.

Usage
MLPCA$get_explained_variance()
Returns

Numeric vector of length M, or NULL if fit() not yet called.


MLPCA$get_means()

Get the column means used for centering.

Usage
MLPCA$get_means()
Returns

Numeric vector of length p. Zero-vector when center = FALSE.


MLPCA$get_norms()

Get the column scaling factors used for normalization.

Usage
MLPCA$get_norms()
Returns

Numeric vector of length p. Ones when normalize = FALSE.


MLPCA$clone()

The objects of this class are cloneable with this method.

Usage
MLPCA$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

References

G. Guennebaud, B. Jacob et al., Eigen v3, https://libeigen.gitlab.io/, 2010.

See Also

Other ML methods: MLElasticNet, MLElasticNetCV, MLLpNormScaler, MLRidge, MLRidgeCV, MLSVD, MLZScoreScaler, ml_agglomerative_cluster(), ml_cut_tree(), ml_distance_metric, ml_linkage_method

Examples

set.seed(42)
X <- matrix(rnorm(50 * 8), 50, 8)
pca <- MLPCA$new(X, M = 3, center = TRUE)
pca$fit()
pca$get_explained_variance()
X_new <- matrix(rnorm(10 * 8), 10, 8)
pca$transform(X_new)
pca$restore()


TRexSelector documentation built on Nov. 20, 2026, 5:09 p.m.