parApplyClusterAnalysis: Repeated Application of a Clustering Method

In FCPS: Fundamental Clustering Problems Suite

Repeated Application of a Clustering Method

Description

Repeatedly applies a clustering method to data or distances. Trials can be executed serially or on a worker cluster from the recommended parallel package. A single input or a list of inputs can be processed. It was used for the benchmarking of clustering algorithms in [Thrun, 2018; Thrun/Ultsch, 2020; Thrun, 2021].

Usage

parApplyClusterAnalysis(
  DataOrDistances,
  FUN,
  NumberOfTrials = 1:100,
  ClusterNo = NULL,
  WorkersOrNo,
  SocketType = "PSOCK",
  SetSeed = TRUE,
  ...
)

Arguments

DataOrDistances	Data, distances, dissimilarities, or a list of such inputs. A list that is not a data.frame is treated as a collection of inputs.
FUN	A function or character string naming a clustering function. The clustering function should return a list with a unique element named Cls if a clustering matrix is required.
NumberOfTrials	A positive integer count or a vector of positive integer trial identifiers. If a single value n is supplied, the trial identifiers are seq_len(n). Default is 1:100.
ClusterNo	Number of clusters supplied to FUN. For multiple inputs, this may be one value or one value per input. NULL, an empty value, or NA causes the argument to be omitted from the clustering-function call.
WorkersOrNo	Missing, NULL, a positive integer, or an object inheriting from class "cluster". If missing, the function attempts to use one fewer than the number of detected logical CPU cores. NULL requests serial execution. A positive integer creates a new worker cluster. An existing cluster object is used without being stopped by this function.
SocketType	Non-empty character scalar passed to the type argument of parallel::makeCluster(). Default is "PSOCK".
SetSeed	Logical scalar. If TRUE, trial i uses seed 1000 + i. If FALSE, no deterministic trial seed is assigned. Default is TRUE.
...	Further arguments passed to FUN. Named arguments in ... may not redefine arguments already supplied by the wrapper.

Details

Default is the number of cores existing minus 1.

In FCPS default parameters for each clustering algorithm are used automatically if not specified by the user. parApplyClusterAnalysis expects in FUN a function of a clustering algorithm which returns a list of objects of which one is named Cls. If not given the whole output of FUN is returned with a warning.

Cls is a [1:N] numerical vector of of numbers 1:k of the k clusters labeling the data points to the clusters.

Value

For a single input, a list with components:

Cls_Matrix	Matrix containing one clustering vector per trial. Column names identify seeds or trial IDs. It is NULL if at least one result does not have exactly one element named Cls.
ComputationTime	Named numeric vector containing elapsed computation time in seconds for each trial.
Seeds	Named integer vector containing the seeds used for the trials, or NULL when SetSeed = FALSE.
CAobjects	List of complete clustering results. For this generic wrapper, it is included when Cls_Matrix cannot be constructed.

For multiple inputs, a list containing one result of this form per input is returned. Input names are retained when present.

Author(s)

Michael Thrun

References

Thrun, M. C.: Projection-Based Clustering through Self-Organization and Swarm Intelligence, Springer, Heidelberg, ISBN: 978-3658205393, 2018.

Thrun, M. C., Ultsch, A.: Swarm Intelligence for Self-Organized Clustering, Artificial Intelligence, Vol. 290, pp. 103237, DOI: 10.1016/j.artint.2020.103237, Elsevier, 2021.

Thrun, M. C.: Distance-Based Clustering Challenges for Unbiased Benchmarking Studies, Nature Scientific Reports, Vol. 11, pp. 18988, DOI: 10.1038/s41598-021-98126-1, 2021.

See Also

clusterApply

Examples

simple_clustering <- function(Data, ClusterNo = 2, ...) {
  fit <- stats::kmeans(Data, centers = ClusterNo)
  list(Cls = fit$cluster, Object = fit)
}

DataList=list(
  Dataset1=matrix(rnorm(40, 0), ncol = 2),
  DataSet2=matrix(rnorm(40, 4), ncol = 2)
)

# Serial example
result <- parApplyClusterAnalysis(
  DataOrDistances = DataList,
  FUN = simple_clustering,
  NumberOfTrials = 2,
  ClusterNo = 2,
  WorkersOrNo = NULL
)

result$Cls_Matrix
result$ComputationTime

FCPS documentation built on July 15, 2026, 5:08 p.m.