naginterfaces.library.mv.cluster_​kmeans

naginterfaces.library.mv.cluster_kmeans(x, isx, cmeans, wt=None, maxit=10)

cluster_kmeans performs $K$-means cluster analysis.

For full information please refer to the NAG Library document for g03ef

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g03/g03eff.html

Parameters

xfloat, array-like, shape $(n,m)$

$x[\text{i}-1,\text{j}-1]$ must contain the value of the $\text{j}$th variable for the $\text{i}$th object, for $\text{j}=1,2,\dots ,m$, for $\text{i}=1,2,\dots ,n$.

isxint, array-like, shape $\left(m\right)$

$isx[\text{j}-1]$ indicates whether or not the $\text{j}$th variable is to be included in the analysis. If $isx[\text{j}-1]>0$, the variable contained in the $\text{j}$th column of $x$ is included, for $\text{j}=1,2,\dots ,m$.

cmeansfloat, array-like, shape $(k,\text{nvar})$

$cmeans[\text{i}-1,\text{j}-1]$ must contain the value of the $\text{j}$th variable for the $\text{i}$th initial cluster centre, for $\text{j}=1,2,\dots ,p$, for $\text{i}=1,2,\dots ,K$.

wtNone or float, array-like, shape $\left(n\right)$, optional

If $wt\text{is not}None$, the first $n$ elements of $wt$ must contain the weights to be used.

If $wt[i-1]=0.0$, the $i$th observation is not included in the analysis.

The effective number of observation is the sum of the weights.

If $wt\text{is}None$, $wt$ is not referenced and the effective number of observations is $n$.

maxitint, optional

The maximum number of iterations allowed in the analysis.

Returns

cmeansfloat, ndarray, shape $(k,\text{nvar})$

$cmeans[\text{i}-1,\text{j}-1]$ contains the value of the $\text{j}$th variable for the $\text{i}$th computed cluster centre, for $\text{j}=1,2,\dots ,p$, for $\text{i}=1,2,\dots ,K$.

incint, ndarray, shape $\left(n\right)$

$inc[\text{i}-1]$ contains the cluster to which the $\text{i}$th object has been allocated, for $\text{i}=1,2,\dots ,n$.

nicint, ndarray, shape $\left(k\right)$

$nic[\text{i}-1]$ contains the number of objects in the $\text{i}$th cluster, for $\text{i}=1,2,\dots ,K$.

cssfloat, ndarray, shape $\left(k\right)$

$css[\text{i}-1]$ contains the within-cluster (weighted) sum of squares of the $\text{i}$th cluster, for $\text{i}=1,2,\dots ,K$.

cswfloat, ndarray, shape $\left(k\right)$

$csw[\text{i}-1]$ contains the within-cluster sum of weights of the $\text{i}$th cluster, for $\text{i}=1,2,\dots ,K$. If $\text{weight}=\text{'U'}$, the sum of weights is the number of objects in the cluster.

Raises

NagValueError

(errno $1$)

On entry, $maxit=⟨value⟩$.

Constraint: $maxit>0$.

(errno $1$)

On entry, $k=⟨value⟩$.

Constraint: $k\ge 2$.

(errno $1$)

On entry, $m=⟨value⟩$ and $\text{nvar}=⟨value⟩$.

Constraint: $m\ge \text{nvar}$.

(errno $1$)

On entry, $\text{nvar}=⟨value⟩$.

Constraint: $\text{nvar}\ge 1$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n>1$.

(errno $1$)

On entry, $\text{weight}=⟨value⟩$.

Constraint: $\text{weight}=\text{'U'}$ or $\text{'W'}$.

(errno $2$)

On entry, $wt$ has less than two positive values.

(errno $2$)

On entry, $i=⟨value⟩$ and $wt[i-1]<0.0$.

Constraint: $wt[i-1]\ge 0.0$.

(errno $3$)

On entry, $\text{nvar}=⟨value⟩$ and $⟨value⟩$ values of $isx>0$.

Constraint: exactly $\text{nvar}$ elements of $isx>0$.

(errno $4$)

At least one cluster is empty after the initial assignment.

(errno $5$)

Convergence has not been achieved within the maximum number of iterations $maxit=⟨value⟩$.

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

Given $n$ objects with $p$ variables measured on each object, $x_{\text{i}\text{j}}$, for $\text{j}=1,2,\dots ,p$, for $\text{i}=1,2,\dots ,n$, cluster_kmeans allocates each object to one of $K$ groups or clusters to minimize the within-cluster sum of squares:

$$\sum _{k=1}^K\sum _{i\in S_k}\sum _{j=1}^p{(x_{ij}-{\overline{x}}_{kj})}^2\text{,}$$

where $S_k$ is the set of objects in the $k$th cluster and ${\overline{x}}_{kj}$ is the mean for the variable $j$ over cluster $k$. This is often known as $K$-means clustering.

In addition to the data matrix, a $K\times p$ matrix giving the initial cluster centres for the $K$ clusters is required. The objects are then initially allocated to the cluster with the nearest cluster mean. Given the initial allocation, the procedure is to iteratively search for the $K$-partition with locally optimal within-cluster sum of squares by moving points from one cluster to another.

Optionally, weights for each object, $w_i$, can be used so that the clustering is based on within-cluster weighted sums of squares:

$$\sum _{k=1}^K\sum _{i\in S_k}\sum _{j=1}^p{w}_i{(x_{ij}-{\tilde{x}}_{kj})}^2\text{,}$$

where ${\tilde{x}}_{kj}$ is the weighted mean for variable $j$ over cluster $k$.

The function is based on the algorithm of Hartigan and Wong (1979).

References

Everitt, B S, 1974, Cluster Analysis, Heinemann

Hartigan, J A and Wong, M A, 1979, Algorithm AS 136: A K-means clustering algorithm, Appl. Statist. (28), 100–108

Kendall, M G and Stuart, A, 1976, The Advanced Theory of Statistics (Volume 3), (3rd Edition), Griffin

Krzanowski, W J, 1990, Principles of Multivariate Analysis, Oxford University Press

See also

naginterfaces.library.examples.mv.cluster_kmeans_ex.main()