sparsecoding.transforms package

class sparsecoding.transforms.WhiteningTransform(algorithm: str = 'zca', stats: Dict | None = None, compute_stats: bool = False, **kwargs)

Bases: object

A PyTorch transform for image whitening that can be used in a transform pipeline. Supports frequency, PCA, and ZCA whitening methods.

Parameters:

  • algorithm (str) – One of [‘frequency’, ‘pca’, ‘zca’, ‘cholesky]

  • stats (Dict or None, default=None) – Pre-computed statistics for PCA/ZCA whitening

  • compute_stats (bool, default=False) – If True, will compute stats on first batch seen

  • **kwargs – Additional arguments passed to whitening function

sparsecoding.transforms.compute_image_whitening_stats(images: Tensor) → Dict

Wrapper for computing whitening stats of an image dataset

Parameters:

images (torch.Tensor) – Tensor of shape (N, C, H, W)

Return type:

Dictionary containing whitening statistics (eigenvalues, eigenvectors, mean)

sparsecoding.transforms.compute_whitening_stats(X: Tensor)

Given a tensor of data, compute statistics for whitening transform.

Parameters:

X (torch.Tensor) – Input data of size [N, D]

Return type:

Dictionary containing whitening statistics (eigenvalues, eigenvectors, mean)

sparsecoding.transforms.patchify(patch_size: int, image: Tensor, stride: int | None = None)

Break an image into square patches.

Inverse of quilt().

Parameters:

  • patch_size (int) – Patch side length.

  • image (Tensor, shape [*, C, H, W]) – where: C is the number of channels, H is the image height, W is the image width.

  • stride (int, optional) – Stride between patches in pixel space. If not specified, set to patch_size (non-overlapping patches).

Returns:

patches – Non-overlapping patches taken from the input image, where: P is the patch size, N is the number of patches, equal to H//P * W//P, C is the number of channels of the input image.

Return type:

Tensor, shape [*, N, C, P, P]

sparsecoding.transforms.quilt(height: int, width: int, patches: Tensor)

Gather square patches into an image.

Inverse of patchify().

Parameters:

  • height (int) – Height for the reconstructed image.

  • width (int) – Width for the reconstructed image.

  • patches (Tensor, shape [*, N, C, P, P]) – Non-overlapping patches from an input image, where: P is the patch size, N is the number of patches, C is the number of channels in the image.

Returns:

image – Image reconstructed by stitching together input patches.

Return type:

Tensor, shape [*, C, height, width]

sparsecoding.transforms.sample_random_patches(patch_size: int, num_patches: int, image: Tensor)

Sample random patches from an image.

Parameters:

  • patch_size (int) – Patch side length.

  • num_patches (int) – Number of patches to sample.

  • image (Tensor, shape [*, C, H, W]) – where: C is the number of channels, H is the image height, W is the image width.

Returns:

patches – Sampled patches from the input image(s).

Return type:

Tensor, shape [num_patches, C, patch_size, patch_size]

sparsecoding.transforms.whiten(X: Tensor, algorithm: str = 'zca', stats: Dict | None = None, n_components: float | None = None, epsilon: float = 0.0, return_W: bool = False) → Tensor

Apply whitening transform to data using pre-computed statistics.

Parameters:

  • X (torch.Tensor) – Input data of shape [N, D] where N are unique data elements of dimensionality D

  • algorithm (str, default="zca") – Whitening transform we want to apply, one of [‘zca’, ‘pca’, or ‘cholesky’]

  • stats (Dict, default=None) – Dict containing precomputed whitening statistics (mean, eigenvectors, eigenvalues)

  • n_components (float, int, default=None) – Number of principal components to keep. If None, keep all components. If int, keep that many components. If float between 0 and 1, keep components that explain that fraction of variance.

  • epsilon (float, default=0.0) – Optional small constant to prevent division by zero

Return type:

Whitened data of shape [N, D]

Notes

See examples/Data_Whitening.ipynb for usage examples, and brief discussion about the different whitening methods

See https://arxiv.org/abs/1512.00809 for extensive details on whitening transformations - Possible TODO: Also gives two additional transforms that have not been implemented

See https://stats.stackexchange.com/questions/117427/what-is-the-difference-between-zca-whitening-and-pca-whitening for details on PCA and ZCA in particular

sparsecoding.transforms.whiten_images(images: Tensor, algorithm: str, stats: Dict | None = None, **kwargs) → Tensor

Wrapper for all whitening transformations

Parameters:

  • images (torch.Tensor) – Tensor of shape (N, C, H, W)

  • algorithm (str) – What whitening transform we want to use

  • stats (Dict, default=None) – Dictionary of dataset statistics needed for whitening transformations

Return type:

Tensor of whitened data in shape (N, C, H, W)

Submodules

sparsecoding.transforms.images module

class sparsecoding.transforms.images.WhiteningTransform(algorithm: str = 'zca', stats: Dict | None = None, compute_stats: bool = False, **kwargs)

Bases: object

A PyTorch transform for image whitening that can be used in a transform pipeline. Supports frequency, PCA, and ZCA whitening methods.

Parameters:

  • algorithm (str) – One of [‘frequency’, ‘pca’, ‘zca’, ‘cholesky]

  • stats (Dict or None, default=None) – Pre-computed statistics for PCA/ZCA whitening

  • compute_stats (bool, default=False) – If True, will compute stats on first batch seen

  • **kwargs – Additional arguments passed to whitening function

sparsecoding.transforms.images.check_images(images: Tensor, algorithm: str = 'zca')

Verify that tensor is in the shape [N, C, H, W] and C != when using fourier based method

sparsecoding.transforms.images.compute_image_whitening_stats(images: Tensor) → Dict

Wrapper for computing whitening stats of an image dataset

Parameters:

images (torch.Tensor) – Tensor of shape (N, C, H, W)

Return type:

Dictionary containing whitening statistics (eigenvalues, eigenvectors, mean)

sparsecoding.transforms.images.create_frequency_filter(image_size: int, f0_factor: float = 0.4) → Tensor

Create a frequency domain filter for image whitening.

Parameters:

  • image_size (int) – Size of the square image

  • f0_factor (float, default=0.4) – Factor for determining the cutoff frequency

Returns:

torch.Tensor

Return type:

Frequency domain filter

sparsecoding.transforms.images.frequency_whitening(images: Tensor, target_variance: float = 0.1, f0_factor: float = 0.4) → Tensor

Apply frequency domain decorrelation to batched images. Method used in original sparsenet in Olshausen and Field in Nature and http://www.rctn.org/bruno/sparsenet/

Parameters:

  • images (torch.Tensor) – Input images of shape (N, C, H, W)

  • target_variance (float, default=0.1) – Target variance for normalization

  • f0_factor (float, default = 0.4) – Factor for determining filter cutoff frequency

Returns:

torch.Tensor

Return type:

Whitened images

sparsecoding.transforms.images.get_cached_filter(image_size: int, f0_factor: float = 0.4) → Tensor

Get a cached frequency filter for the given image size.

Parameters:

  • image_size (int) – Size of the square image

  • f0_factor (float, default=0.4) – Factor for determining the cutoff frequency

Returns:

torch.Tensor

Return type:

Cached frequency domain filter

sparsecoding.transforms.images.normalize_variance(tensor: Tensor, target_variance: float = 1.0) → Tensor

Normalize the variance of a tensor to a target value.

Parameters:

  • tensor (torch.Tensor) – Input tensor

  • target_variance (float, default=1.0) – Desired variance after normalization

Returns:

torch.Tensor

Return type:

Normalized tensor

sparsecoding.transforms.images.patchify(patch_size: int, image: Tensor, stride: int | None = None)

Break an image into square patches.

Inverse of quilt().

Parameters:

  • patch_size (int) – Patch side length.

  • image (Tensor, shape [*, C, H, W]) – where: C is the number of channels, H is the image height, W is the image width.

  • stride (int, optional) – Stride between patches in pixel space. If not specified, set to patch_size (non-overlapping patches).

Returns:

patches – Non-overlapping patches taken from the input image, where: P is the patch size, N is the number of patches, equal to H//P * W//P, C is the number of channels of the input image.

Return type:

Tensor, shape [*, N, C, P, P]

sparsecoding.transforms.images.quilt(height: int, width: int, patches: Tensor)

Gather square patches into an image.

Inverse of patchify().

Parameters:

  • height (int) – Height for the reconstructed image.

  • width (int) – Width for the reconstructed image.

  • patches (Tensor, shape [*, N, C, P, P]) – Non-overlapping patches from an input image, where: P is the patch size, N is the number of patches, C is the number of channels in the image.

Returns:

image – Image reconstructed by stitching together input patches.

Return type:

Tensor, shape [*, C, height, width]

sparsecoding.transforms.images.sample_random_patches(patch_size: int, num_patches: int, image: Tensor)

Sample random patches from an image.

Parameters:

  • patch_size (int) – Patch side length.

  • num_patches (int) – Number of patches to sample.

  • image (Tensor, shape [*, C, H, W]) – where: C is the number of channels, H is the image height, W is the image width.

Returns:

patches – Sampled patches from the input image(s).

Return type:

Tensor, shape [num_patches, C, patch_size, patch_size]

sparsecoding.transforms.images.whiten_channel(channel: Tensor, filt: Tensor, target_variance: float = 1.0) → Tensor

Apply frequency domain whitening to a single channel.

Parameters:

  • channel (torch.Tensor) – Single channel image tensor

  • filt (torch.Tensor) – Frequency domain filter

  • target_variance (float, default=1.0) – Target variance for normalization

Returns:

torch.Tensor

Return type:

Whitened channel

sparsecoding.transforms.images.whiten_images(images: Tensor, algorithm: str, stats: Dict | None = None, **kwargs) → Tensor

Wrapper for all whitening transformations

Parameters:

  • images (torch.Tensor) – Tensor of shape (N, C, H, W)

  • algorithm (str) – What whitening transform we want to use

  • stats (Dict, default=None) – Dictionary of dataset statistics needed for whitening transformations

Return type:

Tensor of whitened data in shape (N, C, H, W)

sparsecoding.transforms.images_test module

sparsecoding.transforms.images_test.test_patchify_quilt_cycle()
sparsecoding.transforms.images_test.test_sample_random_patches()

sparsecoding.transforms.whiten module

sparsecoding.transforms.whiten.compute_whitening_stats(X: Tensor)

Given a tensor of data, compute statistics for whitening transform.

Parameters:

X (torch.Tensor) – Input data of size [N, D]

Return type:

Dictionary containing whitening statistics (eigenvalues, eigenvectors, mean)

sparsecoding.transforms.whiten.whiten(X: Tensor, algorithm: str = 'zca', stats: Dict | None = None, n_components: float | None = None, epsilon: float = 0.0, return_W: bool = False) → Tensor

Apply whitening transform to data using pre-computed statistics.

Parameters:

  • X (torch.Tensor) – Input data of shape [N, D] where N are unique data elements of dimensionality D

  • algorithm (str, default="zca") – Whitening transform we want to apply, one of [‘zca’, ‘pca’, or ‘cholesky’]

  • stats (Dict, default=None) – Dict containing precomputed whitening statistics (mean, eigenvectors, eigenvalues)

  • n_components (float, int, default=None) – Number of principal components to keep. If None, keep all components. If int, keep that many components. If float between 0 and 1, keep components that explain that fraction of variance.

  • epsilon (float, default=0.0) – Optional small constant to prevent division by zero

Return type:

Whitened data of shape [N, D]

Notes

See examples/Data_Whitening.ipynb for usage examples, and brief discussion about the different whitening methods

See https://arxiv.org/abs/1512.00809 for extensive details on whitening transformations - Possible TODO: Also gives two additional transforms that have not been implemented

See https://stats.stackexchange.com/questions/117427/what-is-the-difference-between-zca-whitening-and-pca-whitening for details on PCA and ZCA in particular

sparsecoding.transforms.whiten_test module

sparsecoding.transforms.whiten_test.test_cholesky()
sparsecoding.transforms.whiten_test.test_pca()
sparsecoding.transforms.whiten_test.test_zca()