linkage — Construct a hierarchical agglomerative clustering tree.

linkage(X) computes pairwise distances between rows of X and returns an (m-1)-by-3 cluster tree. linkage(Y, method) accepts a row-vector condensed distance vector in the same ordering as pdist.

Syntax

Z = linkage(X)
Z = linkage(X, method)
Z = linkage(X, method, metric)
Z = linkage(X, method, metric, 'savememory', value)
Z = linkage(X, method, pdist_inputs)
Z = linkage(Y, method)

Inputs

Returns

Errors

How linkage works

• Rows of X are observations and columns are variables. X must contain at least two observations; an n-by-1 column vector is treated as n one-dimensional observations.
• A row-vector input is interpreted as a condensed distance vector whose length is n*(n-1)/2.
• Distances must be finite and nonnegative.
• The default linkage method is "single".
• Supported methods are "single", "complete", "average", "weighted", "centroid", "median", and "ward", including common MATLAB aliases such as "nearest", "farthest", "upgma", and "wpgma".
• Condensed distance vectors used with "centroid", "median", or "ward" must pass a Euclidean-distance validity check.
• linkage(X, method, metric, ...) uses the same named numeric distance metrics and metric parameters as pdist.
• linkage(X, method, {metric, parameter}) accepts a cell array of pdist inputs.
• "SaveMemory","off" is accepted for source compatibility. "SaveMemory","on" is accepted for observation-matrix input with centroid, median, or ward linkage and Euclidean distance; RunMat uses the same bounded in-memory implementation for both values.
• The current exact agglomerative implementation is bounded to 700 observations to avoid unbounded CPU and memory use.
• The first two columns of Z contain one-based cluster identifiers. Original observations are numbered 1:m; newly formed clusters are numbered m+1, m+2, and so on. The third column contains the linkage distance for each merge.
• Typed-integer observations, condensed distances, and numeric distance parameters are separately gated RunMat extensions and must be exactly representable at the binary64 clustering boundary.

Examples

Cluster observation rows

X = [0 0; 3 4; 4 0; 0 2];
Z = linkage(X, "single")

Expected output:

Z is a 3-by-3 hierarchy. The first merge joins observations 1 and 4 at distance 2.

Cluster a condensed distance vector

Y = [1 4 6 5 7 2];
Z = linkage(Y, "complete")

Expected output:

Z describes complete-linkage merges for four observations.

Use a pdist metric

Z = linkage(X, "average", "cityblock")

Expected output:

Pairwise cityblock distances are used before average-linkage clustering.

Using linkage with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how linkage changes the result.

FAQ

Related Stats functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how linkage is executed, line by line, in Rust.

• View the source for linkage in Rust on GitHub
• Learn how the RunMat runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.

• RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
• Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing