Skip to main content
`Ctrl`+`K`

# 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 (i.e., upper and lower triangles mirror each other). There are additional methods made available that take advantage of this symmetry.

  Added in version 0.7.1.

  Parameters:
    data 1-D or 2-D array_like, or PairwiseMatrix

      A square 2-D array of pairwise relationships between objects, or a 1-D array representing its condensed form. Can instead be an instance of `PairwiseMatrix` or its subclass, in which case its data and IDs will be directly used.

    ids sequence of str, optional

      IDs of the objects. Must match the number of objects in `data`. If None (default) and `data` does not contain IDs, IDs will be monotonically-increasing integers cast as strings, starting from zero (i.e., ‘0’, ‘1’, ‘2’, ‘3’, …).

    validate bool, optional

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

    condensed bool, optional

      Store the data in a 2-D redundant form (False, default) or a 1-D condensed form (True).

    diagonal 1-D array_like or float, optional

      Values along the diagonal of the matrix. Can be a vector matching the number of objects in `data`, or a single number representing a uniform diagonal. Default is zero. Can be provided when `data` is in condensed form. Otherwise, an error will be raised.

  See also

  `PairwiseMatrix`
  `SymmetricMatrix`
  `scipy.spatial.distance.squareform`

  Attributes

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

  Attributes (inherited)

  `data` | Array of pairwise relationships.
  `default_write_format` | Default write format for this object: `lsmat`.
  `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

  `as_condensed` | Return a condensed form deep copy of the matrix.
  `as_redundant` | Return a redundant form deep copy of the matrix.
  `condensed_form` | Return an array of distances in condensed format.
  `copy` | Return a deep copy of the symmetric matrix.
  `from_iterable` | Create a symmetric matrix from an iterable given a metric.
  `permute` | 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` | Obtain the pairwise values between the two groups of IDs.
  `filter` | Filter the matrix by IDs.
  `index` | Return the index of the specified ID.
  `plot` | Create a heatmap of the matrix.
  `read` | Create a new `SymmetricMatrix` instance from a file.
  `rename` | Rename IDs in the matrix.
  `to_data_frame` | Create a pandas DataFrame from this matrix.
  `within` | Obtain all the pairwise values among the set of IDs.
  `write` | Write an instance of `SymmetricMatrix` to a file.

  Special methods

  `__getitem__` | Slice into data by object ID or NumPy indexing.

  Special methods (inherited)

  `__contains__` | Check if the specified ID is in the matrix.
  `__eq__` | Compare this matrix to another for equality.
  `__ge__` | Return self>=value.
  `__getstate__` | Helper for pickle.
  `__gt__` | Return self>value.
  `__le__` | Return self<=value.
  `__lt__` | Return self<value.
  `__ne__` | 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:
      index str, two-tuple of str, or NumPy index

        Can be one of the following:

        - A string: Returns the row vector of this ID.

        - A tuple of two strings: Returns the value between the first ID (row) and the second ID (column).

        - Otherwise, `index` will be passed through to `.data.__getitem__`, allowing for standard indexing of a NumPy array (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.