setup_HOPACH: Setup HOPACHConfig

In rtemis: Schema-Driven Machine Learning and Visualization

Setup HOPACHConfig

Description

Setup a HOPACHConfig object for Hierarchical Ordered Partitioning and Collapsing Hybrid (HOPACH) clustering, via the Bioconductor package 'hopach'.

Usage

setup_HOPACH(
  dist = "cosangle",
  level_selection = "best",
  max_levels = 15L,
  max_children = 9L,
  max_children_mss = 9L,
  collapse = "seq",
  new_medoid = "medsil",
  mss = "med",
  min_improvement = 0,
  initial_order = "co",
  element_order = "own",
  features = NULL
)

Arguments

dist	Character {"cosangle", "abscosangle", "euclid", "cor", "abscor"}: Distance measure.
level_selection	Character {"best", "greedy"}: Which level of the tree becomes the returned partition. "best": the level minimizing MSS; "greedy": the first level below which MSS increases.
max_levels	Integer [1, 15]: Maximum number of levels in the tree.
max_children	Integer [2, 9]: Maximum number of children at each node.
max_children_mss	Integer [2, 9]: Maximum number of children at each node when computing MSS.
collapse	Character {"seq", "all"}: How collapsing is performed at each level. "seq": collapse pairs sequentially from the closest while MSS decreases; "all": collapse any pair that decreases MSS.
new_medoid	Character {"medsil", "center", "nn", "uwnn"}: How the medoid of a collapsed pair is chosen.
mss	Character {"med", "mean"}: Split silhouette criterion; median or mean.
min_improvement	Numeric [0, 1]: Relative improvement in MSS required to accept a collapse step.
initial_order	Character {"co", "clust"}: How clusters in the first level are ordered.
element_order	Character {"own", "neighbor"}: How elements are ordered within a cluster.
features	Optional Character vector: Names of at least 2 distinct feature columns to cluster on. NULL clusters on all numeric features.

Details

HOPACH identifies the number of clusters itself, by building an ordered hierarchical tree and selecting the level with maximally homogeneous clusters under the Median (or Mean) Split Silhouette criterion. There is therefore no k to set: max_levels and max_children bound the tree, and the number of clusters found is reported by the resulting Clustering.

Argument names are rtemis' own. They map to hopach::hopach() as: dist -> d, level_selection -> clusters, max_levels -> K, max_children -> kmax, max_children_mss -> khigh, collapse -> coll, new_medoid -> newmed, mss -> mss, min_improvement -> impr, initial_order -> initord, element_order -> ord.

Two values hopach documents are not offered, because neither works: d = "abseuclid", which distancematrix() has no branch for, and ord = "co", which errors for every input.

On some datasets hopach collapses its tree all the way to a single cluster and cannot split it further, which ends the run with an error. Whether it happens depends on the data and on dist, so another dist clusters the same data.

Value

HOPACHConfig object.

Author(s)

EDG

References

van der Laan MJ, Pollard KS (2003). A new algorithm for hybrid hierarchical clustering with visualization and the bootstrap. Journal of Statistical Planning and Inference, 117(2), 275-303. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/S0378-3758(02)00388-9")}

Examples

hopach_config <- setup_HOPACH(dist = "euclid", max_levels = 3L)
hopach_config

rtemis documentation built on Oct. 20, 2026, 1:06 a.m.