disco_samples: Per-sample DISCO scores

In discoCVI: Implementation of the DISCO Metric for Internal Clustering Evaluation

Per-sample DISCO scores

Description

Computes a pointwise DISCO score for every observation in X. The score lies in [-1, 1]:

• Values close to 1 indicate a well-placed point (either tightly within its cluster or a noise point far from all clusters).

• Values close to 0 indicate borderline placement.

• Values close to -1 indicate a misplaced point (or a noise point that should belong to a cluster).

Four cases are handled:

1. All noise — every point labelled -1: all scores are -1.

2. Single cluster with no noise — all scores are 0.

3. One real cluster + noise — cluster points are scored via p_cluster; noise points are scored via p_noise.

4. Two or more clusters (optional noise) — non-noise points use p_cluster on the non-noise sub-matrix; noise points use p_noise.

Since version 0.2.0 these quantities are computed from the merge tree of the mutual-reachability minimum spanning tree, without storing any n \times n matrix: memory grows linearly with n (times the number of clusters), and the scores are identical to the previous matrix-based implementation up to floating-point rounding.

Usage

disco_samples(X, labels, min_points = 5)

Arguments

X	A numeric matrix (n \times p) or data.frame.
labels	An integer vector of length n containing cluster labels. Use -1 to denote noise/outlier points.
min_points	A positive integer for the core-distance neighbourhood size. Default is 5.

Value

A numeric vector of length n with per-point DISCO scores.

See Also

disco_score, p_cluster, p_noise

Examples

set.seed(42)
X <- matrix(rnorm(100), ncol = 2)
labels <- rep(c(0L, 1L), each = 25)
s <- disco_samples(X, labels)
hist(s, main = "Per-sample DISCO scores")

discoCVI documentation built on Oct. 28, 2026, 1:07 a.m.