NAG C Library Function Document

nag_mv_cluster_indicator (g03ejc)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:    $\mathbf{n}$ – IntegerInput

On entry: the number of objects, $n$.

Constraint: $\mathbf{n}\ge 2$.

2:    $\mathbf{cd}\left[\mathbf{n}-1\right]$ – const doubleInput

On entry: the clustering distances in increasing order as returned by nag_mv_hierar_cluster_analysis (g03ecc).

Constraint: $\mathbf{cd}\left[\mathit{i}\right]\ge \mathbf{cd}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,\mathbf{n}-2$.

3:    $\mathbf{iord}\left[\mathbf{n}\right]$ – const IntegerInput

On entry: the objects in the dendrogram order as returned by nag_mv_hierar_cluster_analysis (g03ecc).

4:    $\mathbf{dord}\left[\mathbf{n}\right]$ – const doubleInput

On entry: the clustering distances corresponding to the order in iord.

5:    $\mathbf{k}$ – Integer *Input/Output

On entry: indicates if a specified number of clusters is required.

$\mathbf{k}>0$

nag_mv_cluster_indicator (g03ejc) will attempt to find k clusters.

$\mathbf{k}\le 0$

nag_mv_cluster_indicator (g03ejc) will find the clusters based on the distance given in dlevel.

Constraint: $\mathbf{k}\le \mathbf{n}$.

On exit: the number of clusters produced, $k$.

6:    $\mathbf{dlevel}$ – double *Input/Output

On entry: if $\mathbf{k}\le 0$, then dlevel must contain the distance at which clusters are produced. Otherwise dlevel need not be set.

Constraint: if $\mathbf{k}\le 0$, $\mathbf{dlevel}>0.0$.

On exit: if $\mathbf{k}>0$ on entry, then dlevel contains the distance at which the required number of clusters are found. Otherwise dlevel remains unchanged.

7:    $\mathbf{ic}\left[\mathbf{n}\right]$ – IntegerOutput

On exit: $\mathbf{ic}\left[\mathit{i}-1\right]$ indicates to which of $k$ clusters the $\mathit{i}$th object belongs, for $\mathit{i}=1,2,\dots ,n$.

8:    $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_2_INT_ARG_GT

On entry, $\mathbf{k}=〈\mathit{\text{value}}〉$ while $\mathbf{n}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{k}\le \mathbf{n}$.

NE_CLUSTER

The precise number of clusters requested is not possible because of
tied clustering distances. The actual number of clusters produced is $〈\mathit{\text{value}}〉$.

NE_INCOMP_ARRAYS

Arrays cd and dord are not compatible.

NE_INT_ARG_LT

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\ge 2$.

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

NE_NOT_INCREASING

The sequence cd is not increasing:
$\mathbf{cd}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$, $\mathbf{cd}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$.

NE_REAL_INT

On entry, $\mathbf{dlevel}=〈\mathit{\text{value}}〉$, $\mathbf{k}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{k}\le 0$ and $\mathbf{dlevel}>0.0$.

NW_2_INT

On exit, $\mathbf{k}=〈\mathit{\text{value}}〉$, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Trivial solution returned.

NW_INT

On exit, $\mathbf{k}=1$.
Trivial solution returned.

NW_REAL_REALARR

On entry, $\mathbf{dlevel}=〈\mathit{\text{value}}〉$, $\mathbf{cd}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$.
Trivial solution returned.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (g03ejce.c)

10.2

Program Data

Program Data (g03ejce.d)

10.3

Program Results

Program Results (g03ejce.r)