<commit_before>#!/usr/bin/env python
r"""
Distance matrices (:mod:`skbio.core.distance`)
==============================================

.. currentmodule:: skbio.core.distance

This module provides functionality for serializing, deserializing, and
manipulating distance matrices in memory. There are multiple distance matrix
classes available, where the appropriate class to use depends on the nature of
the distances you wish to store.

A distance matrix includes both a matrix of distances (floats) between objects,
as well as IDs (object labels; strings) identifying each object in the matrix.

Classes
-------

.. autosummary::
   :toctree: generated/

   DistanceMatrix
   SymmetricDistanceMatrix

Functions
---------

.. autosummary::
   :toctree: generated/

   randdm

Examples
--------
Assume we have the following delimited text file::

    \ta\tb\tc
    a\t0.0\t0.5\t1.0
    b\t0.5\t0.0\t0.75
    c\t1.0\t0.75\t0.0

Load a distance matrix from the file:

>>> from StringIO import StringIO
>>> from skbio.core.distance import DistanceMatrix
>>> dm_f = StringIO("\ta\tb\tc\n"
...                 "a\t0.0\t0.5\t1.0\n"
...                 "b\t0.5\t0.0\t0.75\n"
...                 "c\t1.0\t0.75\t0.0\n")
>>> dm = DistanceMatrix.from_file(dm_f)
>>> print dm
3x3 distance matrix
IDs:
a, b, c
Data:
[[ 0.    0.5   1.  ]
 [ 0.5   0.    0.75]
 [ 1.    0.75  0.  ]]

Access the distance (scalar) between objects ``'a'`` and ``'c'``:

>>> dm['a', 'c']
1.0

Get a row vector of distances between object ``'b'`` and all other objects:

>>> dm['b']
array([ 0.5 ,  0.  ,  0.75])

numpy indexing/slicing also works as expected. Extract the third column:

>>> dm[:, 2]
array([ 1.  ,  0.75,  0.  ])

Serialize the distance matrix to delimited text file:

>>> out_f = StringIO()
>>> dm.to_file(out_f)
>>> out_f.getvalue()
'\ta\tb\tc\na\t0.0\t0.5\t1.0\nb\t0.5\t0.0\t0.75\nc\t1.0\t0.75\t0.0\n'
>>> out_f.getvalue() == dm_f.getvalue()
True

"""
from __future__ import division

#-----------------------------------------------------------------------------
# Copyright (c) 2013--, scikit-bio development team.
#
# Distributed under the terms of the Modified BSD License.
#
# The full license is in the file COPYING.txt, distributed with this software.
#-----------------------------------------------------------------------------

from copy import deepcopy
from itertools import izip

import numpy as np
from scipy.spatial.distance import squareform

from skbio.core.exception import (DistanceMatrixError,
                                  DistanceMatrixFormatError, IDMismatchError,
                                  MissingDataError, MissingHeaderError,
                                  MissingIDError)


class DistanceMatrix(object):
    """Store distances between objects and object IDs.

    A `DistanceMatrix` instance stores a square, hollow, two-dimensional matrix
    of distances between objects. Objects could be, for example, samples or DNA
    sequences. A sequence of IDs accompanies the distances.

    Methods are provided to load and save distance matrices from/to disk, as
    well as perform common operations such as extracting distances based on ID.

    Parameters
    ----------
    data : array_like or DistanceMatrix
        Square, hollow, two-dimensional ``numpy.ndarray`` of distances
        (floats), or a structure that can be converted to a ``numpy.ndarray``
        using ``numpy.asarray``. Can instead be a `DistanceMatrix` instance, in
        which case the distance matrix'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``.
    ids : sequence of str
        Sequence of strings to be used as object IDs. Must match the number of
        rows/cols in `data`.

    Attributes
    ----------
    data
    ids
    dtype
    shape
    size
    T

    See Also
    --------
    SymmetricDistanceMatrix

    Notes
    -----
    The distances are stored in redundant (square-form) format [1]_.

    The data are not checked for symmetry, nor guaranteed/assumed to be
    symmetric.

    Examples
    --------
    Initialize a `skbio.core.distnace.DistanceMatrix` object from an existing
    ``numpy.array`` that represents the distances between  three samples with
    IDs a, b, and c.

    >>> from numpy import array
    >>> from skbio.core.distance import DistanceMatrix
    >>> data = array([[0.0,0.5,1.0],
    ...               [0.5,0.0,0.75],
    ...               [1.0,0.75,0.0]])
    >>> IDs = ["a", "b", "c"]
    >>> dm = DistanceMatrix(data, IDs)
    >>> print dm
    3x3 distance matrix
    IDs:
    a, b, c
    Data:
    [[ 0.    0.5   1.  ]
     [ 0.5   0.    0.75]
     [ 1.    0.75  0.  ]]

    References
    ----------
    .. [1] http://docs.scipy.org/doc/scipy/reference/spatial.distance.html

    """

    @classmethod
    def from_file(cls, dm_f, delimiter='\t'):
        """Load distance matrix from delimited text file.<commit_msg>Fix typos, import format for numpy, and var name<commit_after>#!/usr/bin/env python
r"""
Distance matrices (:mod:`skbio.core.distance`)
==============================================

.. currentmodule:: skbio.core.distance

This module provides functionality for serializing, deserializing, and
manipulating distance matrices in memory. There are multiple distance matrix
classes available, where the appropriate class to use depends on the nature of
the distances you wish to store.

A distance matrix includes both a matrix of distances (floats) between objects,
as well as IDs (object labels; strings) identifying each object in the matrix.

Classes
-------

.. autosummary::
   :toctree: generated/

   DistanceMatrix
   SymmetricDistanceMatrix

Functions
---------

.. autosummary::
   :toctree: generated/

   randdm

Examples
--------
Assume we have the following delimited text file::

    \ta\tb\tc
    a\t0.0\t0.5\t1.0
    b\t0.5\t0.0\t0.75
    c\t1.0\t0.75\t0.0

Load a distance matrix from the file:

>>> from StringIO import StringIO
>>> from skbio.core.distance import DistanceMatrix
>>> dm_f = StringIO("\ta\tb\tc\n"
...                 "a\t0.0\t0.5\t1.0\n"
...                 "b\t0.5\t0.0\t0.75\n"
...                 "c\t1.0\t0.75\t0.0\n")
>>> dm = DistanceMatrix.from_file(dm_f)
>>> print dm
3x3 distance matrix
IDs:
a, b, c
Data:
[[ 0.    0.5   1.  ]
 [ 0.5   0.    0.75]
 [ 1.    0.75  0.  ]]

Access the distance (scalar) between objects ``'a'`` and ``'c'``:

>>> dm['a', 'c']
1.0

Get a row vector of distances between object ``'b'`` and all other objects:

>>> dm['b']
array([ 0.5 ,  0.  ,  0.75])

numpy indexing/slicing also works as expected. Extract the third column:

>>> dm[:, 2]
array([ 1.  ,  0.75,  0.  ])

Serialize the distance matrix to delimited text file:

>>> out_f = StringIO()
>>> dm.to_file(out_f)
>>> out_f.getvalue()
'\ta\tb\tc\na\t0.0\t0.5\t1.0\nb\t0.5\t0.0\t0.75\nc\t1.0\t0.75\t0.0\n'
>>> out_f.getvalue() == dm_f.getvalue()
True

"""
from __future__ import division

#-----------------------------------------------------------------------------
# Copyright (c) 2013--, scikit-bio development team.
#
# Distributed under the terms of the Modified BSD License.
#
# The full license is in the file COPYING.txt, distributed with this software.
#-----------------------------------------------------------------------------

from copy import deepcopy
from itertools import izip

import numpy as np
from scipy.spatial.distance import squareform

from skbio.core.exception import (DistanceMatrixError,
                                  DistanceMatrixFormatError, IDMismatchError,
                                  MissingDataError, MissingHeaderError,
                                  MissingIDError)


class DistanceMatrix(object):
    """Store distances between objects and object IDs.

    A `DistanceMatrix` instance stores a square, hollow, two-dimensional matrix
    of distances between objects. Objects could be, for example, samples or DNA
    sequences. A sequence of IDs accompanies the distances.

    Methods are provided to load and save distance matrices from/to disk, as
    well as perform common operations such as extracting distances based on ID.

    Parameters
    ----------
    data : array_like or DistanceMatrix
        Square, hollow, two-dimensional ``numpy.ndarray`` of distances
        (floats), or a structure that can be converted to a ``numpy.ndarray``
        using ``numpy.asarray``. Can instead be a `DistanceMatrix` instance, in
        which case the distance matrix'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``.
    ids : sequence of str
        Sequence of strings to be used as object IDs. Must match the number of
        rows/cols in `data`.

    Attributes
    ----------
    data
    ids
    dtype
    shape
    size
    T

    See Also
    --------
    SymmetricDistanceMatrix

    Notes
    -----
    The distances are stored in redundant (square-form) format [1]_.

    The data are not checked for symmetry, nor guaranteed/assumed to be
    symmetric.

    References
    ----------
    .. [1] http://docs.scipy.org/doc/scipy/reference/spatial.distance.html

    Examples
    --------
    Initialize a `skbio.core.distance.DistanceMatrix` object from an existing
    ``numpy.array`` that represents the distances between three samples with
    IDs a, b, and c:

        0.0\t0.5\t1.0
        0.5\t0.0\t0.75
        1.0\t0.75\t0.0

    >>> import numpy as np
    >>> from skbio.core.distance import DistanceMatrix
    >>> data = np.array([[0.0,0.5,1.0],
    ...                  [0.5,0.0,0.75],
    ...                  [1.0,0.75,0.0]])
    >>> ids = ["a", "b", "c"]
    >>> dm = DistanceMatrix(data, ids)
    >>> print dm
    3x3 distance matrix
    ids:
    a, b, c
    Data:
    [[ 0.    0.5   1.  ]
     [ 0.5   0.    0.75]
     [ 1.    0.75  0.  ]]

    """

    @classmethod
    def from_file(cls, dm_f, delimiter='\t'):
        """Load distance matrix from delimited text file.
{'fraction_non_alphanumeric': 0.16193209937642283, 'fraction_numerical': 0.028506384242304266, 'mean_word_length': 2.142768273716952, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 111, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4496544', 'n_tokens_mistral': 3273, 'n_tokens_neox': 3080, 'n_words': 1024}