skbio.stats.distance.SymmetricMatrix

class skbio.stats.distance.SymmetricMatrix(data, ids=None, validate=True, condensed=False, diagonal=None)

Store symmetric pairwise relationships between objects.

A SymmetricMatrix is a PairwiseMatrix with the additional requirement that the matrix data is symmetric. There are additional methods made available that take advantage of this symmetry. The plot method provides convenient built-in plotting functionality.

Parameters:

dataarray_like or SymmetricMatrix

Square, symmetric, two-dimensional numpy.ndarray values (floats), or a structure that can be converted to a numpy.ndarray using numpy.asarray or a one-dimensional vector of values (floats), as defined by scipy.spatial.distance.squareform. Can instead be a PairwiseMatrix (or SymmetricMatrix) instance, in which the instance’s data will be used. Data will be converted to a float dtype if necessary. A copy will not be made if already a numpy.ndarray with a float dtype.

idssequence of str, optional

Sequence of strings to be used as object IDs. Must match the number of rows/cols in data. If None (the default), IDs will be monotonically-increasing integers cast as strings, with numbering starting from zero, e.g., ('0', '1', '2', '3', ...).

validatebool, optional

If validate is True (the default) and data is not a DistanceMatrix object, the input data will be validated.

condensedbool, optional

If False (default) the data will be stored in a 2-dimensional redundant form. If True, the data will be stored in a 1-dimensional condensed form.

diagonalnp.ndarray or float, optional

If the matrix is to be stored in condensed form, diagonal stores the information contained in the matrix’s diagonal. If diagonal is a float, this value represents all values in the diagonal of the matrix. If diagonal is an array, it’s values represent the values along the diagonal of the original matrix.

See also

PairwiseMatrix

SymmetricMatrix

squareform

Attributes

T	Transpose of the matrix.
diagonal	Diagonal value(s) of the matrix.

Attributes (inherited)

data	Array of pairwise relationships.
default_write_format
dtype	Data type of the matrix values.
ids	Tuple of object IDs.
shape	Two-element tuple containing the redundant form matrix dimensions.
size	Total number of elements in the underlying data structure.

Methods

condensed_form()	Return an array of distances in condensed format.
copy()	Return a deep copy of the symmetric matrix.
from_iterable(iterable, metric[, key, keys, ...])	Create PairwiseMatrix from an iterable given a metric.
permute([condensed, seed])	Randomly permute both rows and columns in the matrix.
redundant_form()	Return an array of values in redundant format.
transpose()	Return the transpose of the matrix.

Methods (inherited)

between(from_, to_[, allow_overlap])	Obtain the pairwise values between the two groups of IDs.
filter(ids[, strict])	Filter the matrix by IDs.
index(lookup_id)	Return the index of the specified ID.
plot([cmap, title])	Create a heatmap of the matrix.
read([format])	Create a new SymmetricMatrix instance from a file.
rename(mapper[, strict])	Rename IDs in the matrix.
to_data_frame()	Create a pandas.DataFrame from this PairwiseMatrix.
within(ids)	Obtain all the pairwise values among the set of IDs.
write(file[, format])	Write an instance of SymmetricMatrix to a file.

Special methods

__getitem__(index)

Slice into data by object ID or numpy indexing.

Special methods (inherited)

__contains__(lookup_id)	Check if the specified ID is in the matrix.
__eq__(other)	Compare this matrix to another for equality.
__ge__(value, /)	Return self>=value.
__getstate__(/)	Helper for pickle.
__gt__(value, /)	Return self>value.
__le__(value, /)	Return self<=value.
__lt__(value, /)	Return self<value.
__ne__(other)	Determine whether two matrices are not equal.
__str__()	Return a string representation of the matrix.

Details

T

Transpose of the matrix.

If the matrix is in condensed form, a redundant form matrix will be returned.

See also

transpose

diagonal

Diagonal value(s) of the matrix.

If diagonal is a float, this value is repeated along the diagonal of the matrix. If diagonal is an array, it represents the full diagonal of the matrix.

__getitem__(index)

Slice into data by object ID or numpy indexing.

Extracts data from the matrix by object ID, a pair of IDs, or numpy indexing/slicing.

Parameters:

indexstr, two-tuple of str, or numpy index

index can be one of the following forms: an ID, a pair of IDs, or a numpy index.

If index is a string, it is assumed to be an ID and a numpy.ndarray row vector is returned for the corresponding ID. Note that the ID’s row of values is returned, not its column. If the matrix is symmetric, the two will be identical, but this makes a difference if the matrix is asymmetric.

If index is a two-tuple of strings, each string is assumed to be an ID and the corresponding matrix element is returned that represents the value between the two IDs. Note that the order of lookup by ID pair matters if the matrix is asymmetric: the first ID will be used to look up the row, and the second ID will be used to look up the column. Thus, dm['a', 'b'] may not be the same as dm['b', 'a'] if the matrix is asymmetric.

Otherwise, index will be passed through to PairwiseMatrix.data.__getitem__, allowing for standard indexing of a numpy.ndarray (e.g., slicing).

Returns:

ndarray or scalar

Indexed data, where return type depends on the form of index (see description of index for more details).

Raises:

MissingIDError

If the ID(s) specified in index are not in the matrix.

Notes

The lookup based on ID(s) is quick. NumPy indexing (slicing) on condensed form matrices will convert them to redundant, roughly doubling their memory requirement.