parApplyDistanceBasedCA: Repeated Application of a Distance-Based Clustering Method

In FCPS: Fundamental Clustering Problems Suite

Repeated Application of a Distance-Based Clustering Method

Description

Repeatedly applies a distance-based clustering function to one distance or dissimilarity input, or to a collection of such inputs. Trials may run serially or on a parallel worker cluster.

Usage

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

Arguments

Distances	Distance or dissimilarity representation accepted by FUN, or a list of such inputs.
FUN	Function or character string naming a distance-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 inputs, this may be scalar or provide one value per input. NULL or NA omits the argument.
WorkersOrNo	Missing, NULL, a positive integer worker count, or an existing parallel cluster. If missing, an automatically selected worker count is used. 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.

Details

The distance input is passed preferentially to a formal argument named DataOrDistances, Distances, Distance, or Dissimilarities. If none is present, the first inspectable non-dots argument is used.

An internally created worker cluster is stopped when the function exits. An externally supplied cluster remains under the caller's control.

Value

For one input, a list containing:

Cls_Matrix	Matrix of clustering assignments, one column per trial, or NULL if a complete matrix cannot be constructed.
ComputationTime	Named numeric vector containing elapsed trial times.
Seeds	Named integer vector containing trial seeds, or NULL when SetSeed = FALSE.
CAobjects	Named list containing the complete clustering results.

For a collection of inputs, returns a named list containing one result per distance or dissimilarity input.

Operating-system considerations

The default PSOCK backend is suitable for Windows and is also portable to macOS and Unix-like systems. Use serial execution during package examples and most CRAN tests to avoid platform-dependent worker startup behavior.

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, parApplyDataBasedCA, parLapply

Examples

distance_clustering <- function(Distances, ClusterNo = 2) {
  fit <- stats::hclust(Distances)
  cls <- stats::cutree(fit, k = ClusterNo)
  list(Cls = cls, Object = fit)
}

set.seed(3)
Data <- matrix(rnorm(40), ncol = 2)
Distances <- stats::dist(Data)

result <- parApplyDistanceBasedCA(
  Distances = Distances,
  FUN = distance_clustering,
  NumberOfTrials = 2,
  ClusterNo = 2,
  WorkersOrNo = NULL
)

result$Cls_Matrix

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