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

# to_mlab_linkage

scipy.cluster.hierarchy.to_mlab_linkage(Z)

  Convert a linkage matrix to a MATLAB(TM) compatible one.

  Converts a linkage matrix `Z` generated by the linkage function of this module to a MATLAB(TM) compatible one. The return linkage matrix has the last column removed and the cluster indices are converted to `1..N` indexing.

  Parameters:
    Z ndarray

      A linkage matrix generated by `scipy.cluster.hierarchy`.

  Returns:
    to_mlab_linkage ndarray

      A linkage matrix compatible with MATLAB(TM)’s hierarchical clustering functions.

      The return linkage matrix has the last column removed and the cluster indices are converted to `1..N` indexing.

  See also

  `linkage`

    for a description of what a linkage matrix is.

  `from_mlab_linkage`

    transform from Matlab to SciPy format.

  Notes

  Array API Standard Support

  `to_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 | ✅ | n/a

  > See Support for the array API standard for more information.

  Examples

      >>> from scipy.cluster.hierarchy import ward, to_mlab_linkage
      >>> from scipy.spatial.distance import pdist

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

  After a linkage matrix `Z` has been created, we can use `scipy.cluster.hierarchy.to_mlab_linkage` to convert it into MATLAB format:

      >>> mZ = to_mlab_linkage(Z)
      >>> mZ
      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]])

  The new linkage matrix `mZ` uses 1-indexing for all the clusters (instead of 0-indexing). Also, the last column of the original linkage matrix has been dropped.