API reference

knn_density(X::MetricSpace; k=10, d=dist_euclidean)

Estimate a density score at each point as the inverse of the distance to the k-th nearest sample, with a 1e-10 stabilizer. The query point itself counts among the k samples: for distinct points, k=2 reaches the nearest other point, whereas k=1 gives approximately 1e10 everywhere. Higher scores correspond to smaller local neighbour distances; they are not normalized probabilities.

This is a simple density estimator useful for ToMATo clustering. For each point, the k-nearest-neighbor distance is computed via distance_to_measure, and the density is returned as the reciprocal.

Use ToMATo.knn_density explicitly when MetricSpaces is also loaded, since that package exports a different function with the same name. The distance argument changes the density estimate, not the metric used by proximity_graph.

proximity_graph(X::EuclideanSpace, ϵ; max_k_ball=5, min_k_ball=1, k_nn=3)

Calculate the proximity graph of a metric space X and return a graph.

For each point, queries a Euclidean ϵ-ball including self. If the list has fewer than min_k_ball + 1 entries, queries k_nn + 1 nearest samples instead. This fallback can introduce edges longer than ϵ; it requires k_nn < length(X).

The sorted neighbour list is truncated to max_k_ball entries before removing self. The graph is undirected and unions all retained edges, so final vertex degree can exceed this cap. Set min_k_ball=0 and max_k_ball=length(X) for a radius graph without fallback or truncation. Returns a Graphs.SimpleGraph.

tomato(X::MetricSpace, g::Graph, ds::Vector{<:Real}, τ::Real=Inf;
       max_cluster_height::Real=0)

Calculate the ToMATo clustering of the metric space X, with proximity-graph g, relative to aligned finite density values ds and a nonnegative threshold τ. An eligible merge occurs when the shorter peak's height above the current density is strictly less than τ. Increasing τ allows more merges; the default τ=Inf applies no finite prominence cutoff, while τ=0 retains modes for distinct densities.

Returns two objects:

• clusters: a vector of integers, one for each point of X, with the corresponding cluster number.

• births_and_deaths: a dictionary mapping original peak point IDs to [birth_density, death_density]. A finite death is recorded only for an accepted merge in this run. death_density=Inf is the sentinel for an unmerged peak; do not interpret birth_density - Inf as a finite lifetime. Use the unrestricted τ=Inf run to inspect recorded finite prominences.

Final positive labels rank surviving peaks by descending density; they differ from dictionary keys and can change between runs. Equal-density neighbours do not automatically join. The current implementation also has a multiway-saddle limitation: if a chosen component is absorbed by a higher peak, later comparisons at the same point can retain a stale component ID. Thus even a connected graph with distinct densities can retain multiple modes at τ=Inf.

max_cluster_height: every cluster whose peak is less than max_cluster_height will be fused together in a single cluster labeled 0. Set to 0 (default) to keep all clusters.