class skbio.stats.distance.DistanceMatrix(data, ids=None)[source]

Store distances between objects.

A DistanceMatrix is a DissimilarityMatrix with the additional requirement that the matrix data is symmetric. There are additional methods made available that take advantage of this symmetry.


The distances are stored in redundant (square-form) format [R66]. To facilitate use with other scientific Python routines (e.g., scipy), the distances can be retrieved in condensed (vector-form) format using condensed_form.

DistanceMatrix only requires that the distances it stores are symmetric. Checks are not performed to ensure the other three metric properties hold (non-negativity, identity of indiscernibles, and triangle inequality) [R67]. Thus, a DistanceMatrix instance can store distances that are not metric.


[R66](1, 2)
[R67](1, 2)


T Transpose of the dissimilarity matrix.
data Array of dissimilarities.
dtype Data type of the dissimilarities.
ids Tuple of object IDs.
png Display heatmap in IPython Notebook as PNG.
shape Two-element tuple containing the dissimilarity matrix dimensions.
size Total number of elements in the dissimilarity matrix.
svg Display heatmap in IPython Notebook as SVG.


x in dm Check if the specified ID is in the dissimilarity matrix.
dm1 == dm2 Compare this dissimilarity matrix to another for equality.
dm[x] Slice into dissimilarity data by object ID or numpy indexing.
dm1 != dm2 Determine whether two dissimilarity matrices are not equal.
str(dm) Return a string representation of the dissimilarity matrix.
condensed_form() Return an array of distances in condensed format.
copy() Return a deep copy of the dissimilarity matrix.
filter(ids[, strict]) Filter the dissimilarity matrix by IDs.
from_iterable(iterable, metric[, key, keys, ...]) Create DistanceMatrix from all pairs in an iterable given a metric.
index(lookup_id) Return the index of the specified ID.
permute([condensed]) Randomly permute both rows and columns in the matrix.
plot([cmap, title]) Creates a heatmap of the dissimilarity matrix
read(file[, format]) Create a new DistanceMatrix instance from a file.
redundant_form() Return an array of dissimilarities in redundant format.
to_data_frame() Create a pandas.DataFrame from this DissimilarityMatrix.
to_series() Create a pandas.Series from this DistanceMatrix.
transpose() Return the transpose of the dissimilarity matrix.
write(file[, format]) Write an instance of DistanceMatrix to a file.