peal.sparse_dictionaries.splice_decomposition.SpLICEDecomposition

class peal.sparse_dictionaries.splice_decomposition.SpLICEDecomposition

Bases: SparseDictionary

Sparse dictionary using SpLICE for concept decomposition.

Wraps the SpLICE library to decompose CLIP image embeddings into sparse nonnegative weights over a vocabulary of text concepts. This serves as the disentangled dictionary for the DiDAE framework when using pretrained foundation models.

No training is required — SpLICE uses a pretrained CLIP vocabulary dictionary and an L1-regularized solver at inference time. The only data-dependent step is computing the dataset-specific image mean via fit_from_dataloaders().

Methods

decompose	Sparse concept weights of CLIP image embeddings.
fit	Set the dataset-specific image mean from precomputed embeddings.
fit_from_dataloaders	Compute dataset-specific image mean using the CLIP encoder.
get_components	The concept dictionary as a CPU tensor of shape [D, n_components].
get_vocabulary	Get the text vocabulary used by SpLICE.
load_from_disk	Load saved SpLICE decomposition state.
recompose	Reconstruct image embeddings from concept weights.
save_on_disk	Save the SpLICE decomposition state (image mean + config).
set_clip_model	Inject an external CLIP model to ensure identity with the generator.

Attributes

config

__init__(config=pydantic.BaseModel)

Store the config; the SpLICE model itself is loaded lazily.

Parameters:

config (SpLICEDecompositionConfig) – Backbone, vocabulary and solver settings.

set_clip_model(clip_model)

Inject an external CLIP model to ensure identity with the generator.

Parameters:

clip_model – The loaded CLIP model instance (must be ViT-L/14)

fit(X, y=None)

Set the dataset-specific image mean from precomputed embeddings.

Parameters:

• X (torch.Tensor) – CLIP image embeddings [N, D]; their mean replaces SpLICE’s internet-scale image_mean. Ignored when None or empty.

• y (torch.Tensor, optional) – Unused; accepted for interface compatibility.

fit_from_dataloaders(dataloaders, feature_extractor)

Compute dataset-specific image mean using the CLIP encoder. This replaces SpLICE’s generic internet-scale mean with a domain-specific mean, improving decomposition quality for the target dataset.

Parameters:

• dataloaders – List of dataloaders providing (image, label) batches

• feature_extractor – The CLIP image encoder (nn.Module)

decompose(embeddings)

Sparse concept weights of CLIP image embeddings.

The embeddings are L2-normalised, centred by the image mean, re-normalised and passed to splice_model.decompose.

Parameters:

embeddings (torch.Tensor) – CLIP image embeddings [N, D] on any device.

Returns:

Non-negative weights [N, n_components] on self.device.

Return type:

torch.Tensor

recompose(weights)

Reconstruct image embeddings from concept weights.

Parameters:

weights (torch.Tensor) – Concept weights [N, n_components] as returned by decompose().

Returns:

Reconstructed (mean-added, normalised) embeddings [N, D].

Return type:

torch.Tensor

get_components()

The concept dictionary as a CPU tensor of shape [D, n_components].

Returns:

One column per vocabulary concept, i.e. the transposed SpLICE dictionary.

Return type:

torch.Tensor

save_on_disk(path)

Save the SpLICE decomposition state (image mean + config).

load_from_disk(path)

Load saved SpLICE decomposition state.

get_vocabulary()

Get the text vocabulary used by SpLICE.

Returns:

list of concept word strings

Return type:

vocab