Skip to main content
`Ctrl`+`K`
scipy.cluster.hierarchy.

# from_mlab_linkage

scipy.cluster.hierarchy.from_mlab_linkage(Z)

  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:
    Z ndarray

      A linkage matrix generated by MATLAB(TM).

  Returns:
    ZS ndarray

      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

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