`scipy.cluster.hierarchy._hierarchy_impl:is_monotonic`

source: /scipy/cluster/hierarchy/_hierarchy_impl.py:1898

Signature

def is_monotonic(Z)

Summary

Return True if the linkage passed is monotonic.

Extended Summary

The linkage is monotonic if for every cluster $s$ and $t$ joined, the distance between them is no less than the distance between any previously joined clusters.

Parameters

Z : ndarray: The linkage matrix to check for monotonicity.

Returns

b : bool: A boolean indicating whether the linkage is monotonic.

Notes

Array API Standard Support

is_monotonic has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable SCIPY_ARRAY_API=1 and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported.

====================  ====================  ====================
Library               CPU                   GPU
====================  ====================  ====================
NumPy                 ✅                     n/a                 
CuPy                  n/a                   ✅                   
PyTorch               ✅                     ✅                   
JAX                   ✅                     ✅                   
Dask                  ✅                     n/a                 
====================  ====================  ====================

See dev-arrayapi for more information.

Examples

from scipy.cluster.hierarchy import median, ward, is_monotonic
from scipy.spatial.distance import pdist

✓

By definition, some hierarchical clustering algorithms - such as `scipy.cluster.hierarchy.ward` - produce monotonic assignments of samples to clusters; however, this is not always true for other hierarchical methods - e.g. `scipy.cluster.hierarchy.median`. Given a linkage matrix ``Z`` (as the result of a hierarchical clustering method) we can test programmatically whether it has the monotonicity property or not, using `scipy.cluster.hierarchy.is_monotonic`:

X = [[0, 0], [0, 1], [1, 0],
     [0, 4], [0, 3], [1, 4],
     [4, 0], [3, 0], [4, 1],
     [4, 4], [3, 4], [4, 3]]

✓

Z = ward(pdist(X))

✓

Z
is_monotonic(Z)

✗

np.True_

Z = median(pdist(X))

✓

Z
is_monotonic(Z)

✗

np.False_

Note that this method is equivalent to just verifying that the distances in the third column of the linkage matrix appear in a monotonically increasing order.

Aliases

scipy.cluster.hierarchy.is_monotonic