API

Subspace clustering module. Provides algorithms for clustering data points by subspace.

KSSResult{
    TU<:AbstractVector{<:AbstractMatrix{<:AbstractFloat}},
    Tc<:AbstractVector{<:Integer},
    T<:Real}

The output of kss.

Fields

• U::TU: vector of subspace basis matrices U[1],...,U[K]
• c::Tc: vector of cluster assignments c[1],...,c[N]
• iterations::Int: number of iterations performed
• totalcost::T: final value of total cost function
• counts::Vector{Int}: vector of cluster sizes counts[1],...,counts[K]
• converged::Bool: final convergence status

kss(X::AbstractMatrix{<:Real}, d::AbstractVector{<:Integer};
    maxiters = 100,
    rng = default_rng(),
    Uinit = [randsubspace(rng, size(X, 1), di) for di in d])

Cluster the N data points in the D×N data matrix X into K clusters via the K-subspaces (KSS) algorithm with corresponding subspace dimensions d[1],...,d[K]. Output is a KSSResult containing the resulting cluster assignments c[1],...,c[N], subspace basis matrices U[1],...,U[K], and metadata about the algorithm run.

KSS seeks to cluster data points by their subspace by minimizing the following total cost

\[\sum_{i=1}^N \| X[:, i] - U[c[i]] U[c[i]]' X[:, i] \|_2^2\]

with respect to the cluster assignments c[1],...,c[N] and subspace basis matrices U[1],...,U[K].

Keyword arguments

• maxiters::Integer = 100: maximum number of iterations
• rng::AbstractRNG = default_rng(): random number generator (used when reinitializing the subspace for an empty cluster)
• Uinit::AbstractVector{<:AbstractMatrix{<:AbstractFloat}} = [randsubspace(rng, size(X, 1), di) for di in d]: vector of K initial subspace basis matrices to use (each Uinit[k] should be D×d[k])

See also KSSResult.

kss_assign_clusters!(c, U, X)

Assign the N data points in X to the K subspaces in U, update the vector of assignments c, and return this vector of assignments.

See also kss_assign_clusters, kss.

kss_assign_clusters(U, X)

Assign the N data points in X to the K subspaces in U and return a vector of the assignments.

See also kss_assign_clusters!, kss.

kss_estimate_subspace(Xk, dk)

Return dk-dimensional subspace that best fits the data points in Xk.

See also kss.

randsubspace!([rng=default_rng()], U::AbstractMatrix)

Set the D×d matrix U to be the basis matrix of a randomly generated d-dimensional subspace of ℝᴰ.

See also randsubspace

randsubspace([rng=default_rng()], [T=Float64], D, d)

Generate a random d-dimensional subspace of ℝᴰ and return a basis matrix with element type T<:AbstractFloat.

See also randsubspace!