K-Tensors: Clustering Positive Semi-Definite Matrices

Install the Package from PyPI

• Go to the terminal (mac) or command line (windows), copy and paste:pip3 install KTensors or pip3 install KTensors==0.1.7 for a specific version

install the Package from GitHub

• Go to the terminal (mac) or command line (windows), copy and paste:pip3 install git+https://github.com/Hanchao-Zhang/KTensors.git
• Open a python console, copy and paste: from KTensors import KTensors

About the Package

KTensors

KTensors(Psis, K, max_iter=1000).clustering()

input:

• Psis: a 3D array of size (n, p, p) where n is the number of matrices and p is the dimension of the positive semi-definite matrices.
• K: number of clusters
• max_iter: maximum number of iterations, default is 1000, usually finish within 10 iterations

return:

• group: a vector of length n, each element is an index of group membership
• CPCs: K orthonormal basis matrices of size p by p for each cluster
• $\mathbf F$: $\mathbf F = \mathbf B^\top \mathbf\Psi \mathbf B$
• $\text{diag}(\mathbf F)$: $\text{diag}(\mathbf F) = (\mathbf B^\top \mathbf\Psi \mathbf B) \circ \mathbf I$ the diagonal of matrix $\mathbf F$
• centers: Mean of each cluster
• loss: loss function for each iteration

KMetrics

KMetrics(Psis, K, metrics) input:

• Psis: a 3D array of size (n, p, p) where n is the number of matrices and p is the dimension of the positive semi-definite matrices.
• K: number of clusters
• metrics: a string of metrics, including 'euclidean', 'affine_invariant', 'log_euclidean', 'log_det', and 'symmetric_stein'.

output:

• a vector of length n, each element is an index of group membership
• loss function for each iteration

Some Tecnical Details

Loss Function

$$\begin{aligned}\mathcal L(\mathbf \Psi, \mathcal P_{\mathbf B} (\mathbf \Psi) ) = \Vert \mathbf \Psi - \mathbf B((\mathbf B^\top \mathbf \Psi \mathbf B) \circ \mathbb I )\mathbf B^\top \Vert_F^2 = \Vert\mathbf B^\top \mathbf \Psi \mathbf B - (\mathbf B^\top \mathbf \Psi \mathbf B)\circ \mathbb I \Vert_F^2 \end{aligned}$$

where $\mathbb I$ is a identity matrix, and $\circ$ is the Hadamard product.

For more technical details, please refer to the paper.