`scipy.cluster.hierarchy:from_mlab_linkage`

source: /scipy/cluster/hierarchy.py :1796

Signature

def from_mlab_linkage ( Z )

Summary

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

Extended Summary

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

Z : ndarray: A linkage matrix generated by MATLAB(TM).

Returns

ZS : ndarray: A linkage matrix compatible with scipy.cluster.hierarchy.

Notes

Array API Standard Support

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 dev-arrayapi for more information.

Examples

import numpy as np
from scipy.cluster.hierarchy import 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)

✓

✗

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).

Aliases

scipy.cluster.hierarchy.from_mlab_linkage