NAG Library Routine Document
G03EFF
1 Purpose
G03EFF performs -means cluster analysis.
2 Specification
SUBROUTINE G03EFF ( |
WEIGHT, N, M, X, LDX, ISX, NVAR, K, CMEANS, LDC, WT, INC, NIC, CSS, CSW, MAXIT, IWK, WK, IFAIL) |
INTEGER |
N, M, LDX, ISX(M), NVAR, K, LDC, INC(N), NIC(K), MAXIT, IWK(N+3*K), IFAIL |
REAL (KIND=nag_wp) |
X(LDX,M), CMEANS(LDC,NVAR), WT(*), CSS(K), CSW(K), WK(N+2*K) |
CHARACTER(1) |
WEIGHT |
|
3 Description
Given
objects with
variables measured on each object,
, for
and
, G03EFF allocates each object to one of
groups or clusters to minimize the within-cluster sum of squares:
where
is the set of objects in the
th cluster and
is the mean for the variable
over cluster
. This is often known as
-means clustering.
In addition to the data matrix, a by matrix giving the initial cluster centres for the 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 -partition with locally optimal within-cluster sum of squares by moving points from one cluster to another.
Optionally, weights for each object,
, can be used so that the clustering is based on within-cluster weighted sums of squares:
where
is the weighted mean for variable
over cluster
.
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 Parameters
- 1: WEIGHT – CHARACTER(1)Input
On entry: indicates if weights are to be used.
- No weights are used.
- Weights are used and must be supplied in WT.
Constraint:
or .
- 2: N – INTEGERInput
On entry: , the number of objects.
Constraint:
.
- 3: M – INTEGERInput
On entry: the total number of variables in array
X.
Constraint:
.
- 4: X(LDX,M) – REAL (KIND=nag_wp) arrayInput
On entry: must contain the value of the th variable for the th object, for and .
- 5: LDX – INTEGERInput
On entry: the first dimension of the array
X as declared in the (sub)program from which G03EFF is called.
Constraint:
.
- 6: ISX(M) – INTEGER arrayInput
On entry:
indicates whether or not the
th variable is to be included in the analysis. If
, the variable contained in the
th column of
X is included, for
.
Constraint:
for
NVAR values of
.
- 7: NVAR – INTEGERInput
On entry: , the number of variables included in the sums of squares calculations.
Constraint:
.
- 8: K – INTEGERInput
On entry: , the number of clusters.
Constraint:
.
- 9: CMEANS(LDC,NVAR) – REAL (KIND=nag_wp) arrayInput/Output
On entry: must contain the value of the th variable for the th initial cluster centre, for and .
On exit: contains the value of the th variable for the th computed cluster centre, for and .
- 10: LDC – INTEGERInput
On entry: the first dimension of the array
CMEANS as declared in the (sub)program from which G03EFF is called.
Constraint:
.
- 11: WT() – REAL (KIND=nag_wp) arrayInput
-
Note: the dimension of the array
WT
must be at least
if
, and at least
otherwise.
On entry: if
, the first
elements of
WT must contain the weights to be used.
If , the th observation is not included in the analysis. The effective number of observation is the sum of the weights.
If
,
WT is not referenced and the effective number of observations is
.
Constraint:
if , and for at least two values of , for .
- 12: INC(N) – INTEGER arrayOutput
On exit: contains the cluster to which the th object has been allocated, for .
- 13: NIC(K) – INTEGER arrayOutput
On exit: contains the number of objects in the th cluster, for .
- 14: CSS(K) – REAL (KIND=nag_wp) arrayOutput
On exit: contains the within-cluster (weighted) sum of squares of the th cluster, for .
- 15: CSW(K) – REAL (KIND=nag_wp) arrayOutput
On exit: contains the within-cluster sum of weights of the th cluster, for . If , 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:
.
Constraint:
.
- 17: IWK() – INTEGER arrayWorkspace
- 18: WK() – REAL (KIND=nag_wp) arrayWorkspace
- 19: IFAIL – INTEGERInput/Output
-
On entry:
IFAIL must be set to
,
. If you are unfamiliar with this parameter you should refer to
Section 3.3 in the Essential Introduction for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
is recommended. If the output of error messages is undesirable, then the value
is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is
.
When the value is used it is essential to test the value of IFAIL on exit.
On exit:
unless the routine detects an error or a warning has been flagged (see
Section 6).
6 Error Indicators and Warnings
If on entry
or
, explanatory error messages are output on the current error message unit (as defined by
X04AAF).
Errors or warnings detected by the routine:
On entry, | or , |
or | , |
or | , |
or | , |
or | , |
or | , |
or | , |
or | . |
On entry, | and a value of for some , |
or | and for all or all but one values of . |
On entry, | the number of positive values in ISX does not equal NVAR. |
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.
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.
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.
The time per iteration is approximately proportional to .
9 Example
The data consists of observations of five variables on twenty soils (see
Hartigan and Wong (1979)). The data is read in, the
-means clustering performed and the results printed.
9.1 Program Text
Program Text (g03effe.f90)
9.2 Program Data
Program Data (g03effe.d)
9.3 Program Results
Program Results (g03effe.r)