R/classes.R

Defines functions print.KMeansCluster calc_inertia.KMeansCluster calc_inertia get_centroids.KMeansCluster get_centroids membership.KMeansCluster membership new_kmeans_cluster print.Evoc get_nearest_neighbours.Evoc get_nearest_neighbours get_layer.Evoc get_layer best_membership.Evoc best_membership new_evoc print.NearestNeighbours dim.NearestNeighbours get_dist_flat.NearestNeighbours get_dist_flat get_dist_mat.NearestNeighbours get_dist_mat get_idx_flat.NearestNeighbours get_idx_flat get_idx_mat.NearestNeighbours get_idx_mat new_nearest_neighbour

Documented in best_membership best_membership.Evoc calc_inertia calc_inertia.KMeansCluster dim.NearestNeighbours get_centroids get_centroids.KMeansCluster get_dist_flat get_dist_flat.NearestNeighbours get_dist_mat get_dist_mat.NearestNeighbours get_idx_flat get_idx_flat.NearestNeighbours get_idx_mat get_idx_mat.NearestNeighbours get_layer get_layer.Evoc get_nearest_neighbours get_nearest_neighbours.Evoc membership membership.KMeansCluster new_evoc new_kmeans_cluster new_nearest_neighbour print.Evoc print.KMeansCluster print.NearestNeighbours

# classes ----------------------------------------------------------------------

## nearest neighbours ----------------------------------------------------------

#' Generate a new NearestNeighbours
#'
#' @param indices Integer. Nearest neighbours in flat storage format. Need to
#' be sorted!
#' @param dist Numeric. Nearest neighbour distances in flat storarge format.
#' Need to be sorted! On the scale of the metric they were generated with,
#' i.e. Euclidean rather than squared Euclidean.
#' @param k Integer. Number of k-neighbours per sample.
#' @param n Integer. Number of samples.
#'
#' @returns Initialised `NearestNeighbours` class.
#'
#' @examples
#' d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
#' knn <- generate_knn_graph(d$data, k = 15L, .verbose = FALSE)
#' knn2 <- new_nearest_neighbour(
#'   indices = get_idx_flat(knn),
#'   dist = get_dist_flat(knn),
#'   k = 15L,
#'   n = 500L
#' )
#' knn2
#'
#' @export
new_nearest_neighbour <- function(
  indices,
  dist,
  k,
  n
) {
  # checks
  checkmate::qassert(indices, "I+")
  checkmate::qassert(dist, "N+")
  checkmate::assertTRUE(length(indices) == length(dist))
  checkmate::qassert(k, "I1")
  checkmate::qassert(n, "I1")

  res <- list(
    indices = indices,
    dist = dist,
    k = k,
    n = n
  )

  class(res) <- "NearestNeighbours"

  return(res)
}

## getters ---------------------------------------------------------------------

### indices --------------------------------------------------------------------

#' Get the indices as a matrix
#'
#' @param x `NearestNeighbours` class
#'
#' @returns The indices in samples x neighbours format
#'
#' @examples
#' d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
#' knn <- generate_knn_graph(d$data, k = 15L, .verbose = FALSE)
#' dim(get_idx_mat(knn))
#'
#' @export
get_idx_mat <- function(x) {
  UseMethod("get_idx_mat")
}

#' @rdname get_idx_mat
#'
#' @export
get_idx_mat.NearestNeighbours <- function(x) {
  # checks
  checkmate::assertClass(x, "NearestNeighbours")

  res <- matrix(data = x$indices, nrow = x$n, byrow = TRUE)

  return(res)
}

#' Get the indices as a flat vector
#'
#' @param x `NearestNeighbours` class
#'
#' @returns The indices in a flat format like
#' `c(idx1.1, idx1.2, ... , idx.2.1, idx2.2, ... idx3.1, idx3.2)`
#'
#' @examples
#' d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
#' knn <- generate_knn_graph(d$data, k = 15L, .verbose = FALSE)
#' head(get_idx_flat(knn))
#'
#' @export
get_idx_flat <- function(x) {
  UseMethod("get_idx_flat")
}

#' @rdname get_idx_flat
#'
#' @export
get_idx_flat.NearestNeighbours <- function(x) {
  # checks
  checkmate::assertClass(x, "NearestNeighbours")

  x$indices
}

### distances ------------------------------------------------------------------

#' Get the indices as a matrix
#'
#' @param x `NearestNeighbours` class
#'
#' @returns The indices in samples x neighbours format
#'
#' @examples
#' d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
#' knn <- generate_knn_graph(d$data, k = 15L, .verbose = FALSE)
#' dim(get_dist_mat(knn))
#'
#' @export
get_dist_mat <- function(x) {
  UseMethod("get_dist_mat")
}

#' @rdname get_dist_mat
#'
#' @export
get_dist_mat.NearestNeighbours <- function(x) {
  # checks
  checkmate::assertClass(x, "NearestNeighbours")

  res <- matrix(data = x$dist, nrow = x$n, byrow = TRUE)

  return(res)
}

#' Get the distances as a flat vector
#'
#' @param x `NearestNeighbours` class
#'
#' @returns The distances in a flat format like
#' `c(dist1.1, dist1.2, ... , dist2.1, dist2.2, ... dist3.1, dist3.2)`
#'
#' @examples
#' d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
#' knn <- generate_knn_graph(d$data, k = 15L, .verbose = FALSE)
#' head(get_dist_flat(knn))
#'
#' @export
get_dist_flat <- function(x) {
  UseMethod("get_dist_flat")
}

#' @rdname get_dist_flat
#'
#' @export
get_dist_flat.NearestNeighbours <- function(x) {
  # checks
  checkmate::assertClass(x, "NearestNeighbours")

  x$dist
}

### primitives -----------------------------------------------------------------

#' Dimensions of a NearestNeighbours object
#'
#' @param x A `NearestNeighbours` object.
#'
#' @returns The dimensions of the `NearestNeigbour` matrix.
#'
#' @export
#'
#' @keywords internal
dim.NearestNeighbours <- function(x) {
  c(x$n, x$k)
}

#' Print a NearestNeighbours object
#'
#' @param x A `NearestNeighbours` object.
#' @param ... Further arguments passed to or from other methods.
#'
#' @returns Invisibly returns `x`.
#'
#' @export
#'
#' @keywords internal
print.NearestNeighbours <- function(x, ...) {
  cat("NearestNeighbours\n")
  cat("  n_samples:   ", x$n, "\n")
  cat("  k_neighbours:", x$k, "\n")
  invisible(x)
}

## evoc ------------------------------------------------------------------------

### class ----------------------------------------------------------------------

#' Construct an Evoc object
#'
#' @param cluster_layers List of integer vectors.
#' @param membership_strengths List of numeric vectors.
#' @param persistence_scores Numeric vector.
#' @param knn Optional `NearestNeighbours` object or NULL.
#'
#' @returns An `Evoc` S3 object.
#'
#' @keywords internal
new_evoc <- function(
  cluster_layers,
  membership_strengths,
  persistence_scores,
  knn
) {
  structure(
    list(
      cluster_layers = cluster_layers,
      membership_strengths = membership_strengths,
      persistence_scores = persistence_scores,
      knn = knn
    ),
    class = "Evoc"
  )
}

### getters --------------------------------------------------------------------

#' Get the cluster membership at the best persistence score
#'
#' @param x An `Evoc` object.
#'
#' @returns A named list with elements `labels` (integer vector of cluster
#' assignments, `-1` for noise), `membership` (numeric vector of strengths),
#' `layer` (which layer index was selected), and `persistence` (the score).
#'
#' @examples
#' d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
#' res <- evoc(d$data, .verbose = FALSE)
#' table(best_membership(res)$cluster)
#'
#' @export
best_membership <- function(x) {
  UseMethod("best_membership")
}

#' @rdname best_membership
#' @export
best_membership.Evoc <- function(x) {
  idx <- which.max(x$persistence_scores)
  list(
    labels = x$cluster_layers[[idx]],
    membership = x$membership_strengths[[idx]],
    layer = idx,
    persistence = x$persistence_scores[idx]
  )
}

#' Get a specific EVoC layer
#'
#' @param x An `Evoc` object.
#' @param i Integer. Layer index to retrieve.
#'
#' @returns A named list with `labels`, `membership`, and `persistence` for
#' the requested layer.
#'
#' @examples
#' d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
#' res <- evoc(d$data, .verbose = FALSE)
#' str(get_layer(res, 1L))
#'
#' @export
get_layer <- function(x, i) {
  UseMethod("get_layer")
}

#' @rdname get_layer
#' @export
get_layer.Evoc <- function(x, i) {
  checkmate::qassert(i, "I1")
  n <- length(x$cluster_layers)
  if (i < 1L || i > n) {
    stop("Layer index out of range. Available layers: 1 to ", n, call. = FALSE)
  }
  list(
    labels = x$cluster_layers[[i]],
    membership = x$membership_strengths[[i]],
    persistence = x$persistence_scores[i]
  )
}

#' Get the kNN graph from an Evoc object
#'
#' @param x An `Evoc` object.
#'
#' @returns A `NearestNeighbours` object, or `NULL` if the kNN was not stored.
#'
#' @examples
#' d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
#' res <- evoc(d$data, return_knn = TRUE, .verbose = FALSE)
#' get_nearest_neighbours(res)
#'
#' @export
get_nearest_neighbours <- function(x) {
  UseMethod("get_nearest_neighbours")
}

#' @rdname get_nearest_neighbours
#' @export
get_nearest_neighbours.Evoc <- function(x) {
  if (is.null(x$knn)) {
    warning("kNN graph was not stored. Re-run evoc() with return_knn = TRUE.")
  }
  x$knn
}

### primitives -----------------------------------------------------------------

#' Print an Evoc object
#'
#' @param x An `Evoc` object.
#' @param ... Further arguments (ignored).
#'
#' @returns Invisibly returns `x`.
#'
#' @export
#'
#' @keywords internal
print.Evoc <- function(x, ...) {
  n_layers <- length(x$cluster_layers)
  best <- which.max(x$persistence_scores)
  cat("Evoc\n")
  cat("  layers:              ", n_layers, "\n")
  cat("  best layer:          ", best, "\n")
  cat("  best persistence:    ", round(x$persistence_scores[best], 4), "\n")
  cat(
    "  knn:                 ",
    if (is.null(x$knn)) "not stored" else "stored",
    "\n"
  )
  invisible(x)
}

## k means ---------------------------------------------------------------------

### class ----------------------------------------------------------------------

#' Construct a KMeansCluster object
#'
#' @param centroids Numeric matrix of shape k x features.
#' @param assignments Integer vector of length samples (1-indexed).
#' @param k Integer. Number of clusters.
#' @param method Character. Either `"full"` or `"minibatch"`.
#' @param metric Character. Distance metric used.
#'
#' @returns A `KMeansCluster` S3 object.
#'
#' @keywords internal
new_kmeans_cluster <- function(centroids, assignments, k, method, metric) {
  structure(
    list(
      centroids = centroids,
      assignments = assignments,
      k = k,
      method = method,
      metric = metric
    ),
    class = "KMeansCluster"
  )
}

### getters --------------------------------------------------------------------

#' Get cluster assignments
#'
#' @param x A `KMeansCluster` object.
#'
#' @returns Integer vector of length samples with cluster assignments
#'   (1-indexed).
#'
#' @examples
#' d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
#' km <- kmeans_cluster(d$data, k = 4L, .verbose = FALSE)
#' table(membership(km))
#'
#' @export
membership <- function(x) {
  UseMethod("membership")
}

#' @rdname membership
#' @export
membership.KMeansCluster <- function(x) {
  x$assignments
}

#' Get cluster centroids
#'
#' @param x A `KMeansCluster` object.
#'
#' @returns Numeric matrix of shape k x features.
#'
#' @examples
#' d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
#' km <- kmeans_cluster(d$data, k = 4L, .verbose = FALSE)
#' dim(get_centroids(km))
#'
#' @export
get_centroids <- function(x) {
  UseMethod("get_centroids")
}

#' @rdname get_centroids
#'
#' @export
get_centroids.KMeansCluster <- function(x) {
  # checks
  checkmate::assertClass(x, "KMeansCluster")

  x$centroids
}

### metrics --------------------------------------------------------------------

#' Calculate the cluster inertia
#'
#' @param x `KMeansCluster` class.
#' @param data Numerical matrix. The original data used to generate the k-means
#' clusters. Shape of samples x features
#'
#' @returns The cluster inertia
#'
#' @examples
#' d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
#' km <- kmeans_cluster(d$data, k = 4L, .verbose = FALSE)
#' calc_inertia(km, d$data)
#'
#' @export
calc_inertia <- function(x, data) {
  UseMethod("calc_inertia")
}

#' @rdname calc_inertia
#'
#' @export
calc_inertia.KMeansCluster <- function(x, data) {
  # checks
  checkmate::assertClass(x, "KMeansCluster")
  checkmate::assertMatrix(data, mode = "numeric")

  rs_inertia(
    data = data,
    centroids = x$centroids,
    cluster_membership = x$assignments
  )
}

### primitives -----------------------------------------------------------------

#' Print a KMeansCluster object
#'
#' @param x A `KMeansCluster` object.
#' @param ... Further arguments (ignored).
#'
#' @returns Invisibly returns `x`.
#'
#' @export
#'
#' @keywords internal
print.KMeansCluster <- function(x, ...) {
  n <- length(x$assignments)
  sizes <- tabulate(x$assignments, nbins = x$k)
  cat("KMeansCluster\n")
  cat("  method:    ", x$method, "\n")
  cat("  metric:    ", x$metric, "\n")
  cat("  k:         ", x$k, "\n")
  cat("  n:         ", n, "\n")
  cat(
    "  sizes:      min=",
    min(sizes),
    " median=",
    stats::median(sizes),
    " max=",
    max(sizes),
    "\n"
  )
  invisible(x)
}

Try the manifoldsR package in your browser

Any scripts or data that you put into this service are public.

manifoldsR documentation built on Nov. 17, 2026, 5:09 p.m.