scores.utils.TensorPCA

Tensor-based PCA.

Usage

Source

scores.utils.TensorPCA(
    n_components=0.9, gamma=None, M=None, mode=None, mean_center=True
)

Supports standard (linear) PCA and an optional Random Fourier Feature (RFF) mapping prior to PCA.

Operation Modes

  • linear: standard linear PCA.
  • rff: apply a Random Fourier Feature mapping before PCA.

Mode selection follows the constructor arguments: the RFF branch is inferred only when both gamma and M are provided, unless mode is set explicitly. Supplying only one of these values does not enable the RFF mapping by itself.

Saving / Loading

Persist the module with the standard PyTorch state-dict API. The module registers persistent buffers for PCA and RFF state::

torch.save(instance.state_dict(), "tpca.pt")

tpca2 = TensorPCA(n_components=..., gamma=..., M=..., mode=...)
sd = torch.load("tpca.pt")
tpca2.load_state_dict(sd)

The custom _load_from_state_dict accepts placeholder or differently- shaped tensors and will set or register buffers to avoid size-mismatch errors on fresh instances.

Notes

PCA internals are stored in float64 for numerical fidelity. During preprocessing, inputs are cast to float64 to match the stored mean.

See https://arxiv.org/pdf/2505.15284 for motivation behind RFF-PCA.

See Also

scores.PCAScore
scores.EmbeddingScore

Examples

import torch
from seapig.scores.utils import TensorPCA
pca = TensorPCA(n_components=0.90)
X = torch.randn(100, 32)
pca.fit(X)
Z = pca.transform(X)        # projected to lower dimension
X_rec, err = pca.reconstruct(X)  # reconstruction and per-sample L2 error
print(err)
tensor([1.0848, 1.5725, 2.1466, 1.3277, 1.5360, 1.7727, 1.1445, 1.0684, 1.3575,
        2.2037, 1.5044, 1.4891, 1.6238, 1.5578, 2.6422, 1.6761, 1.9741, 1.4328,
        1.3964, 1.5223, 1.2639, 1.4453, 1.5564, 2.0992, 2.2034, 1.5298, 1.3880,
        2.1404, 1.3067, 2.4120, 1.3723, 1.2947, 1.6187, 2.4783, 1.0755, 2.1198,
        1.2108, 1.0201, 1.9510, 1.8309, 1.2112, 1.3093, 1.5463, 2.7748, 2.0322,
        1.8698, 2.3488, 1.5973, 1.9580, 1.3986, 2.1767, 2.0039, 1.0697, 2.0018,
        2.4174, 1.4701, 1.2509, 2.3371, 1.9391, 1.4061, 2.0301, 2.7308, 1.3829,
        1.5683, 1.9536, 1.1104, 2.4663, 0.9955, 1.4139, 1.7873, 1.2206, 1.9651,
        1.9568, 1.7048, 1.6685, 1.7184, 2.0657, 1.3931, 2.3070, 1.8024, 1.6519,
        1.8728, 1.5470, 2.1904, 2.4470, 1.6505, 1.5216, 1.7414, 1.9481, 1.2750,
        1.9345, 1.9236, 2.4115, 1.0019, 2.1994, 2.3884, 2.1987, 1.6812, 2.0181,
        1.9916], dtype=torch.float64)

Methods

Name Description
__init__() Initialise TensorPCA.
finalize() Finalize partial fit: compute covariance SVD and set PCA params.
fit() Fit PCA on the input data X.
fit_transform() Fit PCA on X and return the projected components.
inverse_transform() Reconstruct samples from principal component scores.
partial_fit() Process a single batch for incremental PCA.
reconstruct() Reconstruct an input and return the L2 reconstruction error.
reset_partial() Reset internal accumulators used for partial fitting.
transform() Project input samples onto the retained principal components.

__init__()

Initialise TensorPCA.

Usage

Source

__init__(n_components=0.9, gamma=None, M=None, mode=None, mean_center=True)
Parameters
n_components: int or float = 0.90

If an int, the exact number of principal components to retain (must be > 0). If a float in (0, 1], the minimum cumulative explained variance to retain. Defaults to 0.90 (90% variance).

gamma: float or None = None

Bandwidth parameter for the RFF kernel. If provided together with M, RFF mode is enabled automatically.

M: int or None = None

Number of RFF random features (must be > input dimensionality D). If provided together with gamma, RFF mode is enabled automatically.

mode: (linear, rff) = "linear"

Explicit mode override. When None, the mode is inferred from gamma and M.

mean_center: bool = True
Apply mean centering before fitting/transform? Set to False to omit mean centering.

finalize()

Finalize partial fit: compute covariance SVD and set PCA params.

Usage

Source

finalize()

This method computes the overall mean and centred covariance from accumulated sums and performs SVD to extract principal components.

fit()

Fit PCA on the input data X.

Usage

Source

fit(X, Y=None)

Convenience method that runs a single-batch partial_fit followed by finalize. For large datasets or streaming data, use the incremental partial_fit / finalize interface instead.

Parameters
X: torch.Tensor

Input data of shape (N, D).

Y: None = None
Ignored. Present for API compatibility.

fit_transform()

Fit PCA on X and return the projected components.

Usage

Source

fit_transform(X, Y=None)
Parameters
X: torch.Tensor

Input data of shape (N, D).

Y: None = None
Ignored. Present for API compatibility.
Returns
torch.Tensor
Projected data of shape (N, q) where q is the number of retained components.

inverse_transform()

Reconstruct samples from principal component scores.

Usage

Source

inverse_transform(Z)
Parameters
Z: torch.Tensor
Component scores of shape (N, q).
Returns
torch.Tensor
Reconstructed samples in the preprocessed space, shape (N, D) or (N, M) if RFF mode is used.

partial_fit()

Process a single batch for incremental PCA.

Usage

Source

partial_fit(X)

This accumulates sufficient statistics (sum of samples and sum of outer products) which are later finalised in finalize() to produce the PCA decomposition.

reconstruct()

Reconstruct an input and return the L2 reconstruction error.

Usage

Source

reconstruct(X)

reset_partial()

Reset internal accumulators used for partial fitting.

Usage

Source

reset_partial()

transform()

Project input samples onto the retained principal components.

Usage

Source

transform(X)
Parameters
X: torch.Tensor
Input data of shape (N, D).
Returns
torch.Tensor
Projected data of shape (N, q) where q is the number of retained components.