Integer, Intent (In)	::	n, m, ldx, isx(m), nvar, k, ldc, maxit
Integer, Intent (Inout)	::	ifail
Integer, Intent (Out)	::	inc(n), nic(k), iwk(n+3*k)
Real (Kind=nag_wp), Intent (In)	::	x(ldx,m), wt(*)
Real (Kind=nag_wp), Intent (Inout)	::	cmeans(ldc,nvar)
Real (Kind=nag_wp), Intent (Out)	::	css(k), csw(k), wk(n+2*k)
Character (1), Intent (In)	::	weight

C Header Interface

#include nagmk26.h

void

g03eff_ ( const char *weight, const Integer *n, const Integer *m, const double x[], const Integer *ldx, const Integer isx[], const Integer *nvar, const Integer *k, double cmeans[], const Integer *ldc, const double wt[], Integer inc[], Integer nic[], double css[], double csw[], const Integer *maxit, Integer iwk[], double wk[], Integer *ifail, const Charlen length_weight)

3

Description

Given

n

objects with

p

variables measured on each object,

x_{i j}

, for

i = 1, 2, \dots, n

and

j = 1, 2, \dots, p

, g03eff 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_{i j} - {\bar{x}}_{k j})}^{2},

where

S_{k}

is the set of objects in the

k

th cluster and

{\bar{x}}_{k j}

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

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_{i j} - {\tilde{x}}_{k j})}^{2},

where

{\tilde{x}}_{k j}

is the weighted mean for variable

j

over cluster

k

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

4

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

5

Arguments

1: $weight$ – Character(1)Input

On entry: indicates if weights are to be used.

$weight ='U'$: No weights are used.
$weight ='W'$: Weights are used and must be supplied in wt.

Constraint:

weight ='U'

'W'

2: $n$ – IntegerInput

On entry:

n

, the number of objects.

Constraint:

n > 1

3: $m$ – IntegerInput

On entry: the total number of variables in array x.

Constraint:

m \geq nvar

4: $x (ldx, m)$ – Real (Kind=nag_wp) arrayInput

On entry:

x (i, j)

must contain the value of the

j

th variable for the

i

th object, for

i = 1, 2, \dots, n

and

j = 1, 2, \dots, m

5: $ldx$ – IntegerInput

On entry: the first dimension of the array x as declared in the (sub)program from which g03eff is called.

Constraint:

ldx \geq n

6: $isx (m)$ – Integer arrayInput

On entry:

isx (j)

indicates whether or not the

j

th variable is to be included in the analysis. If

isx (j) > 0

, the variable contained in the

j

th column of x is included, for

j = 1, 2, \dots, m

Constraint:

isx (j) > 0

for nvar values of

j

7: $nvar$ – IntegerInput

On entry:

p

, the number of variables included in the sums of squares calculations.

Constraint:

1 \leq nvar \leq m

8: $k$ – IntegerInput

On entry:

K

, the number of clusters.

Constraint:

k \geq 2

9: $cmeans (ldc, nvar)$ – Real (Kind=nag_wp) arrayInput/Output

On entry:

cmeans (i, j)

must contain the value of the

j

th variable for the

i

th initial cluster centre, for

i = 1, 2, \dots, K

and

j = 1, 2, \dots, p

On exit:

cmeans (i, j)

contains the value of the

j

th variable for the

i

th computed cluster centre, for

i = 1, 2, \dots, K

and

j = 1, 2, \dots, p

10: $ldc$ – IntegerInput

On entry: the first dimension of the array cmeans as declared in the (sub)program from which g03eff is called.

Constraint:

ldc \geq k

11: $wt (*)$ – Real (Kind=nag_wp) arrayInput

Note: the dimension of the array wt must be at least

n

weight ='W'

, and at least

1

otherwise.

On entry: if

weight ='W'

, the first

n

elements of wt must contain the weights to be used.

wt (i) = 0.0

, the

i

th observation is not included in the analysis. The effective number of observation is the sum of the weights.

weight ='U'

, wt is not referenced and the effective number of observations is

n

Constraint: if

weight ='W'

wt (i) \geq 0.0

and

wt (i) > 0.0

for at least two values of

i

, for

i = 1, 2, \dots, n

12: $inc (n)$ – Integer arrayOutput

On exit:

inc (i)

contains the cluster to which the

i

th object has been allocated, for

i = 1, 2, \dots, n

13: $nic (k)$ – Integer arrayOutput

On exit:

nic (i)

contains the number of objects in the

i

th cluster, for

i = 1, 2, \dots, K

14: $css (k)$ – Real (Kind=nag_wp) arrayOutput

On exit:

css (i)

contains the within-cluster (weighted) sum of squares of the

i

th cluster, for

i = 1, 2, \dots, K

15: $csw (k)$ – Real (Kind=nag_wp) arrayOutput

On exit:

csw (i)

contains the within-cluster sum of weights of the

i

th cluster, for

i = 1, 2, \dots, K

. If

weight ='U'

, the sum of weights is the number of objects in the cluster.

16: $maxit$ – IntegerInput

On entry: the maximum number of iterations allowed in the analysis.

Suggested value:

maxit = 10

Constraint:

maxit > 0

17: $iwk (n + 3 \times k)$ – Integer arrayWorkspace

18: $wk (n + 2 \times k)$ – Real (Kind=nag_wp) arrayWorkspace

19: $ifail$ – IntegerInput/Output

On entry: ifail must be set to

0

- 1 ​ or ​ 1

. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value

- 1 ​ or ​ 1

is recommended. If the output of error messages is undesirable, then the value

1

is recommended. Otherwise, if you are not familiar with this argument, the recommended value is

0

. When the value $- 1 or 1$ is used it is essential to test the value of ifail on exit.

On exit:

ifail = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6

Error Indicators and Warnings

If on entry

ifail = 0

- 1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = 1$

On entry,	$weight \neq'W'$ or $'U'$ ,
or	$n < 2$ ,
or	$nvar < 1$ ,
or	$m < nvar$ ,
or	$k < 2$ ,
or	$ldx < n$ ,
or	$ldc < k$ ,
or	$maxit \leq 0$ .

$ifail = 2$

On entry,	$weight ='W'$ and a value of $wt (i) < 0.0$ for some $i$ ,
or	$weight ='W'$ and $wt (i) = 0.0$ for all or all but one values of $i$ .

$ifail = 3$

On entry,

the number of positive values in isx does not equal nvar.

$ifail = 4$: On entry, at least one cluster is empty after the initial assignment. Try a different set of initial cluster centres in cmeans and also consider decreasing the value of k. The empty clusters may be found by examining the values in nic.

$ifail = 5$: Convergence has not been achieved within the maximum number of iterations given by maxit. Try increasing maxit and, if possible, use the returned values in cmeans as the initial cluster centres.

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

g03eff produces clusters that are locally optimal; the within-cluster sum of squares may not be decreased by transferring a point from one cluster to another, but different partitions may have the same or smaller within-cluster sum of squares.

8

Parallelism and Performance

g03eff is not threaded in any implementation.

9

Further Comments

The time per iteration is approximately proportional to

np K

10

Example

The data consists of observations of five variables on twenty soils (see Hartigan and Wong (1979)). The data is read in, the

K

-means clustering performed and the results printed.

NAG Library Routine Document

g03eff (cluster_kmeans)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

6

Error Indicators and Warnings

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

10.2

Program Data

10.3

Program Results