Align clustering results to a reference.

Given a reference clustering result, align one or more query clustering results to the reference using the Hungarian algorithm. Can handle both single clustering vectors and multiple clusterings in a matrix/data.frame format.

align_clusters(
  clust,
  clust_ref,
  clust_names = NULL,
  handle_unmatched = c("label", "NA", "nearest"),
  verbose = FALSE
)

Arguments

clust

Query clustering result(s). Can be:

  • A vector (numeric, character, or factor) for single clustering

  • A matrix/data.frame where each column is a clustering result

  • A list of clustering vectors

clust_ref

Reference clustering result (vector).

clust_names

Optional names for the clustering results (for matrix/list input).

handle_unmatched

How to handle unmatched clusters:

  • "label": create new labels like "Unmatched_X" (default)

  • "NA": assign NA to unmatched clusters

  • "nearest": assign to nearest matching cluster

verbose

Logical. Print alignment progress for multiple clusterings.

Value

  • If input is a single vector: aligned clustering (factor)

  • If input is matrix/data.frame: matrix with aligned clusterings

  • If input is a list: list with aligned clusterings

Examples

# Single clustering alignment
ref <- factor(c("A", "A", "B", "B", "C", "C"))
query <- factor(c(2, 2, 1, 1, 3, 3))
aligned <- align_clusters(query, ref)

# Multiple clusterings alignment
query_matrix <- cbind(
  method1 = c(1, 1, 2, 2, 3, 3),
  method2 = c("a", "a", "b", "b", "c", "c"),
  method3 = c(2, 2, 2, 1, 1, 1)
)
aligned_all <- align_clusters(query_matrix, ref)

# List of clusterings
query_list <- list(
  kmeans = c(1, 1, 2, 2, 3, 3),
  hierarchical = c("x", "x", "y", "y", "z", "z")
)
aligned_list <- align_clusters(query_list, ref)