`scipy.cluster.hierarchy._hierarchy_impl:is_valid_im`

source: build-install/usr/lib/python3.14/site-packages/scipy/cluster/hierarchy/_hierarchy_impl.py:1991

Signature

def is_valid_im(R, warning = False, throw = False, name = None)

Summary

Return True if the inconsistency matrix passed is valid.

Extended Summary

It must be a $n$ by 4 array of doubles. The standard deviations R[:,1] must be nonnegative. The link counts R[:,2] must be positive and no greater than $n - 1$ .

Parameters

R : ndarray: The inconsistency matrix to check for validity.
warning : bool, optional: When True, issues a Python warning if the linkage matrix passed is invalid.
throw : bool, optional: When True, throws a Python exception if the linkage matrix passed is invalid.
name : str, optional: This string refers to the variable name of the invalid linkage matrix.

Returns

b : bool: True if the inconsistency matrix is valid; False otherwise.

Notes

Array API support (experimental): If the input is a lazy Array (e.g. Dask or JAX), the return value may be a 0-dimensional bool Array. When warning=True or throw=True, calling this function materializes the array.

Examples

from scipy.cluster.hierarchy import ward, inconsistent, is_valid_im
from scipy.spatial.distance import pdist

✓

Given a data set ``X``, we can apply a clustering method to obtain a linkage matrix ``Z``. `scipy.cluster.hierarchy.inconsistent` can be also used to obtain the inconsistency matrix ``R`` associated to this clustering process:

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))
R = inconsistent(Z)

✓

Z
R

✗

array([[1.     , 0.     , 1.     , 0.     ],
       [1.     , 0.     , 1.     , 0.     ],
       [1.     , 0.     , 1.     , 0.     ],
       [1.     , 0.     , 1.     , 0.     ],
       [1.1455 , 0.20576, 2.     , 0.70711],
       [1.1455 , 0.20576, 2.     , 0.70711],
       [1.1455 , 0.20576, 2.     , 0.70711],
       [1.1455 , 0.20576, 2.     , 0.70711],
       [2.78516, 2.58798, 3.     , 1.1547 ],
       [2.78516, 2.58798, 3.     , 1.1547 ],
       [6.57066, 1.38071, 3.     , 1.1547 ]])

Now we can use `scipy.cluster.hierarchy.is_valid_im` to verify that ``R`` is correct:

is_valid_im(R)

✓

True

However, if ``R`` is wrongly constructed (e.g., one of the standard deviations is set to a negative value), then the check will fail:

R[-1,1] = R[-1,1] * -1
is_valid_im(R)

✓

False

Aliases

scipy.cluster.hierarchy.is_valid_im