Transform Projection

projection

CLASS	DESCRIPTION
ProjectionTransformer	Linear projection using a pre-computed projection matrix.

Classes

ProjectionTransformer(projection_matrix: torch.Tensor, center: torch.Tensor | None = None)

Bases: Transformer

Linear projection using a pre-computed projection matrix.

Applies matrix multiplication X @ P where P is the projection matrix. Useful for applying PCA projections, random projections, or other linear transformations with fixed projection matrices.

PARAMETER	DESCRIPTION
projection_matrix	Projection matrix of shape (in_features, out_features). TYPE: Tensor
center	Optional centering vector of shape (in_features,). If provided, data is centered before projection: (X - center) @ P. TYPE: torch.Tensor | None, optional, by default None DEFAULT: None

ATTRIBUTE	DESCRIPTION
projection_matrix	The projection matrix (registered as buffer). TYPE: Tensor
center	The centering vector if provided (registered as buffer). TYPE: Tensor | None
in_features	Number of input features. TYPE: int
out_features	Number of output features after projection. TYPE: int

Examples:

Basic projection without centering

>>> import torch
>>> from spectre.transform import ProjectionTransformer
>>> P = torch.randn(10, 3)
>>> projector = ProjectionTransformer(P)
>>> X = torch.randn(100, 10)
>>> X_proj = projector.transform(X)
>>> X_proj.shape
torch.Size([100, 3])

Projection with centering (like PCA)

>>> mean = torch.randn(10)
>>> projector = ProjectionTransformer(P, center=mean)
>>> X_proj = projector.transform(X)
>>> X_proj.shape
torch.Size([100, 3])

Inverse projection (approximate reconstruction)

>>> X_reconstructed = projector.inverse_transform(X_proj)
>>> X_reconstructed.shape
torch.Size([100, 10])

METHOD	DESCRIPTION
transform	Project input data using the projection matrix.
inverse_transform	Approximate inverse projection back to original space.

Source code in spectre/transform/projection.py

def __init__(
    self,
    projection_matrix: torch.Tensor,
    center: torch.Tensor | None = None,
) -> None:
    super().__init__()

    if projection_matrix.dim() != 2:
        raise ValueError(
            f"projection_matrix must be 2D, got shape {projection_matrix.shape}."
        )

    self.register_buffer("projection_matrix", projection_matrix)
    self._in_features = projection_matrix.shape[0]
    self._out_features = projection_matrix.shape[1]

    if center is not None:
        if center.dim() != 1:
            raise ValueError(f"center must be 1D, got shape {center.shape}.")
        if len(center) != self._in_features:
            raise ValueError(
                f"center length ({len(center)}) must match projection_matrix "
                f"input dimension ({self._in_features})."
            )
        self.register_buffer("center", center)
    else:
        self.center = None

Attributes

in_features: int property

Number of input features.

out_features: int property

Number of output features.

Functions

transform(X: torch.Tensor) -> torch.Tensor

Project input data using the projection matrix.

PARAMETER	DESCRIPTION
X	Input data of shape (n_samples, in_features). TYPE: Tensor

RETURNS	DESCRIPTION
Tensor	Projected data of shape (n_samples, out_features).

Source code in spectre/transform/projection.py

def transform(self, X: torch.Tensor) -> torch.Tensor:
    """
    Project input data using the projection matrix.

    Parameters
    ----------
    X : torch.Tensor
        Input data of shape (n_samples, in_features).


    Returns
    -------
    torch.Tensor
        Projected data of shape (n_samples, out_features).
    """
    if X.shape[-1] != self._in_features:
        raise ValueError(
            f"Input feature dimension ({X.shape[-1]}) must match "
            f"projection matrix input dimension ({self._in_features})."
        )

    if self.center is not None:
        X = X - self.center

    return X @ self.projection_matrix

inverse_transform(X: torch.Tensor) -> torch.Tensor

Approximate inverse projection back to original space.

Uses the transpose of the projection matrix for reconstruction. This is exact for orthogonal projections and approximate otherwise.

PARAMETER	DESCRIPTION
X	Projected data of shape (n_samples, out_features). TYPE: Tensor

RETURNS	DESCRIPTION
Tensor	Reconstructed data of shape (n_samples, in_features).

Notes

For orthogonal projection matrices (like PCA components), this provides exact reconstruction if all components are retained. Otherwise, it provides an approximate reconstruction.

Source code in spectre/transform/projection.py

def inverse_transform(self, X: torch.Tensor) -> torch.Tensor:
    """
    Approximate inverse projection back to original space.

    Uses the transpose of the projection matrix for reconstruction.
    This is exact for orthogonal projections and approximate otherwise.

    Parameters
    ----------
    X : torch.Tensor
        Projected data of shape (n_samples, out_features).


    Returns
    -------
    torch.Tensor
        Reconstructed data of shape (n_samples, in_features).


    Notes
    -----
    For orthogonal projection matrices (like PCA components), this
    provides exact reconstruction if all components are retained.
    Otherwise, it provides an approximate reconstruction.
    """
    if X.shape[-1] != self._out_features:
        raise ValueError(
            f"Input feature dimension ({X.shape[-1]}) must match "
            f"projection matrix output dimension ({self._out_features})."
        )

    # Use transpose for inverse
    X_reconstructed = X @ self.projection_matrix.T

    if self.center is not None:
        X_reconstructed = X_reconstructed + self.center

    return X_reconstructed