NDVar.label_clusters(threshold=0, tail=0, name=None)

Find and label clusters of values exceeding a threshold

  • threshold (scalar) – Threshold value for clusters (default 0 to find clusters of non-zero values).

  • tail (0 | -1 | 1) – Whether to label cluster smaller than threshold, larger than threshold, or both (default).

  • name (str) – Name of the output NDVar (default is the current name).


clusters – NDVar of int, each cluster labeled with a unique integer value.['cids'] contains an array of all cluster IDs.

Return type



Together, the labels in the clusters array and the identifiers in['cids'] can be used as input for scipy.ndimage functions. For example, count the number of elements in each label of a binary mask:

>>> from scipy import ndimage
>>> labels = mask.label_clusters()
>>> ns = ndimage.measurements.sum(mask, labels,['cids'])
>>> dict(zip(['cids'], ns))
{1: 35.0, 6: 1.0, 37: 1.0}
>>> (labels == 1).sum()  # confirm count in label 1