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, ...)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.
one integer from 1 to nrow(data) (default: 2).
named extra parameters, with no duplicates or unknown names:
initialization method; "kmeans" or "gmm"
(default: "kmeans"). Matching is case-insensitive and accepts
unambiguous abbreviations.
a positive integer giving the maximum number of outer iterations (default: 10). A value of 1 is honored.
a finite positive tolerance for change in the outer objective
(default: sqrt(.Machine$double.eps), approximately \(1.49\times10^{-8}\)).
one logical value; TRUE prints iteration information
and FALSE suppresses iteration output (default: FALSE).
Warnings about nonconvergence are still emitted.
a positive integer giving the maximum number of steps for each intrinsic centroid calculation (default: 100).
a finite positive tolerance on the norm of the average logarithmic-map vector for each centroid (default: \(10^{-8}\)).
a named list of S3 class T4cluster containing
a length-\(n\) integer vector of final class labels, from \(1:k\).
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.
an \((k\times p)\) matrix of unit-norm centers.
name of the algorithm.
whether the algorithm satisfied its convergence checks.
the number of completed outer iterations.
the reason for termination.
whether the final partition agrees with the partition used for the last center update.
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.
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.
the number of accepted steps in each cluster's last centroid solve; the final residual refresh performs no optimization.
per-cluster norms of the average logarithmic-map vectors, recomputed using the returned labels and centers.
the validated control values used for the run.
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.
# \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)
# }