Transform Reshape

reshape

CLASS	DESCRIPTION
ReshapeTransformer	Reshape data to target shape while preserving batch dimension.
FlattenTransformer	Flatten multi-dimensional data to 2D while preserving batch dimension.

Classes

ReshapeTransformer(target_shape: tuple[int, ...], input_shape: tuple[int, ...] | None = None)

Bases: Transformer

Reshape data to target shape while preserving batch dimension.

Reshapes input tensors from shape (batch_size, ...) to (batch_size, *target_shape). Useful for converting between different data formats while maintaining the batch structure.

PARAMETER	DESCRIPTION
target_shape	Target shape for the data (excluding batch dimension). TYPE: tuple[int, ...]
input_shape	Original input shape (excluding batch dimension) for inverse transformation. Required if inverse_transform will be used. TYPE: tuple[int, ...] | None, optional, by default None DEFAULT: None

ATTRIBUTE	DESCRIPTION
target_shape	The target shape for forward transformation. TYPE: tuple[int, ...]
input_shape	The original shape for inverse transformation. TYPE: tuple[int, ...] | None

Examples:

Reshape flat vectors to 2D

>>> import torch
>>> from spectre.transform import ReshapeTransformer
>>> reshaper = ReshapeTransformer(target_shape=(5, 2))
>>> X = torch.randn(100, 10)
>>> X_reshaped = reshaper.transform(X)
>>> X_reshaped.shape
torch.Size([100, 5, 2])

Reshape with inverse (e.g., flatten to image and back)

>>> reshaper = ReshapeTransformer(target_shape=(28, 28), input_shape=(784,))
>>> X = torch.randn(32, 784)  # Flattened images
>>> X_images = reshaper.transform(X)
>>> X_images.shape
torch.Size([32, 28, 28])
>>> X_reconstructed = reshaper.inverse_transform(X_images)
>>> X_reconstructed.shape
torch.Size([32, 784])
>>> torch.allclose(X, X_reconstructed)
True

METHOD	DESCRIPTION
transform	Reshape input data to target shape.
inverse_transform	Reshape data back to original shape.

Source code in spectre/transform/reshape.py

def __init__(
    self,
    target_shape: tuple[int, ...],
    input_shape: tuple[int, ...] | None = None,
) -> None:
    super().__init__()

    if not isinstance(target_shape, tuple):
        raise TypeError(
            f"target_shape must be tuple, got {type(target_shape).__name__}."
        )

    if not all(isinstance(d, int) and d > 0 for d in target_shape):
        raise ValueError(
            "All dimensions in target_shape must be positive integers."
        )

    self.target_shape = target_shape
    self.input_shape = input_shape

    if input_shape is not None:
        if not isinstance(input_shape, tuple):
            raise TypeError(
                f"input_shape must be tuple, got {type(input_shape).__name__}."
            )
        if not all(isinstance(d, int) and d > 0 for d in input_shape):
            raise ValueError(
                "All dimensions in input_shape must be positive integers."
            )

        # Verify shapes are compatible (same total number of elements)
        import math

        target_numel = math.prod(target_shape)
        input_numel = math.prod(input_shape)
        if target_numel != input_numel:
            raise ValueError(
                f"target_shape ({target_shape}) and input_shape ({input_shape}) "
                f"must have same total number of elements. Got {target_numel} "
                f"and {input_numel}."
            )

Functions

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

Reshape input data to target shape.

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

RETURNS	DESCRIPTION
Tensor	Reshaped data of shape (batch_size, *target_shape).

Source code in spectre/transform/reshape.py

def transform(self, X: torch.Tensor) -> torch.Tensor:
    """
    Reshape input data to target shape.

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


    Returns
    -------
    torch.Tensor
        Reshaped data of shape (batch_size, `*target_shape`).
    """
    batch_size = X.shape[0]
    return X.reshape(batch_size, *self.target_shape)

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

Reshape data back to original shape.

PARAMETER	DESCRIPTION
X	Reshaped data of shape (batch_size, *target_shape). TYPE: Tensor

RETURNS	DESCRIPTION
Tensor	Data in original shape (batch_size, *input_shape).

RAISES	DESCRIPTION
ValueError	If input_shape was not provided at initialization.

Source code in spectre/transform/reshape.py

def inverse_transform(self, X: torch.Tensor) -> torch.Tensor:
    """
    Reshape data back to original shape.

    Parameters
    ----------
    X : torch.Tensor
        Reshaped data of shape (batch_size, `*target_shape`).


    Returns
    -------
    torch.Tensor
        Data in original shape (batch_size, `*input_shape`).


    Raises
    ------
    ValueError
        If input_shape was not provided at initialization.
    """
    if self.input_shape is None:
        raise ValueError(
            "input_shape must be provided at initialization to use inverse_transform."
        )

    batch_size = X.shape[0]
    return X.reshape(batch_size, *self.input_shape)

FlattenTransformer(input_shape: tuple[int, ...] | None = None)

Bases: Transformer

Flatten multi-dimensional data to 2D while preserving batch dimension.

Flattens input tensors from shape (batch_size, d1, d2, ..., dn) to (batch_size, d1 * d2 * ... * dn). Commonly used to convert image data to vectors for linear models.

PARAMETER	DESCRIPTION
input_shape	Original input shape (excluding batch dimension) for inverse transformation. Required if inverse_transform will be used. TYPE: tuple[int, ...] | None, optional, by default None DEFAULT: None

ATTRIBUTE	DESCRIPTION
input_shape	The original shape for inverse transformation. TYPE: tuple[int, ...] | None

Examples:

Flatten image tensors

>>> import torch
>>> from spectre.transform import FlattenTransformer
>>> flattener = FlattenTransformer()
>>> X = torch.randn(32, 28, 28)  # Batch of 28x28 images
>>> X_flat = flattener.transform(X)
>>> X_flat.shape
torch.Size([32, 784])

Flatten with inverse transformation

>>> flattener = FlattenTransformer(input_shape=(28, 28))
>>> X_reconstructed = flattener.inverse_transform(X_flat)
>>> X_reconstructed.shape
torch.Size([32, 28, 28])
>>> torch.allclose(X, X_reconstructed)
True

Flatten 3D data (e.g., RGB images)

>>> X = torch.randn(16, 3, 32, 32)  # Batch of 3x32x32 RGB images
>>> flattener = FlattenTransformer(input_shape=(3, 32, 32))
>>> X_flat = flattener.transform(X)
>>> X_flat.shape
torch.Size([16, 3072])

METHOD	DESCRIPTION
transform	Flatten input data to 2D.
inverse_transform	Reshape flattened data back to original shape.

Source code in spectre/transform/reshape.py

def __init__(self, input_shape: tuple[int, ...] | None = None) -> None:
    super().__init__()

    if input_shape is not None:
        if not isinstance(input_shape, tuple):
            raise TypeError(
                f"input_shape must be tuple, got {type(input_shape).__name__}."
            )
        if not all(isinstance(d, int) and d > 0 for d in input_shape):
            raise ValueError(
                "All dimensions in input_shape must be positive integers."
            )

    self.input_shape = input_shape

Functions

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

Flatten input data to 2D.

PARAMETER	DESCRIPTION
X	Input data of shape (batch_size, d1, d2, ..., dn). TYPE: Tensor

RETURNS	DESCRIPTION
Tensor	Flattened data of shape (batch_size, d1 * d2 * ... * dn).

Source code in spectre/transform/reshape.py

def transform(self, X: torch.Tensor) -> torch.Tensor:
    """
    Flatten input data to 2D.

    Parameters
    ----------
    X : torch.Tensor
        Input data of shape (batch_size, d1, d2, ..., dn).


    Returns
    -------
    torch.Tensor
        Flattened data of shape (batch_size, d1 * d2 * ... * dn).
    """
    batch_size = X.shape[0]
    return X.reshape(batch_size, -1)

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

Reshape flattened data back to original shape.

PARAMETER	DESCRIPTION
X	Flattened data of shape (batch_size, n_features). TYPE: Tensor

RETURNS	DESCRIPTION
Tensor	Data in original shape (batch_size, *input_shape).

RAISES	DESCRIPTION
ValueError	If input_shape was not provided at initialization.

Source code in spectre/transform/reshape.py

def inverse_transform(self, X: torch.Tensor) -> torch.Tensor:
    """
    Reshape flattened data back to original shape.

    Parameters
    ----------
    X : torch.Tensor
        Flattened data of shape (batch_size, n_features).


    Returns
    -------
    torch.Tensor
        Data in original shape (batch_size, `*input_shape`).


    Raises
    ------
    ValueError
        If input_shape was not provided at initialization.
    """
    if self.input_shape is None:
        raise ValueError(
            "input_shape must be provided at initialization to use inverse_transform."
        )

    batch_size = X.shape[0]
    return X.reshape(batch_size, *self.input_shape)