`scipy.cluster.hierarchy._hierarchy_impl:is_valid_im`

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

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.

Array API Standard Support

is_valid_im 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                   ⚠️ see notes          ⚠️ see notes        
Dask                  ⚠️ see notes          n/a                 
====================  ====================  ====================

See dev-arrayapi for more information.

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