scipy.cluster.hierarchy.

from_mlab_linkage#

scipy.cluster.hierarchy.from_mlab_linkage(Z)[source] #

Convert a linkage matrix generated by MATLAB(TM) to a new linkage matrix compatible with this module.

The conversion does two things:

the indices are converted from 1..N to 0..(N-1) form, and

a fourth column Z[:,3] is added where Z[i,3] represents the number of original observations (leaves) in the non-singleton cluster i.

This function is useful when loading in linkages from legacy data files generated by MATLAB.

Parameters:

Zndarray: A linkage matrix generated by MATLAB(TM).

Returns:

ZSndarray: A linkage matrix compatible with scipy.cluster.hierarchy.

See also

linkage: for a description of what a linkage matrix is.
to_mlab_linkage: transform from SciPy to MATLAB format.

Notes

from_mlab_linkage 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	⚠️ merges chunks	n/a

See Support for the array API standard for more information.

Examples

>>> importnumpyasnp
>>> fromscipy.cluster.hierarchyimport ward, from_mlab_linkage

Given a linkage matrix in MATLAB format mZ, we can use scipy.cluster.hierarchy.from_mlab_linkage to import it into SciPy format:

>>> mZ = np.array([[1, 2, 1], [4, 5, 1], [7, 8, 1],
...  [10, 11, 1], [3, 13, 1.29099445],
...  [6, 14, 1.29099445],
...  [9, 15, 1.29099445],
...  [12, 16, 1.29099445],
...  [17, 18, 5.77350269],
...  [19, 20, 5.77350269],
...  [21, 22, 8.16496581]])

>>> Z = from_mlab_linkage(mZ)
>>> Z
array([[ 0. , 1. , 1. , 2. ],
 [ 3. , 4. , 1. , 2. ],
 [ 6. , 7. , 1. , 2. ],
 [ 9. , 10. , 1. , 2. ],
 [ 2. , 12. , 1.29099445, 3. ],
 [ 5. , 13. , 1.29099445, 3. ],
 [ 8. , 14. , 1.29099445, 3. ],
 [ 11. , 15. , 1.29099445, 3. ],
 [ 16. , 17. , 5.77350269, 6. ],
 [ 18. , 19. , 5.77350269, 6. ],
 [ 20. , 21. , 8.16496581, 12. ]])

As expected, the linkage matrix Z returned includes an additional column counting the number of original samples in each cluster. Also, all cluster indices are reduced by 1 (MATLAB format uses 1-indexing, whereas SciPy uses 0-indexing).