pgcuts.graph

Graph construction and similarity computation.

Main pipeline

pgcuts.graph.build_rbf_knn_graph(features, n_neighbors=100)[source]

Build an RBF-weighted KNN graph.

Pipeline: KNN distances -> row-normalize -> scale by degree -> Gaussian RBF -> symmetrize.

Parameters:

  • features (ndarray) – Data matrix, shape (n, d).

  • n_neighbors (int) – Number of nearest neighbors.

Returns:

Sparse symmetric similarity matrix.

Return type:

csr_matrix

Building blocks

pgcuts.graph.knn_graph(features, n_neighbors=10, mode='distance', metric='minkowski')[source]

Build a symmetric sparse KNN graph.

Parameters:

  • features (ndarray) – Data matrix, shape (n, d).

  • n_neighbors (int) – Number of nearest neighbors.

  • mode (str) – “distance” or “connectivity”.

  • metric (str) – Distance metric.

Returns:

Symmetric sparse distance/connectivity matrix.

Return type:

csr_matrix

pgcuts.graph.gaussian_rbf_kernel(distances, sigma=None)[source]

Convert sparse distances to Gaussian RBF.

Parameters:

  • distances (spmatrix) – Sparse distance matrix.

  • sigma (float) – Bandwidth. If None, uses median of max distances per row.

Returns:

Sparse similarity matrix.

Return type:

csr_matrix

pgcuts.graph.symmetrize(w_mat)[source]

Symmetrize a sparse matrix: (W + W^T) / 2.

Parameters:

w_mat (spmatrix)

Return type:

csr_matrix

Cross-set similarities

pgcuts.graph.get_knn_distances(x_left, x_right, num_neighbors, mode='distance', metric='minkowski')[source]

Compute mutual KNN distances between two sets.

Parameters:

  • x_left (ndarray) – Left point set, shape (n1, d).

  • x_right (ndarray) – Right point set, shape (n2, d).

  • num_neighbors (int) – Number of neighbors.

  • mode (str) – “distance” or “connectivity”.

  • metric (str) – Distance metric.

Returns:

Symmetric sparse distance matrix.

Return type:

csr_matrix

pgcuts.graph.sp_knn_similarity(x_left, x_right, num_neighbors, mode='distance', metric='minkowski')[source]

Build sparse KNN similarity between two sets.

Parameters:

  • x_left (ndarray) – Left point set, shape (n1, d).

  • x_right (ndarray) – Right point set, shape (n2, d).

  • num_neighbors (int) – Number of neighbors.

  • mode (str) – “distance” or “connectivity”.

  • metric (str) – Distance metric.

Returns:

Sparse similarity matrix.

Return type:

csr_matrix

pgcuts.graph.torch_knn_similarity(x_left, x_right, num_neighbors, mode='distance', metric='minkowski')[source]

Compute KNN similarity as a dense torch tensor.

Parameters:

  • x_left (Tensor) – Left point set tensor.

  • x_right (Tensor) – Right point set tensor.

  • num_neighbors (int) – Number of neighbors.

  • mode (str) – “distance” or “connectivity”.

  • metric (str) – Distance metric.

Returns:

Dense similarity tensor.

Return type:

Tensor

pgcuts.graph.torch_pairwise_similarities(x1, x2, factor=1.0)[source]

Dense pairwise Gaussian similarity.

Parameters:

  • x1 (Tensor) – First point set, shape (n1, d).

  • x2 (Tensor) – Second point set, shape (n2, d).

  • factor (float) – Bandwidth scaling factor.

Returns:

Similarity matrix, shape (n1, n2).

Return type:

Tensor

pgcuts.graph.compute_sp_similarities(affinity_mat)[source]

Convert sparse distances to Gaussian similarities.

Parameters:

affinity_mat (spmatrix) – Sparse distance matrix.

Returns:

Sparse similarity matrix.

Return type:

csr_matrix

Laplacian

pgcuts.graph.sparse_laplacian(w_mat)[source]

Compute graph Laplacian L = D - W.

Parameters:

w_mat (spmatrix) – Sparse similarity/adjacency matrix.

Returns:

Sparse Laplacian matrix.

Return type:

spmatrix