Geometry module

Geometry module.

MARBLE.geometry.furthest_point_sampling(x, N=None, spacing=0.0, start_idx=0)

A greedy O(N^2) algorithm to do furthest points sampling

Parameters:

• x (nxdim matrix) – input data

• N (int) – number of sampled points

• stop_crit – when reaching this fraction of the total manifold diameter, we stop sampling

• start_idx – index of starting node

Returns:

node indices of the N sampled points lambdas: list of distances of furthest points

Return type:

perm

MARBLE.geometry.cluster(x, cluster_typ='kmeans', n_clusters=15, seed=0)

Cluster data.

Parameters:

• x (nxdim matrix)

• cluster_typ – Clustering method.

• n_clusters – Number of clusters.

• seed – seed

Returns:

sklearn cluster object

Return type:

clusters

MARBLE.geometry.embed(x, embed_typ='umap', dim_emb=2, manifold=None, verbose=True, seed=0, **kwargs)

Embed data to 2D space.

Parameters:

• x (nxdim matrix) – data

• embed_typ – embedding method. The default is ‘tsne’.

Returns:

embedded data

Return type:

emb (nx2 matrix)

MARBLE.geometry.relabel_by_proximity(clusters)

Update clusters labels such that nearby clusters in the embedding get similar labels.

Parameters:

clusters – sklearn object containing ‘centroids’, ‘n_clusters’, ‘labels’ as attributes

Returns:

sklearn object with updated labels

Return type:

clusters

MARBLE.geometry.compute_distribution_distances(clusters=None, data=None, slices=None)

Compute the distance between clustered distributions across datasets.

Parameters:

clusters – sklearn object containing ‘centroids’, ‘slices’, ‘labels’ as attributes

Returns:

distance matrix gamma: optimal transport matrix centroid_distances: distances between cluster centroids

Return type:

dist

MARBLE.geometry.neighbour_vectors(pos, edge_index)

Local out-going edge vectors around each node.

Parameters:

• pos (nxdim matrix) – node positions

• edge_index (2xE matrix) – edge indices

Returns:

neighbourhood vectors.

Return type:

nvec (Exdim matrix)

MARBLE.geometry.project_gauge_to_neighbours(nvec, gauges, edge_index)

Project the gauge vectors to local edge vectors.

Parameters:

• nvec (Exdim matrix) – neighbourhood vectors

• local_gauge (dimxnxdim torch tensor) – if None, global gauge is generated

Returns:

list of (nxn) torch tensors of projected components

MARBLE.geometry.gradient_op(pos, edge_index, gauges)

Directional derivative kernel from Beaini et al. 2021.

Parameters:

• pos (nxdim Matrix)

• edge_index (2x|E| matrix)

• gauge (list) – orthonormal unit vectors

Returns:

list of (nxn) Anisotropic kernels

MARBLE.geometry.normalize_sparse_matrix(sp_tensor)

Normalize sparse matrix.

MARBLE.geometry.global_to_local_frame(x, gauges, length_correction=False, reverse=False)

Transform signal into local coordinates.

MARBLE.geometry.project_to_gauges(x, gauges, dim=2)

Project to gauges.

MARBLE.geometry.manifold_dimension(Sigma, frac_explained=0.9)

Estimate manifold dimension based on singular vectors

MARBLE.geometry.fit_graph(x, graph_type='cknn', par=1, delta=1.0, metric='euclidean')

Fit graph to node positions

MARBLE.geometry.is_connected(edge_index)

Check if it is connected.

MARBLE.geometry.compute_laplacian(data, normalization='rw')

Compute Laplacian.

MARBLE.geometry.compute_connection_laplacian(data, R, normalization='rw')

Connection Laplacian

Parameters:

• data – Pytorch geometric data object.

• R (nxnxdxd) – Connection matrices between all pairs of nodes. Default is None, in case of a global coordinate system.

• normalization –

  None, ‘rw’ 1. None: No normalization \(\mathbf{L} = \mathbf{D} - \mathbf{A}\)

  2. “rw”: Random-walk normalization :math:mathbf{L} = mathbf{I} - mathbf{D}^{-1} mathbf{A}`

Returns:

ndxnd normalised connection Laplacian matrix.

MARBLE.geometry.compute_gauges(data, dim_man=None, n_geodesic_nb=10, processes=1)

Orthonormal gauges for the tangent space at each node.

Parameters:

• data – Pytorch geometric data object.

• n_geodesic_nb – number of geodesic neighbours. The default is 10.

• processes – number of CPUs to use

Returns:

Matrix containing dim unit vectors for each node. Sigma: Singular valued

Return type:

gauges (nxdimxdim matrix)

MARBLE.geometry.compute_connections(data, gauges, processes=1)

Find smallest rotations R between gauges pairs. It is assumed that the first row of edge_index is what we want to align to, i.e., gauges(i) = gauges(j)@R[i,j].T

R[i,j] is optimal rotation that minimises ||X - RY||_F computed by SVD: X, Y = gauges[i].T, gauges[j].T U, _, Vt = scipy.linalg.svd(X.T@Y) R[i,j] = U@Vt

Parameters:

• data – Pytorch geometric data object

• gauges (nxdxd matrix) – Orthogonal unit vectors for each node

• processes – number of CPUs to use

Returns:

(n*dim,n*dim) matrix of rotation matrices

MARBLE.geometry.compute_eigendecomposition(A, k=None, eps=1e-08)

Eigendecomposition of a square matrix A.

Parameters:

• A – square matrix A

• k – number of eigenvectors

• eps – small error term

Returns:

eigenvalues of the Laplacian evecs (V,k): matrix of eigenvectors of the Laplacian

Return type:

evals (k)