VegsoupPartition: Partition a Vegsoup object
In vegsoup: Classes and Methods for Phytosociology

Description Usage Arguments Details Value Warning Author(s) References See Also Examples

Create an object of class 'VegsoupPartition' by selecting a predefined clustering algorithm or by supplying a function.

VegsoupPartition(obj, k, method = c("ward", "flexible", "pam", "isopam",
                 "kmeans", "optpart", "wards", "fanny", "FCM", "KM", "external"),
                 clustering, polish = FALSE, seed = NULL, verbose = FALSE,
                 ...)

`obj`	`Vegsoup` object.
`k`	number of partitions to create. Note, argument `k` can also be 1. In this case the whole object forms a single partition, the partitioning is flat.
`method`	clustering method. See ‘Details’.
`clustering`	external vector of cluster partitons, or column to be selected from `obj`. See `names`.
`polish`	apply optimization of silhouette widths `optsil` to merge singletons into an existing multi element partition. Note, this will likely decrease the initial number of `k`!
`seed`	set random number generator to make results from methods `"kmeans"` and `"fanny"` reproducible.
`verbose`	print diagnostic messages.
`...`	passed to methods. Currently not supported!

The function creates a partitioned object of class 'Vegsoup' using several clustering methods. All methods except "kmeans" take a 'dist' object as data argument (as.dist(obj)). "kmeans" uses the original data matrix (as.matrix(obj)), whereas method "KM" is capable of using a 'dist' objects. Specific implementation details are given below:

ward: calls cluster::agnes with method = "ward".
flexible: calls cluster::agnes with method = "flexible" and par.method = c(alpha, alpha, beta, 0), where alpha = 0.625 and beta = 1 - 2 * alpha.
pam: calls cluster::pam with no specific additional options, except argument k.
kmeans: calls stats::kmeans with centers = k. It doesn't use a dissimilarity matrix and proper standardization is required (e.g. Hellinger-distances, decostand(obj) <- "hellinger" and vegdist(obj) <- "euclidean"). In most cases method "KM" is preferred.
wards: calls stats::hclust with method = "ward.D".
fanny: calls cluster::fanny with k = k, argument memb.exp is set to 1.1 if not supplied.
FCM, KM: calls vegclust::vegclustdist with mobileMemb = k and method = "FCM", respectively "KM". If you need further argument use the function interface (see FUN below).
isopam: calls isopam::isopam using the 'distance' argument
external: simply takes a user (object) supplied partitioning vector 'clustering'. If argument 'clustering' is a "character" of length 1 the function seeks to select the supplied column from obj. If it is given as a vector of mode numeric and of length equal to nrow(obj) it is treated as the partitioning vector.this will be used. Vectors of mode character will be coerced using as.numeric(factor(clustering)) to construct the clustering vector. In both cases argument 'method' is ignored and will be set to "external".
FUN: If method is a function, VegsoupPartition will internally create a distance matrix by calling Xd <- as.dist(obj). The raw data matrix, possibly standardized, is available with X <- as.matrix(obj). Argument k is queried from the function's argument k. These object are evaluated with FUN by a call to do.call(FUN, args = list(Xd = Xd, X = X, k = k)). All other arguments must are defined inside FUN. The output of FUN needs to be nothing but a partitioning vector of integers!

Depending on the applied method the partitioning vector is obtained as follows: 'agnes' and 'hclust' objects are sliced by subsequent calls to cutree to obtain k partitions. Objects of class 'pam', 'fanny' and 'kmeans' already contain a cluster(ing) attribute. If a hierarchy was estimated for 'isopam' objects the flat attribute is accessed, otherwise the lowest hierarchy level is extracted. When using the function interface to method the returned partitioning vector of FUN should not be reordered in any way. The function must not assign names to the results vector, this is performed automatically.

If polish is TRUE the function tries to groom singletons (single member group) using the optsil procedure. This may take some time to complete. Argument maxitr is set to k^2.

Returns an object of class VegsoupPartition. For method fanny the matrix containing the memberships is retained in the sites data (additional k columns are added).

Method "fanny" and fast = TRUE may hang due to warnings issued by fanny and may freeze your R session. Setting memb.exp = 1.1 will in most cases avoid any warnings of fanny.

Roland Kaiser

Missing, there are many!

VegsoupPartition OptimStride hclust

require(vegsoup)

# simulate 100 plots and 200 species distributed along a two-dimensional gradient
x <- coenoflex(100, 200)

r <- VegsoupPartition(x, k = 2, method = "fanny", memb.exp = 2)
partitioning(r)
head(sites(r))

# plot membership values against gradient values
stars(sites(r)[grep("M", names(r))],
      locations = sites(r)[, grep("gradient", names(r))], len = 0.05,
      draw.segments = TRUE, labels = NULL)