pccdr 1.0.2

Dimensionality reduction by preserving clusters and correlations.

PCC - Dimensionality reduction with very high global structure preservation

PrePrint: https://arxiv.org/abs/2503.07609 Authors: Jacob Gildenblat, Jens Pahnke

pip install pccdr

from pcc import PCUMAP
pcumap_embedding = PCUMAP(device='cuda').fit_transform(X)

⭐ This is a python package for dimensionality reduction (DR) with high global structure preservation.

⭐ That means that unlike in popular DR methods like UMAP, the distances between transformed points - will actually mean something.

⭐ Use PCUMAP for simply enhancing the widely used UMAP method with global structure preservation.

⭐ Or use it with our own PCC objective that resutls with extremely high global structure preservation, and competitive local structure.

(For spearman correlation support, install torchsort (pip install torchsort))

A few visual examples

Image	Description
	An example on the Fashion-Mnist dataset
	An application on Mass Spectometry Imaging
	An application illustarting the global structure preservation on the Macosko single cell dataset compared to UMAP

PCC is built on the idea of sampling reference points, meausring distances of all data points from the reference points, and maximizing the correlations of these distances in the high dimensional data, and the transformed low dimensional data.

Usage examples

See examples/macosko.ipynb for more detailed explanation and usage examples.

There are two modes:

Plugging into UMAP, for getting a meaningful transformation where distances between points mean something

Here we use the excellent recent TorchDR library, and add plug in our objective into UMAP.

from pcc import PCUMAP
pcumap_embedding = PCUMAP(device='cuda').fit_transform(X)

PCC as a standalone DR method with a multi task objective

This optimizes a local structure preservation multi task objective that tries to predict which clusters points belong to, as well as global structure preservation loss that maximizes corerlations between distances of all points to sampled reference points.

First, lets cluster the points with different clustering models:

np.random.seed(0)

clusters = []
n_clusters_list = [4, 8, 16, 32, 64]
for n_clusters in n_clusters_list:
    kmeans = KMeans(n_clusters=n_clusters, random_state=0, n_init="auto")
    cluster_labels = kmeans.fit_predict(X)
    clusters.append(cluster_labels)

Then we can call PCC:

pcc_reducer = PCC(num_components=2, num_epochs=2000, num_points=1000, pearson=True, 
                  spearman=False, beta=5, k_epoch=2)
pcc_embedding = pcc_reducer.fit_transform(X, clusters)