Geodesic spherical \(k\)-means algorithm is a counterpart of the spherical \(k\)-means algorithm by replacing the cosine similarity with the squared geodesic distance, which is the great-circle distance under the intrinsic geometry regime on the unit hypersphere. If the data is not normalized, it performs the normalization and proceeds thereafter.

gskmeans(data, k = 2, ...)

Arguments

data

a real numeric \((n\times p)\) matrix of row-stacked observations, with \(n\geq 1\) and \(p\geq 2\). Every entry must be finite and every row must be nonzero. Each row is normalized to have unit Euclidean norm.

k

one integer from 1 to nrow(data) (default: 2).

...

named extra parameters, with no duplicates or unknown names:

init

initialization method; "kmeans" or "gmm" (default: "kmeans"). Matching is case-insensitive and accepts unambiguous abbreviations.

maxiter

a positive integer giving the maximum number of outer iterations (default: 10). A value of 1 is honored.

abstol

a finite positive tolerance for change in the outer objective (default: sqrt(.Machine$double.eps), approximately \(1.49\times10^{-8}\)).

verbose

one logical value; TRUE prints iteration information and FALSE suppresses iteration output (default: FALSE). Warnings about nonconvergence are still emitted.

mean.maxiter

a positive integer giving the maximum number of steps for each intrinsic centroid calculation (default: 100).

mean.tol

a finite positive tolerance on the norm of the average logarithmic-map vector for each centroid (default: \(10^{-8}\)).

Value

a named list of S3 class T4cluster containing

cluster

a length-\(n\) integer vector of final class labels, from \(1:k\).

cost

the sum of squared great-circle distances, \(\sum_i d_{\mathbb S}(x_i,\mu_{z_i})^2\), using the returned labels and centers. Lower values are better; no division by \(n\) or factor of \(1/2\) is applied.

means

an \((k\times p)\) matrix of unit-norm centers.

algorithm

name of the algorithm.

converged

whether the algorithm satisfied its convergence checks.

iterations

the number of completed outer iterations.

status

the reason for termination.

labels_stable

whether the final partition agrees with the partition used for the last center update.

objective_history

the initial cost, the cost after each completed outer update, and the final freshly assigned cost. The last value equals cost; the final entry may duplicate its predecessor.

mean_converged

a per-cluster indicator that the average-logarithm residual is at most mean.tol for the returned partition and centers. This is a stationarity diagnostic, not a global-optimality certificate.

mean_iterations

the number of accepted steps in each cluster's last centroid solve; the final residual refresh performs no optimization.

mean_residual

per-cluster norms of the average logarithmic-map vectors, recomputed using the returned labels and centers.

control

the validated control values used for the run.

Details

Assignments minimize the great-circle distance, equivalently maximizing the inner product with a unit center. An empty cluster during initialization, reassignment, or final assignment raises an error; clusters are not silently deleted or revived. Exact assignment ties select the first center.

Coincident points have zero logarithmic map. A required logarithmic map at an antipodal or numerically near-antipodal point raises an error, using a relative tangent-residual threshold of \(10^{-12}\). Antipodal distances themselves remain well-defined. An initial zero resultant uses the first cluster observation as a starting point, which may trigger this explicit antipodal policy. The method does not claim a unique or globally minimizing intrinsic mean for arbitrary dispersed spherical data.

Centroids are updated with damped intrinsic gradient steps and a check that the fixed-cluster objective does not increase. Returned labels are freshly assigned to the returned centers. When converged is FALSE, the centers can be approximate and need not be stationary for the final partition. Inspect both outer and intrinsic solver diagnostics.

Examples

# \donttest{
# -------------------------------------------------------------
#            clustering with 'household' dataset
# -------------------------------------------------------------
## PREPARE
data(household, package="T4cluster")
X   = household$data
lab = as.integer(household$gender)

## EXECUTE GSKMEANS WITH VARYING K's
vec.rand = rep(0, 9)
for (i in 1:9){
  clust_i = gskmeans(X, k=(i+1))$cluster
  vec.rand[i] = compare.rand(clust_i, lab)
}

## VISUALIZE THE RAND INDEX
opar <- par(no.readonly=TRUE)
plot(2:10, vec.rand, type="b", pch=19, ylim=c(0.5, 1),
     ylab="Rand index",xlab="number of clusters",
     main="clustering quality index over varying k's.")

par(opar)
# }