`scipy.spatial.distance:is_valid_dm`

source: /scipy/spatial/distance.py :2307

Signature

   def     is_valid_dm (    D    ,    tol    =  0.0   ,    throw    =  False   ,    name    =  D   ,    warning    =  False     )

Summary

Return True if input array satisfies basic distance matrix properties (symmetry and zero diagonal).

Extended Summary

This function checks whether the input is a 2-dimensional square NumPy array with a zero diagonal and symmetry within a specified tolerance. These are necessary properties for a distance matrix but not sufficient -- in particular, this function does not check the triangle inequality, which is required for a true metric distance matrix.

The triangle inequality states that for any three points i, j, and k: D[i,k] <= D[i,j] + D[j,k]

Parameters

D : array_like: The candidate object to test for basic distance matrix properties.
tol : float, optional: The distance matrix is considered symmetric if the absolute difference between entries ij and ji is less than or equal to tol. The same tolerance is used to determine whether diagonal entries are effectively zero.
throw : bool, optional: If True, raises an exception when the input is invalid.
name : str, optional: The name of the variable to check. This is used in exception messages when throw is True to identify the offending variable.
warning : bool, optional: If True, a warning message is raised instead of throwing an exception.

Returns

valid : bool: True if the input satisfies the symmetry and zero-diagonal conditions.

Raises

: ValueError: If throw is True and D is not a valid distance matrix.
: UserWarning: If warning is True and D is not a valid distance matrix.

Notes

This function does not check the triangle inequality, which is required for a complete validation of a metric distance matrix. Only structural properties (symmetry and zero diagonal) are verified. Small numerical deviations from symmetry or exact zero diagonal are tolerated within the tol parameter.

Examples

import numpy as np
from scipy.spatial.distance import is_valid_dm

✓

This matrix is a valid distance matrix.

d = np.array([[0.0, 1.1, 1.2, 1.3],
              [1.1, 0.0, 1.0, 1.4],
              [1.2, 1.0, 0.0, 1.5],
              [1.3, 1.4, 1.5, 0.0]])
is_valid_dm(d)

✓

In the following examples, the input is not a valid distance matrix. Not square:

is_valid_dm([[0, 2, 2], [2, 0, 2]])

✓

Nonzero diagonal element:

is_valid_dm([[0, 1, 1], [1, 2, 3], [1, 3, 0]])

✓

Not symmetric:

is_valid_dm([[0, 1, 3], [2, 0, 1], [3, 1, 0]])

✓

Aliases

scipy.cluster._optimal_leaf_ordering.is_valid_dm