numeric matrix or data.frame.

a function which accepts as first argument a (data) matrix like x, second argument, say k, k >= 2, the number of clusters desired, and returns a list with a component named (or shortened to) cluster which is a vector of length n = nrow(x) of integers in 1:k determining the clustering or grouping of the n observations.

the maximum number of clusters to consider, must be at least two.

integer, number of Monte Carlo (“bootstrap”) samples.

a positive integer specifying the power p which is applied to the euclidean distances (dist) before they are summed up to give W(k). The default, d.power = 1, corresponds to the “historical” R implementation, whereas d.power = 2 corresponds to what Tibshirani et al had proposed. This was found by Juan Gonzalez, in 2016-02.

a character string specifying the space of the H_0 distribution (of no cluster). Both "scaledPCA" and "original" use a uniform distribution in a hyper cube and had been mentioned in the reference; "original" been added after a proposal (including code) by Juan Gonzalez.

integer or logical, determining if “progress” output should be printed. The default prints one bit per bootstrap sample.

(for clusGap():) optionally further arguments for FUNcluster(), see kmeans example below.

numeric vector of ‘function values’, of length K, whose (“1 SE respected”) maximum we want.

numeric vector of length K of standard errors of f.

character string indicating how the “optimal” number of clusters, k^, is computed from the gap statistics (and their standard deviations), or more generally how the location k^ of the maximum of f[k] should be determined.

"globalmax":

simply corresponds to the global maximum, i.e., is which.max(f)

"firstmax":

gives the location of the first local maximum.

"Tibs2001SEmax":

uses the criterion, Tibshirani et al (2001) proposed: “the smallest k such that f(k) ≥ f(k+1) - s_{k+1}”. Note that this chooses k = 1 when all standard deviations are larger than the differences f(k+1) - f(k).

"firstSEmax":

location of the first f() value which is not smaller than the first local maximum minus SE.factor * SE.f[], i.e, within an “f S.E.” range of that maximum (see also SE.factor).

This, the default, has been proposed by Martin Maechler in 2012, when adding clusGap() to the cluster package, after having seen the "globalSEmax" proposal (in code) and read the "Tibs2001SEmax" proposal.

"globalSEmax":

(used in Dudoit and Fridlyand (2002), supposedly following Tibshirani's proposition): location of the first f() value which is not smaller than the global maximum minus SE.factor * SE.f[], i.e, within an “f S.E.” range of that maximum (see also SE.factor).

See the examples for a comparison in a simple case.

[When method contains "SE"] Determining the optimal number of clusters, Tibshirani et al. proposed the “1 S.E.”-rule. Using an SE.factor f, the “f S.E.”-rule is used, more generally.

arguments with the same meaning as in plot.default(), with different default.

logical indicating if (1 SE -)“error bars” should be drawn, via arrows().

a list of arguments passed to arrows(); the default, notably angle and code, provide a style matching usual error bars.

a matrix with K.max rows and 4 columns, named "logW", "E.logW", "gap", and "SE.sim", where gap = E.logW - logW, and SE.sim corresponds to the standard error of gap, SE.sim[k]=s[k], where s[k] := sqrt(1 + 1/B) sd^*(gap[]), and sd^*() is the standard deviation of the simulated (“bootstrapped”) gap values.

the clusGap(..) call.

the spaceH0 argument (match.arg()ed).

number of observations, i.e., nrow(x).

input B

input function FUNcluster