parApplyDataBasedCA: Repeated Application of a Data-Based Clustering Method

In FCPS: Fundamental Clustering Problems Suite

Repeated Application of a Data-Based Clustering Method

Description

Repeatedly applies a data-based clustering method to one dataset or a collection of datasets. Trials may be executed serially or in parallel.

Usage

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

Arguments

Data	Dataset accepted by FUN, or a list of datasets. A list that is not a data.frame is interpreted as a collection of inputs.
FUN	Function or character string naming a data-based clustering method. The result should normally be a list containing a unique element named Cls.
NumberOfTrials	Positive integer count or vector of positive integer trial identifiers. A scalar n generates seq_len(n). Default is 1:100.
ClusterNo	Number of clusters passed to FUN. For multiple datasets, it may be scalar or provide one value per dataset. NULL or NA omits the argument.
WorkersOrNo	Missing, NULL, a positive integer worker count, or an existing parallel cluster. If missing, one fewer than the detected logical cores is used when possible. NULL requests serial execution.
SocketType	Character scalar passed to parallel::makeCluster(). Default is "PSOCK".
SetSeed	Logical scalar. If TRUE, trial i uses seed 1000 + i. Default is TRUE.
...	Further arguments passed to FUN. Wrapper-supplied arguments may not be redefined.

Details

The dataset is passed to a formal argument named Data when available. Otherwise, DataOrDistances or the first inspectable non-dots argument is used.

For multiple datasets, errors raised while processing an individual dataset are converted to warnings. The corresponding list element is returned as NULL, while processing continues for the remaining datasets.

An internally created worker cluster is stopped automatically. A cluster supplied through WorkersOrNo is not stopped.

Value

For one dataset, a list with:

Cls_Matrix	Matrix of clustering vectors, one column per trial, or NULL if it cannot be constructed.
ComputationTime	Named numeric vector of elapsed trial times.
Seeds	Named integer vector of seeds, or NULL if SetSeed = FALSE.
CAobjects	Named list containing the complete clustering result from every trial.

For a collection of datasets, returns a list with one result per dataset. Failed datasets are represented by NULL.

Operating-system considerations

The default "PSOCK" cluster type is portable across the operating systems supported by R. Objects required by FUN must be available or serializable on each worker.

Set WorkersOrNo = NULL for deterministic serial testing.

Author(s)

Michael Thrun

References

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

parApplyClusterAnalysis, parApplyDistanceBasedCA, makeCluster

Examples

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

set.seed(2)
Data <- matrix(rnorm(80), ncol = 2)

result <- parApplyDataBasedCA(
  Data = Data,
  FUN = simple_clustering,
  NumberOfTrials = 2,
  ClusterNo = 2,
  WorkersOrNo = NULL
)

result$Cls_Matrix

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