c = np.asarray(c).ravel()<EOL>if r is None:<EOL><INDENT>r = c.conjugate()<EOL><DEDENT>else:<EOL><INDENT>r = np.asarray(r).ravel()<EOL><DEDENT>vals = np.concatenate((r[-<NUM_LIT:1>:<NUM_LIT:0>:-<NUM_LIT:1>], c))<EOL>a, b = np.ogrid[<NUM_LIT:0>:len(c), len(r) - <NUM_LIT:1>:-<NUM_LIT:1>:-<NUM_LIT:1>]<EOL>indx = a + b<EOL>return vals[indx]<EOL>

Construct a Toeplitz matrix.

The Toeplitz matrix has constant diagonals, with c as its first column
and r as its first row.  If r is not given, ``r == conjugate(c)`` is
assumed.

Parameters
----------
c : array_like
    First column of the matrix.  Whatever the actual shape of `c`, it
    will be converted to a 1-D array.
r : array_like
    First row of the matrix. If None, ``r = conjugate(c)`` is assumed;
    in this case, if c[0] is real, the result is a Hermitian matrix.
    r[0] is ignored; the first row of the returned matrix is
    ``[c[0], r[1:]]``.  Whatever the actual shape of `r`, it will be
    converted to a 1-D array.

Returns
-------
A : (len(c), len(r)) ndarray
    The Toeplitz matrix. Dtype is the same as ``(c[0] + r[0]).dtype``.

See also
--------
circulant : circulant matrix
hankel : Hankel matrix

Notes
-----
The behavior when `c` or `r` is a scalar, or when `c` is complex and
`r` is None, was changed in version 0.8.0.  The behavior in previous
versions was undocumented and is no longer supported.

Examples
--------
>>> from scipy.linalg import toeplitz
>>> toeplitz([1,2,3], [1,4,5,6])
array([[1, 4, 5, 6],
       [2, 1, 4, 5],
       [3, 2, 1, 4]])
>>> toeplitz([1.0, 2+3j, 4-1j])
array([[ 1.+0.j,  2.-3.j,  4.+1.j],
       [ 2.+3.j,  1.+0.j,  2.-3.j],
       [ 4.-1.j,  2.+3.j,  1.+0.j]])


c = np.asarray(c).ravel()<EOL>a, b = np.ogrid[<NUM_LIT:0>:len(c), <NUM_LIT:0>:-len(c):-<NUM_LIT:1>]<EOL>indx = a + b<EOL>return c[indx]<EOL>

Construct a circulant matrix.

Parameters
----------
c : (N,) array_like
    1-D array, the first column of the matrix.

Returns
-------
A : (N, N) ndarray
    A circulant matrix whose first column is `c`.

See also
--------
toeplitz : Toeplitz matrix
hankel : Hankel matrix

Notes
-----
.. versionadded:: 0.8.0

Examples
--------
>>> from scipy.linalg import circulant
>>> circulant([1, 2, 3])
array([[1, 3, 2],
       [2, 1, 3],
       [3, 2, 1]])


c = np.asarray(c).ravel()<EOL>if r is None:<EOL><INDENT>r = np.zeros_like(c)<EOL><DEDENT>else:<EOL><INDENT>r = np.asarray(r).ravel()<EOL><DEDENT>vals = np.concatenate((c, r[<NUM_LIT:1>:]))<EOL>a, b = np.ogrid[<NUM_LIT:0>:len(c), <NUM_LIT:0>:len(r)]<EOL>indx = a + b<EOL>return vals[indx]<EOL>

Construct a Hankel matrix.

The Hankel matrix has constant anti-diagonals, with `c` as its
first column and `r` as its last row.  If `r` is not given, then
`r = zeros_like(c)` is assumed.

Parameters
----------
c : array_like
    First column of the matrix.  Whatever the actual shape of `c`, it
    will be converted to a 1-D array.
r : array_like
    Last row of the matrix. If None, ``r = zeros_like(c)`` is assumed.
    r[0] is ignored; the last row of the returned matrix is
    ``[c[-1], r[1:]]``.  Whatever the actual shape of `r`, it will be
    converted to a 1-D array.

Returns
-------
A : (len(c), len(r)) ndarray
    The Hankel matrix. Dtype is the same as ``(c[0] + r[0]).dtype``.

See also
--------
toeplitz : Toeplitz matrix
circulant : circulant matrix

Examples
--------
>>> from scipy.linalg import hankel
>>> hankel([1, 17, 99])
array([[ 1, 17, 99],
       [17, 99,  0],
       [99,  0,  0]])
>>> hankel([1,2,3,4], [4,7,7,8,9])
array([[1, 2, 3, 4, 7],
       [2, 3, 4, 7, 7],
       [3, 4, 7, 7, 8],
       [4, 7, 7, 8, 9]])


<EOL>if n < <NUM_LIT:1>:<EOL><INDENT>lg2 = <NUM_LIT:0><EOL><DEDENT>else:<EOL><INDENT>lg2 = int(math.log(n, <NUM_LIT:2>))<EOL><DEDENT>if <NUM_LIT:2> ** lg2 != n:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT>H = np.array([[<NUM_LIT:1>]], dtype=dtype)<EOL>for i in range(<NUM_LIT:0>, lg2):<EOL><INDENT>H = np.vstack((np.hstack((H, H)), np.hstack((H, -H))))<EOL><DEDENT>return H<EOL>

Construct a Hadamard matrix.

Constructs an n-by-n Hadamard matrix, using Sylvester's
construction.  `n` must be a power of 2.

Parameters
----------
n : int
    The order of the matrix.  `n` must be a power of 2.
dtype : numpy dtype
    The data type of the array to be constructed.

Returns
-------
H : (n, n) ndarray
    The Hadamard matrix.

Notes
-----
.. versionadded:: 0.8.0

Examples
--------
>>> from scipy.linalg import hadamard
>>> hadamard(2, dtype=complex)
array([[ 1.+0.j,  1.+0.j],
       [ 1.+0.j, -1.-0.j]])
>>> hadamard(4)
array([[ 1,  1,  1,  1],
       [ 1, -1,  1, -1],
       [ 1,  1, -1, -1],
       [ 1, -1, -1,  1]])


f = np.atleast_1d(f)<EOL>s = np.atleast_1d(s)<EOL>if f.ndim != <NUM_LIT:1>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if s.ndim != <NUM_LIT:1>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if f.size != s.size + <NUM_LIT:1>:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT>if s.size == <NUM_LIT:0>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>tmp = f[<NUM_LIT:0>] + s[<NUM_LIT:0>]<EOL>n = f.size<EOL>a = np.zeros((n, n), dtype=tmp.dtype)<EOL>a[<NUM_LIT:0>] = f<EOL>a[list(range(<NUM_LIT:1>, n)), list(range(<NUM_LIT:0>, n - <NUM_LIT:1>))] = s<EOL>return a<EOL>

Create a Leslie matrix.

Given the length n array of fecundity coefficients `f` and the length
n-1 array of survival coefficents `s`, return the associated Leslie matrix.

Parameters
----------
f : (N,) array_like
    The "fecundity" coefficients.
s : (N-1,) array_like
    The "survival" coefficients, has to be 1-D.  The length of `s`
    must be one less than the length of `f`, and it must be at least 1.

Returns
-------
L : (N, N) ndarray
    The array is zero except for the first row,
    which is `f`, and the first sub-diagonal, which is `s`.
    The data-type of the array will be the data-type of ``f[0]+s[0]``.

Notes
-----
.. versionadded:: 0.8.0

The Leslie matrix is used to model discrete-time, age-structured
population growth [1]_ [2]_. In a population with `n` age classes, two sets
of parameters define a Leslie matrix: the `n` "fecundity coefficients",
which give the number of offspring per-capita produced by each age
class, and the `n` - 1 "survival coefficients", which give the
per-capita survival rate of each age class.

References
----------
.. [1] P. H. Leslie, On the use of matrices in certain population
       mathematics, Biometrika, Vol. 33, No. 3, 183--212 (Nov. 1945)
.. [2] P. H. Leslie, Some further notes on the use of matrices in
       population mathematics, Biometrika, Vol. 35, No. 3/4, 213--245
       (Dec. 1948)

Examples
--------
>>> from scipy.linalg import leslie
>>> leslie([0.1, 2.0, 1.0, 0.1], [0.2, 0.8, 0.7])
array([[ 0.1,  2. ,  1. ,  0.1],
       [ 0.2,  0. ,  0. ,  0. ],
       [ 0. ,  0.8,  0. ,  0. ],
       [ 0. ,  0. ,  0.7,  0. ]])


if not a.flags['<STR_LIT>']:<EOL><INDENT>a = np.reshape(a, a.shape)<EOL><DEDENT>if not b.flags['<STR_LIT>']:<EOL><INDENT>b = np.reshape(b, b.shape)<EOL><DEDENT>o = np.outer(a, b)<EOL>o = o.reshape(a.shape + b.shape)<EOL>return np.concatenate(np.concatenate(o, axis=<NUM_LIT:1>), axis=<NUM_LIT:1>)<EOL>

Kronecker product.

The result is the block matrix::

    a[0,0]*b    a[0,1]*b  ... a[0,-1]*b
    a[1,0]*b    a[1,1]*b  ... a[1,-1]*b
    ...
    a[-1,0]*b   a[-1,1]*b ... a[-1,-1]*b

Parameters
----------
a : (M, N) ndarray
    Input array
b : (P, Q) ndarray
    Input array

Returns
-------
A : (M*P, N*Q) ndarray
    Kronecker product of `a` and `b`.

Examples
--------
>>> from numpy import array
>>> from scipy.linalg import kron
>>> kron(array([[1,2],[3,4]]), array([[1,1,1]]))
array([[1, 1, 1, 2, 2, 2],
       [3, 3, 3, 4, 4, 4]])


if arrs == ():<EOL><INDENT>arrs = ([],)<EOL><DEDENT>arrs = [np.atleast_2d(a) for a in arrs]<EOL>bad_args = [k for k in range(len(arrs)) if arrs[k].ndim > <NUM_LIT:2>]<EOL>if bad_args:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>" % bad_args)<EOL><DEDENT>shapes = np.array([a.shape for a in arrs])<EOL>out = np.zeros(np.sum(shapes, axis=<NUM_LIT:0>), dtype=arrs[<NUM_LIT:0>].dtype)<EOL>r, c = <NUM_LIT:0>, <NUM_LIT:0><EOL>for i, (rr, cc) in enumerate(shapes):<EOL><INDENT>out[r:r + rr, c:c + cc] = arrs[i]<EOL>r += rr<EOL>c += cc<EOL><DEDENT>return out<EOL>

Create a block diagonal matrix from provided arrays.

Given the inputs `A`, `B` and `C`, the output will have these
arrays arranged on the diagonal::

    [[A, 0, 0],
     [0, B, 0],
     [0, 0, C]]

Parameters
----------
A, B, C, ... : array_like, up to 2-D
    Input arrays.  A 1-D array or array_like sequence of length `n`is
    treated as a 2-D array with shape ``(1,n)``.

Returns
-------
D : ndarray
    Array with `A`, `B`, `C`, ... on the diagonal.  `D` has the
    same dtype as `A`.

Notes
-----
If all the input arrays are square, the output is known as a
block diagonal matrix.

Examples
--------
>>> from scipy.linalg import block_diag
>>> A = [[1, 0],
...      [0, 1]]
>>> B = [[3, 4, 5],
...      [6, 7, 8]]
>>> C = [[7]]
>>> block_diag(A, B, C)
[[1 0 0 0 0 0]
 [0 1 0 0 0 0]
 [0 0 3 4 5 0]
 [0 0 6 7 8 0]
 [0 0 0 0 0 7]]
>>> block_diag(1.0, [2, 3], [[4, 5], [6, 7]])
array([[ 1.,  0.,  0.,  0.,  0.],
       [ 0.,  2.,  3.,  0.,  0.],
       [ 0.,  0.,  0.,  4.,  5.],
       [ 0.,  0.,  0.,  6.,  7.]])


a = np.atleast_1d(a)<EOL>if a.ndim != <NUM_LIT:1>:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT>if a.size < <NUM_LIT:2>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if a[<NUM_LIT:0>] == <NUM_LIT:0>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>first_row = -a[<NUM_LIT:1>:] / (<NUM_LIT:1.0> * a[<NUM_LIT:0>])<EOL>n = a.size<EOL>c = np.zeros((n - <NUM_LIT:1>, n - <NUM_LIT:1>), dtype=first_row.dtype)<EOL>c[<NUM_LIT:0>] = first_row<EOL>c[list(range(<NUM_LIT:1>, n - <NUM_LIT:1>)), list(range(<NUM_LIT:0>, n - <NUM_LIT:2>))] = <NUM_LIT:1><EOL>return c<EOL>

Create a companion matrix.

Create the companion matrix [1]_ associated with the polynomial whose
coefficients are given in `a`.

Parameters
----------
a : (N,) array_like
    1-D array of polynomial coefficients.  The length of `a` must be
    at least two, and ``a[0]`` must not be zero.

Returns
-------
c : (N-1, N-1) ndarray
    The first row of `c` is ``-a[1:]/a[0]``, and the first
    sub-diagonal is all ones.  The data-type of the array is the same
    as the data-type of ``1.0*a[0]``.

Raises
------
ValueError
    If any of the following are true: a) ``a.ndim != 1``;
    b) ``a.size < 2``; c) ``a[0] == 0``.

Notes
-----
.. versionadded:: 0.8.0

References
----------
.. [1] R. A. Horn & C. R. Johnson, *Matrix Analysis*.  Cambridge, UK:
    Cambridge University Press, 1999, pp. 146-7.

Examples
--------
>>> from scipy.linalg import companion
>>> companion([1, -10, 31, -30])
array([[ 10., -31.,  30.],
       [  1.,   0.,   0.],
       [  0.,   1.,   0.]])


values = <NUM_LIT:1.0> / (<NUM_LIT:1.0> + np.arange(<NUM_LIT:2> * n - <NUM_LIT:1>))<EOL>h = hankel(values[:n], r=values[n - <NUM_LIT:1>:])<EOL>return h<EOL>

Create a Hilbert matrix of order `n`.

Returns the `n` by `n` array with entries `h[i,j] = 1 / (i + j + 1)`.

Parameters
----------
n : int
    The size of the array to create.

Returns
-------
h : (n, n) ndarray
    The Hilbert matrix.

See Also
--------
invhilbert : Compute the inverse of a Hilbert matrix.

Notes
-----
.. versionadded:: 0.10.0

Examples
--------
>>> from scipy.linalg import hilbert
>>> hilbert(3)
array([[ 1.        ,  0.5       ,  0.33333333],
       [ 0.5       ,  0.33333333,  0.25      ],
       [ 0.33333333,  0.25      ,  0.2       ]])


from scipy.special import comb<EOL>if exact:<EOL><INDENT>if n > <NUM_LIT>:<EOL><INDENT>dtype = object<EOL><DEDENT>else:<EOL><INDENT>dtype = np.int64<EOL><DEDENT><DEDENT>else:<EOL><INDENT>dtype = np.float64<EOL><DEDENT>invh = np.empty((n, n), dtype=dtype)<EOL>for i in xrange(n):<EOL><INDENT>for j in xrange(<NUM_LIT:0>, i + <NUM_LIT:1>):<EOL><INDENT>s = i + j<EOL>invh[i, j] = ((-<NUM_LIT:1>) ** s * (s + <NUM_LIT:1>) *<EOL>comb(n + i, n - j - <NUM_LIT:1>, exact) *<EOL>comb(n + j, n - i - <NUM_LIT:1>, exact) *<EOL>comb(s, i, exact) ** <NUM_LIT:2>)<EOL>if i != j:<EOL><INDENT>invh[j, i] = invh[i, j]<EOL><DEDENT><DEDENT><DEDENT>return invh<EOL>

Compute the inverse of the Hilbert matrix of order `n`.

The entries in the inverse of a Hilbert matrix are integers.  When `n`
is greater than 14, some entries in the inverse exceed the upper limit
of 64 bit integers.  The `exact` argument provides two options for
dealing with these large integers.

Parameters
----------
n : int
    The order of the Hilbert matrix.
exact : bool
    If False, the data type of the array that is returned is np.float64,
    and the array is an approximation of the inverse.
    If True, the array is the exact integer inverse array.  To represent
    the exact inverse when n > 14, the returned array is an object array
    of long integers.  For n <= 14, the exact inverse is returned as an
    array with data type np.int64.

Returns
-------
invh : (n, n) ndarray
    The data type of the array is np.float64 if `exact` is False.
    If `exact` is True, the data type is either np.int64 (for n <= 14)
    or object (for n > 14).  In the latter case, the objects in the
    array will be long integers.

See Also
--------
hilbert : Create a Hilbert matrix.

Notes
-----
.. versionadded:: 0.10.0

Examples
--------
>>> from scipy.linalg import invhilbert
>>> invhilbert(4)
array([[   16.,  -120.,   240.,  -140.],
       [ -120.,  1200., -2700.,  1680.],
       [  240., -2700.,  6480., -4200.],
       [ -140.,  1680., -4200.,  2800.]])
>>> invhilbert(4, exact=True)
array([[   16,  -120,   240,  -140],
       [ -120,  1200, -2700,  1680],
       [  240, -2700,  6480, -4200],
       [ -140,  1680, -4200,  2800]], dtype=int64)
>>> invhilbert(16)[7,7]
4.2475099528537506e+19
>>> invhilbert(16, exact=True)[7,7]
42475099528537378560L


def pascal(n, kind='<STR_LIT>', exact=True):

from scipy.special import comb<EOL>if kind not in ['<STR_LIT>', '<STR_LIT>', '<STR_LIT>']:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if exact:<EOL><INDENT>if n >= <NUM_LIT>:<EOL><INDENT>L_n = np.empty((n, n), dtype=object)<EOL>L_n.fill(<NUM_LIT:0>)<EOL><DEDENT>else:<EOL><INDENT>L_n = np.zeros((n, n), dtype=np.uint64)<EOL><DEDENT>for i in range(n):<EOL><INDENT>for j in range(i + <NUM_LIT:1>):<EOL><INDENT>L_n[i, j] = comb(i, j, exact=True)<EOL><DEDENT><DEDENT><DEDENT>else:<EOL><INDENT>L_n = comb(*np.ogrid[:n, :n])<EOL><DEDENT>if kind is '<STR_LIT>':<EOL><INDENT>p = L_n<EOL><DEDENT>elif kind is '<STR_LIT>':<EOL><INDENT>p = L_n.T<EOL><DEDENT>else:<EOL><INDENT>p = np.dot(L_n, L_n.T)<EOL><DEDENT>return p<EOL>

Returns the n x n Pascal matrix.

The Pascal matrix is a matrix containing the binomial coefficients as
its elements.

Parameters
----------
n : int
    The size of the matrix to create; that is, the result is an n x n
    matrix.
kind : str, optional
    Must be one of 'symmetric', 'lower', or 'upper'.
    Default is 'symmetric'.
exact : bool, optional
    If `exact` is True, the result is either an array of type
    numpy.uint64 (if n < 35) or an object array of Python long integers.
    If `exact` is False, the coefficients in the matrix are computed using
    `scipy.special.comb` with `exact=False`.  The result will be a floating
    point array, and the values in the array will not be the exact
    coefficients, but this version is much faster than `exact=True`.

Returns
-------
p : (n, n) ndarray
    The Pascal matrix.

Notes
-----
See http://en.wikipedia.org/wiki/Pascal_matrix for more information
about Pascal matrices.

.. versionadded:: 0.11.0

Examples
--------
>>> from scipy.linalg import pascal
>>> pascal(4)
array([[ 1,  1,  1,  1],
       [ 1,  2,  3,  4],
       [ 1,  3,  6, 10],
       [ 1,  4, 10, 20]], dtype=uint64)
>>> pascal(4, kind='lower')
array([[1, 0, 0, 0],
       [1, 1, 0, 0],
       [1, 2, 1, 0],
       [1, 3, 3, 1]], dtype=uint64)
>>> pascal(50)[-1, -1]
25477612258980856902730428600L
>>> from scipy.special import comb
>>> comb(98, 49, exact=True)
25477612258980856902730428600L


if scale not in [None, '<STR_LIT>', '<STR_LIT:n>']:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>" % (scale,))<EOL><DEDENT>omegas = np.exp(-<NUM_LIT> * np.pi * np.arange(n) / n).reshape(-<NUM_LIT:1>, <NUM_LIT:1>)<EOL>m = omegas ** np.arange(n)<EOL>if scale == '<STR_LIT>':<EOL><INDENT>m /= math.sqrt(n)<EOL><DEDENT>elif scale == '<STR_LIT:n>':<EOL><INDENT>m /= n<EOL><DEDENT>return m<EOL>

Discrete Fourier transform matrix.

Create the matrix that computes the discrete Fourier transform of a
sequence [1]_.  The n-th primitive root of unity used to generate the
matrix is exp(-2*pi*i/n), where i = sqrt(-1).

Parameters
----------
n : int
    Size the matrix to create.
scale : str, optional
    Must be None, 'sqrtn', or 'n'.
    If `scale` is 'sqrtn', the matrix is divided by `sqrt(n)`.
    If `scale` is 'n', the matrix is divided by `n`.
    If `scale` is None (the default), the matrix is not normalized, and the
    return value is simply the Vandermonde matrix of the roots of unity.

Returns
-------
m : (n, n) ndarray
    The DFT matrix.

Notes
-----
When `scale` is None, multiplying a vector by the matrix returned by
`dft` is mathematically equivalent to (but much less efficient than)
the calculation performed by `scipy.fftpack.fft`.

.. versionadded:: 0.14.0

References
----------
.. [1] "DFT matrix", http://en.wikipedia.org/wiki/DFT_matrix

Examples
--------
>>> np.set_printoptions(precision=5, suppress=True)
>>> x = np.array([1, 2, 3, 0, 3, 2, 1, 0])
>>> m = dft(8)
>>> m.dot(x)   # Comute the DFT of x
array([ 12.+0.j,  -2.-2.j,   0.-4.j,  -2.+2.j,   4.+0.j,  -2.-2.j,
        -0.+4.j,  -2.+2.j])

Verify that ``m.dot(x)`` is the same as ``fft(x)``.

>>> from scipy.fftpack import fft
>>> fft(x)     # Same result as m.dot(x)
array([ 12.+0.j,  -2.-2.j,   0.-4.j,  -2.+2.j,   4.+0.j,  -2.-2.j,
         0.+4.j,  -2.+2.j])


std_dev = std(obs, axis=<NUM_LIT:0>)<EOL>zero_std_mask = std_dev == <NUM_LIT:0><EOL>if zero_std_mask.any():<EOL><INDENT>std_dev[zero_std_mask] = <NUM_LIT:1.0><EOL>warnings.warn("<STR_LIT>"<EOL>"<STR_LIT>",<EOL>RuntimeWarning)<EOL><DEDENT>return obs / std_dev<EOL>

Normalize a group of observations on a per feature basis.

Before running k-means, it is beneficial to rescale each feature
dimension of the observation set with whitening. Each feature is
divided by its standard deviation across all observations to give
it unit variance.

Parameters
----------
obs : ndarray
    Each row of the array is an observation.  The
    columns are the features seen during each observation.

    >>> #         f0    f1    f2
    >>> obs = [[  1.,   1.,   1.],  #o0
    ...        [  2.,   2.,   2.],  #o1
    ...        [  3.,   3.,   3.],  #o2
    ...        [  4.,   4.,   4.]]  #o3

Returns
-------
result : ndarray
    Contains the values in `obs` scaled by the standard deviation
    of each column.

Examples
--------
>>> from scipy.cluster.vq import whiten
>>> features  = np.array([[1.9, 2.3, 1.7],
...                       [1.5, 2.5, 2.2],
...                       [0.8, 0.6, 1.7,]])
>>> whiten(features)
array([[ 4.17944278,  2.69811351,  7.21248917],
       [ 3.29956009,  2.93273208,  9.33380951],
       [ 1.75976538,  0.7038557 ,  7.21248917]])


ct = common_type(obs, code_book)<EOL>if obs.dtype != ct:<EOL><INDENT>c_obs = obs.astype(ct)<EOL><DEDENT>else:<EOL><INDENT>c_obs = obs<EOL><DEDENT>if code_book.dtype != ct:<EOL><INDENT>c_code_book = code_book.astype(ct)<EOL><DEDENT>else:<EOL><INDENT>c_code_book = code_book<EOL><DEDENT>if ct in (single, double):<EOL><INDENT>results = _vq.vq(c_obs, c_code_book)<EOL><DEDENT>else:<EOL><INDENT>results = py_vq(obs, code_book)<EOL><DEDENT>return results<EOL>

Assign codes from a code book to observations.

Assigns a code from a code book to each observation. Each
observation vector in the 'M' by 'N' `obs` array is compared with the
centroids in the code book and assigned the code of the closest
centroid.

The features in `obs` should have unit variance, which can be
achieved by passing them through the whiten function.  The code
book can be created with the k-means algorithm or a different
encoding algorithm.

Parameters
----------
obs : ndarray
    Each row of the 'M' x 'N' array is an observation.  The columns are
    the "features" seen during each observation. The features must be
    whitened first using the whiten function or something equivalent.
code_book : ndarray
    The code book is usually generated using the k-means algorithm.
    Each row of the array holds a different code, and the columns are
    the features of the code.

     >>> #              f0    f1    f2   f3
     >>> code_book = [
     ...             [  1.,   2.,   3.,   4.],  #c0
     ...             [  1.,   2.,   3.,   4.],  #c1
     ...             [  1.,   2.,   3.,   4.]]  #c2

Returns
-------
code : ndarray
    A length M array holding the code book index for each observation.
dist : ndarray
    The distortion (distance) between the observation and its nearest
    code.

Examples
--------
>>> from numpy import array
>>> from scipy.cluster.vq import vq
>>> code_book = array([[1.,1.,1.],
...                    [2.,2.,2.]])
>>> features  = array([[  1.9,2.3,1.7],
...                    [  1.5,2.5,2.2],
...                    [  0.8,0.6,1.7]])
>>> vq(features,code_book)
(array([1, 1, 0],'i'), array([ 0.43588989,  0.73484692,  0.83066239]))


<EOL>if np.ndim(obs) == <NUM_LIT:1>:<EOL><INDENT>if not np.ndim(obs) == np.ndim(code_book):<EOL><INDENT>raise ValueError(<EOL>"<STR_LIT>")<EOL><DEDENT>else:<EOL><INDENT>return _py_vq_1d(obs, code_book)<EOL><DEDENT><DEDENT>else:<EOL><INDENT>(n, d) = shape(obs)<EOL><DEDENT>if not np.ndim(obs) == np.ndim(code_book):<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>elif not d == code_book.shape[<NUM_LIT:1>]:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>""<STR_LIT>" %<EOL>(code_book.shape[<NUM_LIT:1>], d))<EOL><DEDENT>code = zeros(n, dtype=int)<EOL>min_dist = zeros(n)<EOL>for i in range(n):<EOL><INDENT>dist = np.sum((obs[i] - code_book) ** <NUM_LIT:2>, <NUM_LIT:1>)<EOL>code[i] = argmin(dist)<EOL>min_dist[i] = dist[code[i]]<EOL><DEDENT>return code, sqrt(min_dist)<EOL>

Python version of vq algorithm.

    The algorithm computes the euclidian distance between each
    observation and every frame in the code_book.

    Parameters
    ----------
    obs : ndarray
        Expects a rank 2 array. Each row is one observation.
    code_book : ndarray
        Code book to use. Same format than obs. Should have same number of
        features (eg columns) than obs.

    Returns
    -------
    code : ndarray
        code[i] gives the label of the ith obversation, that its code is
        code_book[code[i]].
    mind_dist : ndarray
        min_dist[i] gives the distance between the ith observation and its
        corresponding code.

    Notes
    -----
    This function is slower than the C version but works for
    all input types.  If the inputs have the wrong types for the
    C versions of the function, this one is called as a last resort.

    It is about 20 times slower than the C version.


raise RuntimeError("<STR_LIT>")<EOL>n = obs.size<EOL>nc = code_book.size<EOL>dist = np.zeros((n, nc))<EOL>for i in range(nc):<EOL><INDENT>dist[:, i] = np.sum(obs - code_book[i])<EOL><DEDENT>print(dist)<EOL>code = argmin(dist)<EOL>min_dist = dist[code]<EOL>return code, sqrt(min_dist)<EOL>

Python version of vq algorithm for rank 1 only.

    Parameters
    ----------
    obs : ndarray
        Expects a rank 1 array. Each item is one observation.
    code_book : ndarray
        Code book to use. Same format than obs. Should rank 1 too.

    Returns
    -------
    code : ndarray
        code[i] gives the label of the ith obversation, that its code is
        code_book[code[i]].
    mind_dist : ndarray
        min_dist[i] gives the distance between the ith observation and its
        corresponding code.


d = shape(obs)[<NUM_LIT:1>]<EOL>if not d == code_book.shape[<NUM_LIT:1>]:<EOL><INDENT>raise ValueError("""<STR_LIT>""" % (code_book.shape[<NUM_LIT:1>], d))<EOL><DEDENT>diff = obs[newaxis, :, :] - code_book[:,newaxis,:]<EOL>dist = sqrt(np.sum(diff * diff, -<NUM_LIT:1>))<EOL>code = argmin(dist, <NUM_LIT:0>)<EOL>min_dist = minimum.reduce(dist, <NUM_LIT:0>)<EOL>return code, min_dist<EOL>

2nd Python version of vq algorithm.

    The algorithm simply computes the euclidian distance between each
    observation and every frame in the code_book/

    Parameters
    ----------
    obs : ndarray
        Expect a rank 2 array. Each row is one observation.
    code_book : ndarray
        Code book to use. Same format than obs. Should have same number of
        features (eg columns) than obs.

    Returns
    -------
    code : ndarray
        code[i] gives the label of the ith obversation, that its code is
        code_book[code[i]].
    mind_dist : ndarray
        min_dist[i] gives the distance between the ith observation and its
        corresponding code.

    Notes
    -----
    This could be faster when number of codebooks is small, but it
    becomes a real memory hog when codebook is large. It requires
    N by M by O storage where N=number of obs, M = number of
    features, and O = number of codes.


def _kmeans(obs, guess, thresh=<NUM_LIT>):

code_book = array(guess, copy=True)<EOL>avg_dist = []<EOL>diff = thresh+<NUM_LIT:1.><EOL>while diff > thresh:<EOL><INDENT>nc = code_book.shape[<NUM_LIT:0>]<EOL>obs_code, distort = vq(obs, code_book)<EOL>avg_dist.append(mean(distort, axis=-<NUM_LIT:1>))<EOL>if(diff > thresh):<EOL><INDENT>code_book, has_members = _vq.update_cluster_means(obs, obs_code, nc)<EOL>code_book = code_book.compress(has_members, axis=<NUM_LIT:0>)<EOL><DEDENT>if len(avg_dist) > <NUM_LIT:1>:<EOL><INDENT>diff = avg_dist[-<NUM_LIT:2>] - avg_dist[-<NUM_LIT:1>]<EOL><DEDENT><DEDENT>return code_book, avg_dist[-<NUM_LIT:1>]<EOL>

raw" version of k-means.

    Returns
    -------
    code_book :
        the lowest distortion codebook found.
    avg_dist :
        the average distance a observation is from a code in the book.
        Lower means the code_book matches the data better.

    See Also
    --------
    kmeans : wrapper around k-means

    Examples
    --------
    Note: not whitened in this example.

    >>> from numpy import array
    >>> from scipy.cluster.vq import _kmeans
    >>> features  = array([[ 1.9,2.3],
    ...                    [ 1.5,2.5],
    ...                    [ 0.8,0.6],
    ...                    [ 0.4,1.8],
    ...                    [ 1.0,1.0]])
    >>> book = array((features[0],features[2]))
    >>> _kmeans(features,book)
    (array([[ 1.7       ,  2.4       ],
           [ 0.73333333,  1.13333333]]), 0.40563916697728591)


def kmeans(obs, k_or_guess, iter=<NUM_LIT:20>, thresh=<NUM_LIT>):

if int(iter) < <NUM_LIT:1>:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>if type(k_or_guess) == type(array([])):<EOL><INDENT>guess = k_or_guess<EOL>if guess.size < <NUM_LIT:1>:<EOL><INDENT>raise ValueError("<STR_LIT>" %<EOL>guess)<EOL><DEDENT>result = _kmeans(obs, guess, thresh=thresh)<EOL><DEDENT>else:<EOL><INDENT>best_dist = np.inf<EOL>No = obs.shape[<NUM_LIT:0>]<EOL>k = k_or_guess<EOL>if k < <NUM_LIT:1>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>for i in range(iter):<EOL><INDENT>guess = take(obs, randint(<NUM_LIT:0>, No, k), <NUM_LIT:0>)<EOL>book, dist = _kmeans(obs, guess, thresh=thresh)<EOL>if dist < best_dist:<EOL><INDENT>best_book = book<EOL>best_dist = dist<EOL><DEDENT><DEDENT>result = best_book, best_dist<EOL><DEDENT>return result<EOL>

Performs k-means on a set of observation vectors forming k clusters.

The k-means algorithm adjusts the centroids until sufficient
progress cannot be made, i.e. the change in distortion since
the last iteration is less than some threshold. This yields
a code book mapping centroids to codes and vice versa.

Distortion is defined as the sum of the squared differences
between the observations and the corresponding centroid.

Parameters
----------
obs : ndarray
   Each row of the M by N array is an observation vector. The
   columns are the features seen during each observation.
   The features must be whitened first with the `whiten` function.

k_or_guess : int or ndarray
   The number of centroids to generate. A code is assigned to
   each centroid, which is also the row index of the centroid
   in the code_book matrix generated.

   The initial k centroids are chosen by randomly selecting
   observations from the observation matrix. Alternatively,
   passing a k by N array specifies the initial k centroids.

iter : int, optional
   The number of times to run k-means, returning the codebook
   with the lowest distortion. This argument is ignored if
   initial centroids are specified with an array for the
   ``k_or_guess`` parameter. This parameter does not represent the
   number of iterations of the k-means algorithm.

thresh : float, optional
   Terminates the k-means algorithm if the change in
   distortion since the last k-means iteration is less than
   or equal to thresh.

Returns
-------
codebook : ndarray
   A k by N array of k centroids. The i'th centroid
   codebook[i] is represented with the code i. The centroids
   and codes generated represent the lowest distortion seen,
   not necessarily the globally minimal distortion.

distortion : float
   The distortion between the observations passed and the
   centroids generated.

See Also
--------
kmeans2 : a different implementation of k-means clustering
   with more methods for generating initial centroids but without
   using a distortion change threshold as a stopping criterion.

whiten : must be called prior to passing an observation matrix
   to kmeans.

Examples
--------
>>> from numpy import array
>>> from scipy.cluster.vq import vq, kmeans, whiten
>>> features  = array([[ 1.9,2.3],
...                    [ 1.5,2.5],
...                    [ 0.8,0.6],
...                    [ 0.4,1.8],
...                    [ 0.1,0.1],
...                    [ 0.2,1.8],
...                    [ 2.0,0.5],
...                    [ 0.3,1.5],
...                    [ 1.0,1.0]])
>>> whitened = whiten(features)
>>> book = array((whitened[0],whitened[2]))
>>> kmeans(whitened,book)
(array([[ 2.3110306 ,  2.86287398],
       [ 0.93218041,  1.24398691]]), 0.85684700941625547)

>>> from numpy import random
>>> random.seed((1000,2000))
>>> codes = 3
>>> kmeans(whitened,codes)
(array([[ 2.3110306 ,  2.86287398],
       [ 1.32544402,  0.65607529],
       [ 0.40782893,  2.02786907]]), 0.5196582527686241)


if data.ndim > <NUM_LIT:1>:<EOL><INDENT>n = data.shape[<NUM_LIT:0>]<EOL><DEDENT>else:<EOL><INDENT>n = data.size<EOL><DEDENT>p = np.random.permutation(n)<EOL>x = data[p[:k], :].copy()<EOL>return x<EOL>

Pick k points at random in data (one row = one observation).

    This is done by taking the k first values of a random permutation of 1..N
    where N is the number of observation.

    Parameters
    ----------
    data : ndarray
        Expect a rank 1 or 2 array. Rank 1 are assumed to describe one
        dimensional data, rank 2 multidimensional data, in which case one
        row is one observation.
    k : int
        Number of samples to generate.


def init_rank1(data):<EOL><INDENT>mu = np.mean(data)<EOL>cov = np.cov(data)<EOL>x = np.random.randn(k)<EOL>x *= np.sqrt(cov)<EOL>x += mu<EOL>return x<EOL><DEDENT>def init_rankn(data):<EOL><INDENT>mu = np.mean(data, <NUM_LIT:0>)<EOL>cov = np.atleast_2d(np.cov(data, rowvar=<NUM_LIT:0>))<EOL>x = np.random.randn(k, mu.size)<EOL>x = np.dot(x, np.linalg.cholesky(cov).T) + mu<EOL>return x<EOL><DEDENT>nd = np.ndim(data)<EOL>if nd == <NUM_LIT:1>:<EOL><INDENT>return init_rank1(data)<EOL><DEDENT>else:<EOL><INDENT>return init_rankn(data)<EOL><DEDENT>

Returns k samples of a random variable which parameters depend on data.

    More precisely, it returns k observations sampled from a Gaussian random
    variable which mean and covariances are the one estimated from data.

    Parameters
    ----------
    data : ndarray
        Expect a rank 1 or 2 array. Rank 1 are assumed to describe one
        dimensional data, rank 2 multidimensional data, in which case one
        row is one observation.
    k : int
        Number of samples to generate.


warnings.warn("<STR_LIT>"<EOL>"<STR_LIT>")<EOL>


raise ClusterError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL>


def kmeans2(data, k, iter=<NUM_LIT:10>, thresh=<NUM_LIT>, minit='<STR_LIT>',<EOL>missing='<STR_LIT>'):

if missing not in _valid_miss_meth:<EOL><INDENT>raise ValueError("<STR_LIT>" % str(missing))<EOL><DEDENT>nd = np.ndim(data)<EOL>if nd == <NUM_LIT:1>:<EOL><INDENT>d = <NUM_LIT:1><EOL><DEDENT>elif nd == <NUM_LIT:2>:<EOL><INDENT>d = data.shape[<NUM_LIT:1>]<EOL><DEDENT>else:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if np.size(data) < <NUM_LIT:1>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if np.size(k) > <NUM_LIT:1> or minit == '<STR_LIT>':<EOL><INDENT>if not nd == np.ndim(k):<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if d == <NUM_LIT:1>:<EOL><INDENT>nc = len(k)<EOL><DEDENT>else:<EOL><INDENT>(nc, dc) = k.shape<EOL>if not dc == d:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT><DEDENT>clusters = k.copy()<EOL><DEDENT>else:<EOL><INDENT>try:<EOL><INDENT>nc = int(k)<EOL><DEDENT>except TypeError:<EOL><INDENT>raise ValueError("<STR_LIT>" % str(k))<EOL><DEDENT>if nc < <NUM_LIT:1>:<EOL><INDENT>raise ValueError("<STR_LIT>" % str(k))<EOL><DEDENT>if not nc == k:<EOL><INDENT>warnings.warn("<STR_LIT>")<EOL><DEDENT>try:<EOL><INDENT>init = _valid_init_meth[minit]<EOL><DEDENT>except KeyError:<EOL><INDENT>raise ValueError("<STR_LIT>" % str(minit))<EOL><DEDENT>clusters = init(data, k)<EOL><DEDENT>if int(iter) < <NUM_LIT:1>:<EOL><INDENT>raise ValueError("<STR_LIT>" % iter)<EOL><DEDENT>return _kmeans2(data, clusters, iter, nc, _valid_miss_meth[missing])<EOL>

Classify a set of observations into k clusters using the k-means algorithm.

The algorithm attempts to minimize the Euclidian distance between
observations and centroids. Several initialization methods are
included.

Parameters
----------
data : ndarray
    A 'M' by 'N' array of 'M' observations in 'N' dimensions or a length
    'M' array of 'M' one-dimensional observations.
k : int or ndarray
    The number of clusters to form as well as the number of
    centroids to generate. If `minit` initialization string is
    'matrix', or if a ndarray is given instead, it is
    interpreted as initial cluster to use instead.
iter : int
    Number of iterations of the k-means algrithm to run. Note
    that this differs in meaning from the iters parameter to
    the kmeans function.
thresh : float
    (not used yet)
minit : string
    Method for initialization. Available methods are 'random',
    'points', 'uniform', and 'matrix':

    'random': generate k centroids from a Gaussian with mean and
    variance estimated from the data.

    'points': choose k observations (rows) at random from data for
    the initial centroids.

    'uniform': generate k observations from the data from a uniform
    distribution defined by the data set (unsupported).

    'matrix': interpret the k parameter as a k by M (or length k
    array for one-dimensional data) array of initial centroids.
missing : string
    Method to deal with empty clusters. Available methods are
    'warn' and 'raise':

    'warn': give a warning and continue.

    'raise': raise an ClusterError and terminate the algorithm.

Returns
-------
centroid : ndarray
    A 'k' by 'N' array of centroids found at the last iteration of
    k-means.
label : ndarray
    label[i] is the code or index of the centroid the
    i'th observation is closest to.


def _kmeans2(data, code, niter, nc, missing):

for i in range(niter):<EOL><INDENT>label = vq(data, code)[<NUM_LIT:0>]<EOL>new_code, has_members = _vq.update_cluster_means(data, label, nc)<EOL>if not has_members.all():<EOL><INDENT>missing()<EOL>new_code[~has_members] = code[~has_members]<EOL><DEDENT>code = new_code<EOL><DEDENT>return code, label<EOL>

raw" version of kmeans2. Do not use directly.

    Run k-means with a given initial codebook.


if a.base is not None:<EOL><INDENT>return a.copy()<EOL><DEDENT>elif np.issubsctype(a, np.float32):<EOL><INDENT>return np.array(a, dtype=np.double)<EOL><DEDENT>else:<EOL><INDENT>return a<EOL><DEDENT>

Copies the array if its base points to a parent array.


l = [_copy_array_if_base_present(a) for a in T]<EOL>return l<EOL>

Accepts a tuple of arrays T. Copies the array T[i] if its base array
points to an actual array. Otherwise, the reference is just copied.
This is useful if the arrays are being passed to a C function that
does not do proper striding.


if pnts >= <NUM_LIT:2>:<EOL><INDENT>D = np.random.rand(pnts * (pnts - <NUM_LIT:1>) / <NUM_LIT:2>)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT>return D<EOL>

Generates a random distance matrix stored in condensed form. A
        pnts * (pnts - 1) / 2 sized vector is returned.


return linkage(y, method='<STR_LIT>', metric='<STR_LIT>')<EOL>

Performs single/min/nearest linkage on the condensed distance matrix ``y``

Parameters
----------
y : ndarray
    The upper triangular of the distance matrix. The result of
    ``pdist`` is returned in this form.

Returns
-------
Z : ndarray
    The linkage matrix.

See Also
--------
linkage: for advanced creation of hierarchical clusterings.


Performs complete/max/farthest point linkage on a condensed distance matrix

Parameters
----------
y : ndarray
    The upper triangular of the distance matrix. The result of
    ``pdist`` is returned in this form.

Returns
-------
Z : ndarray
    A linkage matrix containing the hierarchical clustering. See
    the ``linkage`` function documentation for more information
    on its structure.

See Also
--------
linkage


Performs average/UPGMA linkage on a condensed distance matrix

Parameters
----------
y : ndarray
    The upper triangular of the distance matrix. The result of
    ``pdist`` is returned in this form.

Returns
-------
Z : ndarray
    A linkage matrix containing the hierarchical clustering. See
    the ``linkage`` function documentation for more information
    on its structure.

See Also
--------
linkage: for advanced creation of hierarchical clusterings.


Performs weighted/WPGMA linkage on the condensed distance matrix.

See ``linkage`` for more information on the return
structure and algorithm.

Parameters
----------
y : ndarray
    The upper triangular of the distance matrix. The result of
    ``pdist`` is returned in this form.

Returns
-------
Z : ndarray
    A linkage matrix containing the hierarchical clustering. See
    the ``linkage`` function documentation for more information
    on its structure.

See Also
--------
linkage : for advanced creation of hierarchical clusterings.


Performs centroid/UPGMC linkage.

See ``linkage`` for more information on the return structure
and algorithm.

The following are common calling conventions:

1. ``Z = centroid(y)``

   Performs centroid/UPGMC linkage on the condensed distance
   matrix ``y``.  See ``linkage`` for more information on the return
   structure and algorithm.

2. ``Z = centroid(X)``

   Performs centroid/UPGMC linkage on the observation matrix ``X``
   using Euclidean distance as the distance metric. See ``linkage``
   for more information on the return structure and algorithm.

Parameters
----------
Q : ndarray
    A condensed or redundant distance matrix. A condensed
    distance matrix is a flat array containing the upper
    triangular of the distance matrix. This is the form that
    ``pdist`` returns. Alternatively, a collection of
    m observation vectors in n dimensions may be passed as
    a m by n array.

Returns
-------
Z : ndarray
    A linkage matrix containing the hierarchical clustering. See
    the ``linkage`` function documentation for more information
    on its structure.

See Also
--------
linkage: for advanced creation of hierarchical clusterings.


Performs median/WPGMC linkage.

See ``linkage`` for more information on the return structure
and algorithm.

 The following are common calling conventions:

 1. ``Z = median(y)``

    Performs median/WPGMC linkage on the condensed distance matrix
    ``y``.  See ``linkage`` for more information on the return
    structure and algorithm.

 2. ``Z = median(X)``

    Performs median/WPGMC linkage on the observation matrix ``X``
    using Euclidean distance as the distance metric. See linkage
    for more information on the return structure and algorithm.

Parameters
----------
Q : ndarray
    A condensed or redundant distance matrix. A condensed
    distance matrix is a flat array containing the upper
    triangular of the distance matrix. This is the form that
    ``pdist`` returns. Alternatively, a collection of
    m observation vectors in n dimensions may be passed as
    a m by n array.

Returns
-------
Z : ndarray
    The hierarchical clustering encoded as a linkage matrix.

See Also
--------
linkage: for advanced creation of hierarchical clusterings.


Performs Ward's linkage on a condensed or redundant distance matrix.

See linkage for more information on the return structure
and algorithm.

The following are common calling conventions:

1. ``Z = ward(y)``
   Performs Ward's linkage on the condensed distance matrix ``Z``. See
   linkage for more information on the return structure and
   algorithm.

2. ``Z = ward(X)``
   Performs Ward's linkage on the observation matrix ``X`` using
   Euclidean distance as the distance metric. See linkage for more
   information on the return structure and algorithm.

Parameters
----------
Q : ndarray
    A condensed or redundant distance matrix. A condensed
    distance matrix is a flat array containing the upper
    triangular of the distance matrix. This is the form that
    ``pdist`` returns. Alternatively, a collection of
    m observation vectors in n dimensions may be passed as
    a m by n array.

Returns
-------
Z : ndarray
    The hierarchical clustering encoded as a linkage matrix.

See Also
--------
linkage: for advanced creation of hierarchical clusterings.


def linkage(y, method='<STR_LIT>', metric='<STR_LIT>'):

if not isinstance(method, string_types):<EOL><INDENT>raise TypeError("<STR_LIT>")<EOL><DEDENT>y = _convert_to_double(np.asarray(y, order='<STR_LIT:c>'))<EOL>s = y.shape<EOL>if len(s) == <NUM_LIT:1>:<EOL><INDENT>distance.is_valid_y(y, throw=True, name='<STR_LIT:y>')<EOL>d = distance.num_obs_y(y)<EOL>if method not in _cpy_non_euclid_methods:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT>[y] = _copy_arrays_if_base_present([y])<EOL>Z = np.zeros((d - <NUM_LIT:1>, <NUM_LIT:4>))<EOL>if method == '<STR_LIT>':<EOL><INDENT>_hierarchy.slink(y, Z, int(d))<EOL><DEDENT>else:<EOL><INDENT>_hierarchy.linkage(y, Z, int(d),<EOL>int(_cpy_non_euclid_methods[method]))<EOL><DEDENT><DEDENT>elif len(s) == <NUM_LIT:2>:<EOL><INDENT>X = y<EOL>n = s[<NUM_LIT:0>]<EOL>if method not in _cpy_linkage_methods:<EOL><INDENT>raise ValueError('<STR_LIT>' % method)<EOL><DEDENT>if method in _cpy_non_euclid_methods:<EOL><INDENT>dm = distance.pdist(X, metric)<EOL>Z = np.zeros((n - <NUM_LIT:1>, <NUM_LIT:4>))<EOL>if method == '<STR_LIT>':<EOL><INDENT>_hierarchy.slink(dm, Z, n)<EOL><DEDENT>else:<EOL><INDENT>_hierarchy.linkage(dm, Z, n,<EOL>int(_cpy_non_euclid_methods[method]))<EOL><DEDENT><DEDENT>elif method in _cpy_euclid_methods:<EOL><INDENT>if metric != '<STR_LIT>':<EOL><INDENT>raise ValueError(("<STR_LIT>"<EOL>"<STR_LIT>") % method)<EOL><DEDENT>dm = distance.pdist(X, metric)<EOL>Z = np.zeros((n - <NUM_LIT:1>, <NUM_LIT:4>))<EOL>_hierarchy.linkage(dm, Z, n,<EOL>int(_cpy_euclid_methods[method]))<EOL><DEDENT><DEDENT>return Z<EOL>

Performs hierarchical/agglomerative clustering on the condensed
distance matrix y.

y must be a :math:`{n \\choose 2}` sized
vector where n is the number of original observations paired
in the distance matrix. The behavior of this function is very
similar to the MATLAB linkage function.

A 4 by :math:`(n-1)` matrix ``Z`` is returned. At the
:math:`i`-th iteration, clusters with indices ``Z[i, 0]`` and
``Z[i, 1]`` are combined to form cluster :math:`n + i`. A
cluster with an index less than :math:`n` corresponds to one of
the :math:`n` original observations. The distance between
clusters ``Z[i, 0]`` and ``Z[i, 1]`` is given by ``Z[i, 2]``. The
fourth value ``Z[i, 3]`` represents the number of original
observations in the newly formed cluster.

The following linkage methods are used to compute the distance
:math:`d(s, t)` between two clusters :math:`s` and
:math:`t`. The algorithm begins with a forest of clusters that
have yet to be used in the hierarchy being formed. When two
clusters :math:`s` and :math:`t` from this forest are combined
into a single cluster :math:`u`, :math:`s` and :math:`t` are
removed from the forest, and :math:`u` is added to the
forest. When only one cluster remains in the forest, the algorithm
stops, and this cluster becomes the root.

A distance matrix is maintained at each iteration. The ``d[i,j]``
entry corresponds to the distance between cluster :math:`i` and
:math:`j` in the original forest.

At each iteration, the algorithm must update the distance matrix
to reflect the distance of the newly formed cluster u with the
remaining clusters in the forest.

Suppose there are :math:`|u|` original observations
:math:`u[0], \\ldots, u[|u|-1]` in cluster :math:`u` and
:math:`|v|` original objects :math:`v[0], \\ldots, v[|v|-1]` in
cluster :math:`v`. Recall :math:`s` and :math:`t` are
combined to form cluster :math:`u`. Let :math:`v` be any
remaining cluster in the forest that is not :math:`u`.

The following are methods for calculating the distance between the
newly formed cluster :math:`u` and each :math:`v`.

  * method='single' assigns

    .. math::
       d(u,v) = \\min(dist(u[i],v[j]))

    for all points :math:`i` in cluster :math:`u` and
    :math:`j` in cluster :math:`v`. This is also known as the
    Nearest Point Algorithm.

  * method='complete' assigns

    .. math::
       d(u, v) = \\max(dist(u[i],v[j]))

    for all points :math:`i` in cluster u and :math:`j` in
    cluster :math:`v`. This is also known by the Farthest Point
    Algorithm or Voor Hees Algorithm.

  * method='average' assigns

    .. math::
       d(u,v) = \\sum_{ij} \\frac{d(u[i], v[j])}
                               {(|u|*|v|)}

    for all points :math:`i` and :math:`j` where :math:`|u|`
    and :math:`|v|` are the cardinalities of clusters :math:`u`
    and :math:`v`, respectively. This is also called the UPGMA
    algorithm.

  * method='weighted' assigns

    .. math::
       d(u,v) = (dist(s,v) + dist(t,v))/2

    where cluster u was formed with cluster s and t and v
    is a remaining cluster in the forest. (also called WPGMA)

  * method='centroid' assigns

    .. math::
       dist(s,t) = ||c_s-c_t||_2

    where :math:`c_s` and :math:`c_t` are the centroids of
    clusters :math:`s` and :math:`t`, respectively. When two
    clusters :math:`s` and :math:`t` are combined into a new
    cluster :math:`u`, the new centroid is computed over all the
    original objects in clusters :math:`s` and :math:`t`. The
    distance then becomes the Euclidean distance between the
    centroid of :math:`u` and the centroid of a remaining cluster
    :math:`v` in the forest. This is also known as the UPGMC
    algorithm.

  * method='median' assigns math:`d(s,t)` like the ``centroid``
    method. When two clusters :math:`s` and :math:`t` are combined
    into a new cluster :math:`u`, the average of centroids s and t
    give the new centroid :math:`u`. This is also known as the
    WPGMC algorithm.

  * method='ward' uses the Ward variance minimization algorithm.
    The new entry :math:`d(u,v)` is computed as follows,

    .. math::

       d(u,v) = \\sqrt{\\frac{|v|+|s|}
                           {T}d(v,s)^2
                    + \\frac{|v|+|t|}
                           {T}d(v,t)^2
                    + \\frac{|v|}
                           {T}d(s,t)^2}

    where :math:`u` is the newly joined cluster consisting of
    clusters :math:`s` and :math:`t`, :math:`v` is an unused
    cluster in the forest, :math:`T=|v|+|s|+|t|`, and
    :math:`|*|` is the cardinality of its argument. This is also
    known as the incremental algorithm.

Warning: When the minimum distance pair in the forest is chosen, there
may be two or more pairs with the same minimum distance. This
implementation may chose a different minimum than the MATLAB
version.

Parameters
----------
y : ndarray
    A condensed or redundant distance matrix. A condensed distance matrix
    is a flat array containing the upper triangular of the distance matrix.
    This is the form that ``pdist`` returns. Alternatively, a collection of
    :math:`m` observation vectors in n dimensions may be passed as an
    :math:`m` by :math:`n` array.
method : str, optional
    The linkage algorithm to use. See the ``Linkage Methods`` section below
    for full descriptions.
metric : str, optional
    The distance metric to use. See the ``distance.pdist`` function for a
    list of valid distance metrics.

Returns
-------
Z : ndarray
    The hierarchical clustering encoded as a linkage matrix.


Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>n = Z.shape[<NUM_LIT:0>] + <NUM_LIT:1><EOL>d = [None] * (n * <NUM_LIT:2> - <NUM_LIT:1>)<EOL>for i in xrange(<NUM_LIT:0>, n):<EOL><INDENT>d[i] = ClusterNode(i)<EOL><DEDENT>nd = None<EOL>for i in xrange(<NUM_LIT:0>, n - <NUM_LIT:1>):<EOL><INDENT>fi = int(Z[i, <NUM_LIT:0>])<EOL>fj = int(Z[i, <NUM_LIT:1>])<EOL>if fi > i + n:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>'<EOL>'<STR_LIT>') % fi)<EOL><DEDENT>if fj > i + n:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>'<EOL>'<STR_LIT>') % fj)<EOL><DEDENT>nd = ClusterNode(i + n, d[fi], d[fj], Z[i, <NUM_LIT:2>])<EOL>if Z[i, <NUM_LIT:3>] != nd.count:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>') % i)<EOL><DEDENT>d[n + i] = nd<EOL><DEDENT>if rd:<EOL><INDENT>return (nd, d)<EOL><DEDENT>else:<EOL><INDENT>return nd<EOL><DEDENT>

Converts a hierarchical clustering encoded in the matrix ``Z`` (by
linkage) into an easy-to-use tree object.

The reference r to the root ClusterNode object is returned.

Each ClusterNode object has a left, right, dist, id, and count
attribute. The left and right attributes point to ClusterNode objects
that were combined to generate the cluster. If both are None then
the ClusterNode object is a leaf node, its count must be 1, and its
distance is meaningless but set to 0.

Note: This function is provided for the convenience of the library
user. ClusterNodes are not used as input to any of the functions in this
library.

Parameters
----------
Z : ndarray
    The linkage matrix in proper form (see the ``linkage``
    function documentation).

rd : bool, optional
    When False, a reference to the root ClusterNode object is
    returned.  Otherwise, a tuple (r,d) is returned. ``r`` is a
    reference to the root node while ``d`` is a dictionary
    mapping cluster ids to ClusterNode references. If a cluster id is
    less than n, then it corresponds to a singleton cluster
    (leaf node). See ``linkage`` for more information on the
    assignment of cluster ids to clusters.

Returns
-------
L : list
    The pre-order traversal.


Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>Zs = Z.shape<EOL>n = Zs[<NUM_LIT:0>] + <NUM_LIT:1><EOL>zz = np.zeros((n * (n - <NUM_LIT:1>)) // <NUM_LIT:2>, dtype=np.double)<EOL>Z = _convert_to_double(Z)<EOL>_hierarchy.cophenetic_distances(Z, zz, int(n))<EOL>if Y is None:<EOL><INDENT>return zz<EOL><DEDENT>Y = np.asarray(Y, order='<STR_LIT:c>')<EOL>distance.is_valid_y(Y, throw=True, name='<STR_LIT:Y>')<EOL>z = zz.mean()<EOL>y = Y.mean()<EOL>Yy = Y - y<EOL>Zz = zz - z<EOL>numerator = (Yy * Zz)<EOL>denomA = Yy ** <NUM_LIT:2><EOL>denomB = Zz ** <NUM_LIT:2><EOL>c = numerator.sum() / np.sqrt((denomA.sum() * denomB.sum()))<EOL>return (c, zz)<EOL>

Calculates the cophenetic distances between each observation in
the hierarchical clustering defined by the linkage ``Z``.

Suppose ``p`` and ``q`` are original observations in
disjoint clusters ``s`` and ``t``, respectively and
``s`` and ``t`` are joined by a direct parent cluster
``u``. The cophenetic distance between observations
``i`` and ``j`` is simply the distance between
clusters ``s`` and ``t``.

Parameters
----------
Z : ndarray
    The hierarchical clustering encoded as an array
    (see ``linkage`` function).

Y : ndarray (optional)
    Calculates the cophenetic correlation coefficient ``c`` of a
    hierarchical clustering defined by the linkage matrix `Z`
    of a set of :math:`n` observations in :math:`m`
    dimensions. `Y` is the condensed distance matrix from which
    `Z` was generated.

Returns
-------
c : ndarray
    The cophentic correlation distance (if ``y`` is passed).
d : ndarray
    The cophenetic distance matrix in condensed form. The
    :math:`ij` th entry is the cophenetic distance between
    original observations :math:`i` and :math:`j`.


Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>Zs = Z.shape<EOL>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>if (not d == np.floor(d)) or d < <NUM_LIT:0>:<EOL><INDENT>raise ValueError('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT>[Z] = _copy_arrays_if_base_present([Z])<EOL>n = Zs[<NUM_LIT:0>] + <NUM_LIT:1><EOL>R = np.zeros((n - <NUM_LIT:1>, <NUM_LIT:4>), dtype=np.double)<EOL>_hierarchy.inconsistent(Z, R, int(n), int(d))<EOL>return R<EOL>

Calculates inconsistency statistics on a linkage.

Note: This function behaves similarly to the MATLAB(TM)
inconsistent function.

Parameters
----------
Z : ndarray
    The :math:`(n-1)` by 4 matrix encoding the linkage
    (hierarchical clustering).  See ``linkage`` documentation
    for more information on its form.
d : int, optional
    The number of links up to `d` levels below each
    non-singleton cluster.

Returns
-------
R : ndarray
    A :math:`(n-1)` by 5 matrix where the ``i``'th row
    contains the link statistics for the non-singleton cluster
    ``i``. The link statistics are computed over the link
    heights for links :math:`d` levels below the cluster
    ``i``. ``R[i,0]`` and ``R[i,1]`` are the mean and standard
    deviation of the link heights, respectively; ``R[i,2]`` is
    the number of links included in the calculation; and
    ``R[i,3]`` is the inconsistency coefficient,

    .. math:: \\frac{\\mathtt{Z[i,2]}-\\mathtt{R[i,0]}} {R[i,1]}


Z = np.asarray(Z, dtype=np.double, order='<STR_LIT:c>')<EOL>Zs = Z.shape<EOL>if len(Zs) == <NUM_LIT:0> or (len(Zs) == <NUM_LIT:1> and Zs[<NUM_LIT:0>] == <NUM_LIT:0>):<EOL><INDENT>return Z.copy()<EOL><DEDENT>if len(Zs) != <NUM_LIT:2>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if Zs[<NUM_LIT:0>] == <NUM_LIT:0>:<EOL><INDENT>return Z.copy()<EOL><DEDENT>Zpart = Z.copy()<EOL>if Zpart[:, <NUM_LIT:0>:<NUM_LIT:2>].min() != <NUM_LIT:1.0> and Zpart[:, <NUM_LIT:0>:<NUM_LIT:2>].max() != <NUM_LIT:2> * Zs[<NUM_LIT:0>]:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>Zpart[:, <NUM_LIT:0>:<NUM_LIT:2>] -= <NUM_LIT:1.0><EOL>CS = np.zeros((Zs[<NUM_LIT:0>],), dtype=np.double)<EOL>_hierarchy.calculate_cluster_sizes(Zpart, CS, int(Zs[<NUM_LIT:0>]) + <NUM_LIT:1>)<EOL>return np.hstack([Zpart, CS.reshape(Zs[<NUM_LIT:0>], <NUM_LIT:1>)])<EOL>

Converts a linkage matrix generated by MATLAB(TM) to a new
linkage matrix compatible with this module.

The conversion does two things:

 * the indices are converted from ``1..N`` to ``0..(N-1)`` form,
   and

 * a fourth column Z[:,3] is added where Z[i,3] is represents the
   number of original observations (leaves) in the non-singleton
   cluster i.

This function is useful when loading in linkages from legacy data
files generated by MATLAB.

Parameters
----------
Z : ndarray
    A linkage matrix generated by MATLAB(TM).

Returns
-------
ZS : ndarray
    A linkage matrix compatible with this library.


Z = np.asarray(Z, order='<STR_LIT:c>', dtype=np.double)<EOL>Zs = Z.shape<EOL>if len(Zs) == <NUM_LIT:0> or (len(Zs) == <NUM_LIT:1> and Zs[<NUM_LIT:0>] == <NUM_LIT:0>):<EOL><INDENT>return Z.copy()<EOL><DEDENT>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>ZP = Z[:, <NUM_LIT:0>:<NUM_LIT:3>].copy()<EOL>ZP[:, <NUM_LIT:0>:<NUM_LIT:2>] += <NUM_LIT:1.0><EOL>return ZP<EOL>

Converts a linkage matrix to a MATLAB(TM) compatible one.

Converts a linkage matrix ``Z`` generated by the linkage function
of this module to a MATLAB(TM) compatible one. The return linkage
matrix has the last column removed and the cluster indices are
converted to ``1..N`` indexing.

Parameters
----------
Z : ndarray
    A linkage matrix generated by this library.

Returns
-------
to_mlab_linkage : ndarray
    A linkage matrix compatible with MATLAB(TM)'s hierarchical
    clustering functions.

    The return linkage matrix has the last column removed
    and the cluster indices are converted to ``1..N`` indexing.


Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>return (Z[<NUM_LIT:1>:, <NUM_LIT:2>] >= Z[:-<NUM_LIT:1>, <NUM_LIT:2>]).all()<EOL>

Returns True if the linkage passed is monotonic.

The linkage is monotonic if for every cluster :math:`s` and :math:`t`
joined, the distance between them is no less than the distance
between any previously joined clusters.

Parameters
----------
Z : ndarray
    The linkage matrix to check for monotonicity.

Returns
-------
b : bool
    A boolean indicating whether the linkage is monotonic.


def is_valid_im(R, warning=False, throw=False, name=None):

R = np.asarray(R, order='<STR_LIT:c>')<EOL>valid = True<EOL>try:<EOL><INDENT>if type(R) != np.ndarray:<EOL><INDENT>if name:<EOL><INDENT>raise TypeError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise TypeError('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT><DEDENT>if R.dtype != np.double:<EOL><INDENT>if name:<EOL><INDENT>raise TypeError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise TypeError('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT><DEDENT>if len(R.shape) != <NUM_LIT:2>:<EOL><INDENT>if name:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT><DEDENT>if R.shape[<NUM_LIT:1>] != <NUM_LIT:4>:<EOL><INDENT>if name:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT><DEDENT>if R.shape[<NUM_LIT:0>] < <NUM_LIT:1>:<EOL><INDENT>if name:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT><DEDENT>if (R[:, <NUM_LIT:0>] < <NUM_LIT:0>).any():<EOL><INDENT>if name:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT><DEDENT>if (R[:, <NUM_LIT:1>] < <NUM_LIT:0>).any():<EOL><INDENT>if name:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT><DEDENT>if (R[:, <NUM_LIT:2>] < <NUM_LIT:0>).any():<EOL><INDENT>if name:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT><DEDENT><DEDENT>except Exception as e:<EOL><INDENT>if throw:<EOL><INDENT>raise<EOL><DEDENT>if warning:<EOL><INDENT>_warning(str(e))<EOL><DEDENT>valid = False<EOL><DEDENT>return valid<EOL>

Returns True if the inconsistency matrix passed is valid.

    It must be a :math:`n` by 4 numpy array of doubles. The standard
    deviations ``R[:,1]`` must be nonnegative. The link counts
    ``R[:,2]`` must be positive and no greater than :math:`n-1`.

    Parameters
    ----------
    R : ndarray
        The inconsistency matrix to check for validity.
    warning : bool, optional
         When True, issues a Python warning if the linkage
         matrix passed is invalid.
    throw : bool, optional
         When True, throws a Python exception if the linkage
         matrix passed is invalid.
    name : str, optional
         This string refers to the variable name of the invalid
         linkage matrix.

    Returns
    -------
    b : bool
        True if the inconsistency matrix is valid.


def is_valid_linkage(Z, warning=False, throw=False, name=None):

Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>valid = True<EOL>try:<EOL><INDENT>if type(Z) != np.ndarray:<EOL><INDENT>if name:<EOL><INDENT>raise TypeError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise TypeError('<STR_LIT>')<EOL><DEDENT><DEDENT>if Z.dtype != np.double:<EOL><INDENT>if name:<EOL><INDENT>raise TypeError('<STR_LIT>'<EOL>% name)<EOL><DEDENT>else:<EOL><INDENT>raise TypeError('<STR_LIT>')<EOL><DEDENT><DEDENT>if len(Z.shape) != <NUM_LIT:2>:<EOL><INDENT>if name:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT><DEDENT>if Z.shape[<NUM_LIT:1>] != <NUM_LIT:4>:<EOL><INDENT>if name:<EOL><INDENT>raise ValueError('<STR_LIT>'<EOL>% name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT><DEDENT>if Z.shape[<NUM_LIT:0>] == <NUM_LIT:0>:<EOL><INDENT>raise ValueError('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT>n = Z.shape[<NUM_LIT:0>]<EOL>if n > <NUM_LIT:1>:<EOL><INDENT>if ((Z[:, <NUM_LIT:0>] < <NUM_LIT:0>).any() or (Z[:, <NUM_LIT:1>] < <NUM_LIT:0>).any()):<EOL><INDENT>if name:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT><DEDENT>if (Z[:, <NUM_LIT:2>] < <NUM_LIT:0>).any():<EOL><INDENT>if name:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT><DEDENT>if (Z[:, <NUM_LIT:3>] < <NUM_LIT:0>).any():<EOL><INDENT>if name:<EOL><INDENT>raise ValueError('<STR_LIT>'<EOL>% name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT><DEDENT><DEDENT>if _check_hierarchy_uses_cluster_before_formed(Z):<EOL><INDENT>if name:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT><DEDENT>if _check_hierarchy_uses_cluster_more_than_once(Z):<EOL><INDENT>if name:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>') % name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT><DEDENT><DEDENT>except Exception as e:<EOL><INDENT>if throw:<EOL><INDENT>raise<EOL><DEDENT>if warning:<EOL><INDENT>_warning(str(e))<EOL><DEDENT>valid = False<EOL><DEDENT>return valid<EOL>

Checks the validity of a linkage matrix.

A linkage matrix is valid if it is a two dimensional
ndarray (type double) with :math:`n`
rows and 4 columns.  The first two columns must contain indices
between 0 and :math:`2n-1`. For a given row ``i``,
:math:`0 \\leq \\mathtt{Z[i,0]} \\leq i+n-1`
and :math:`0 \\leq Z[i,1] \\leq i+n-1`
(i.e. a cluster cannot join another cluster unless the cluster
being joined has been generated.)

Parameters
----------
Z : array_like
    Linkage matrix.
warning : bool, optional
    When True, issues a Python warning if the linkage
    matrix passed is invalid.
throw : bool, optional
    When True, throws a Python exception if the linkage
    matrix passed is invalid.
name : str, optional
       This string refers to the variable name of the invalid
       linkage matrix.

Returns
-------
b : bool
    True iff the inconsistency matrix is valid.


Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>return (Z.shape[<NUM_LIT:0>] + <NUM_LIT:1>)<EOL>

Returns the number of original observations of the linkage matrix
passed.

Parameters
----------
Z : ndarray
    The linkage matrix on which to perform the operation.

Returns
-------
n : int
    The number of original observations in the linkage.


is_valid_linkage(Z, throw=True)<EOL>distance.is_valid_y(Y, throw=True)<EOL>Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>Y = np.asarray(Y, order='<STR_LIT:c>')<EOL>return distance.num_obs_y(Y) == num_obs_linkage(Z)<EOL>

Checks for correspondence between linkage and condensed distance matrices

They must have the same number of original observations for
the check to succeed.

This function is useful as a sanity check in algorithms that make
extensive use of linkage and distance matrices that must
correspond to the same set of original observations.

Parameters
----------
Z : array_like
    The linkage matrix to check for correspondence.
Y : array_like
    The condensed distance matrix to check for correspondence.

Returns
-------
b : bool
    A boolean indicating whether the linkage matrix and distance
    matrix could possibly correspond to one another.


def fcluster(Z, t, criterion='<STR_LIT>', depth=<NUM_LIT:2>, R=None, monocrit=None):

Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>n = Z.shape[<NUM_LIT:0>] + <NUM_LIT:1><EOL>T = np.zeros((n,), dtype='<STR_LIT:i>')<EOL>[Z] = _copy_arrays_if_base_present([Z])<EOL>if criterion == '<STR_LIT>':<EOL><INDENT>if R is None:<EOL><INDENT>R = inconsistent(Z, depth)<EOL><DEDENT>else:<EOL><INDENT>R = np.asarray(R, order='<STR_LIT:c>')<EOL>is_valid_im(R, throw=True, name='<STR_LIT:R>')<EOL>[R] = _copy_arrays_if_base_present([R])<EOL><DEDENT>_hierarchy.cluster_in(Z, R, T, float(t), int(n))<EOL><DEDENT>elif criterion == '<STR_LIT>':<EOL><INDENT>_hierarchy.cluster_dist(Z, T, float(t), int(n))<EOL><DEDENT>elif criterion == '<STR_LIT>':<EOL><INDENT>_hierarchy.cluster_maxclust_dist(Z, T, int(n), int(t))<EOL><DEDENT>elif criterion == '<STR_LIT>':<EOL><INDENT>[monocrit] = _copy_arrays_if_base_present([monocrit])<EOL>_hierarchy.cluster_monocrit(Z, monocrit, T, float(t), int(n))<EOL><DEDENT>elif criterion == '<STR_LIT>':<EOL><INDENT>[monocrit] = _copy_arrays_if_base_present([monocrit])<EOL>_hierarchy.cluster_maxclust_monocrit(Z, monocrit, T, int(n), int(t))<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>'<EOL>% str(criterion))<EOL><DEDENT>return T<EOL>

Forms flat clusters from the hierarchical clustering defined by
the linkage matrix ``Z``.

Parameters
----------
Z : ndarray
    The hierarchical clustering encoded with the matrix returned
    by the `linkage` function.
t : float
    The threshold to apply when forming flat clusters.
criterion : str, optional
    The criterion to use in forming flat clusters. This can
    be any of the following values:

      ``inconsistent`` : If a cluster node and all its
          descendants have an inconsistent value less than or equal
          to `t` then all its leaf descendants belong to the
          same flat cluster. When no non-singleton cluster meets
          this criterion, every node is assigned to its own
          cluster. (Default)

      ``distance`` : Forms flat clusters so that the original
          observations in each flat cluster have no greater a
          cophenetic distance than `t`.

      ``maxclust`` : Finds a minimum threshold ``r`` so that
          the cophenetic distance between any two original
          observations in the same flat cluster is no more than
          ``r`` and no more than `t` flat clusters are formed.

      ``monocrit`` : Forms a flat cluster from a cluster node c
          with index i when ``monocrit[j] <= t``.

          For example, to threshold on the maximum mean distance
          as computed in the inconsistency matrix R with a
          threshold of 0.8 do:

            MR = maxRstat(Z, R, 3)

            cluster(Z, t=0.8, criterion='monocrit', monocrit=MR)

      ``maxclust_monocrit`` : Forms a flat cluster from a
          non-singleton cluster node ``c`` when ``monocrit[i] <=
          r`` for all cluster indices ``i`` below and including
          ``c``. ``r`` is minimized such that no more than ``t``
          flat clusters are formed. monocrit must be
          monotonic. For example, to minimize the threshold t on
          maximum inconsistency values so that no more than 3 flat
          clusters are formed, do:

            MI = maxinconsts(Z, R)

            cluster(Z, t=3, criterion='maxclust_monocrit', monocrit=MI)

depth : int, optional
    The maximum depth to perform the inconsistency calculation.
    It has no meaning for the other criteria. Default is 2.
R : ndarray, optional
    The inconsistency matrix to use for the 'inconsistent'
    criterion. This matrix is computed if not provided.
monocrit : ndarray, optional
    An array of length n-1. `monocrit[i]` is the
    statistics upon which non-singleton i is thresholded. The
    monocrit vector must be monotonic, i.e. given a node c with
    index i, for all node indices j corresponding to nodes
    below c, `monocrit[i] >= monocrit[j]`.

Returns
-------
fcluster : ndarray
    An array of length n. T[i] is the flat cluster number to
    which original observation i belongs.


def fclusterdata(X, t, criterion='<STR_LIT>',<EOL>metric='<STR_LIT>', depth=<NUM_LIT:2>, method='<STR_LIT>', R=None):

X = np.asarray(X, order='<STR_LIT:c>', dtype=np.double)<EOL>if type(X) != np.ndarray or len(X.shape) != <NUM_LIT:2>:<EOL><INDENT>raise TypeError('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT>Y = distance.pdist(X, metric=metric)<EOL>Z = linkage(Y, method=method)<EOL>if R is None:<EOL><INDENT>R = inconsistent(Z, d=depth)<EOL><DEDENT>else:<EOL><INDENT>R = np.asarray(R, order='<STR_LIT:c>')<EOL><DEDENT>T = fcluster(Z, criterion=criterion, depth=depth, R=R, t=t)<EOL>return T<EOL>

Cluster observation data using a given metric.

Clusters the original observations in the n-by-m data
matrix X (n observations in m dimensions), using the euclidean
distance metric to calculate distances between original observations,
performs hierarchical clustering using the single linkage algorithm,
and forms flat clusters using the inconsistency method with `t` as the
cut-off threshold.

A one-dimensional array T of length n is returned. T[i] is the index
of the flat cluster to which the original observation i belongs.

Parameters
----------
X : (N, M) ndarray
    N by M data matrix with N observations in M dimensions.
t : float
    The threshold to apply when forming flat clusters.
criterion : str, optional
    Specifies the criterion for forming flat clusters.  Valid
    values are 'inconsistent' (default), 'distance', or 'maxclust'
    cluster formation algorithms. See `fcluster` for descriptions.
metric : str, optional
    The distance metric for calculating pairwise distances. See
    `distance.pdist` for descriptions and linkage to verify
    compatibility with the linkage method.
depth : int, optional
    The maximum depth for the inconsistency calculation. See
    `inconsistent` for more information.
method : str, optional
    The linkage method to use (single, complete, average,
    weighted, median centroid, ward). See `linkage` for more
    information. Default is "single".
R : ndarray, optional
    The inconsistency matrix. It will be computed if necessary
    if it is not passed.

Returns
-------
fclusterdata : ndarray
    A vector of length n. T[i] is the flat cluster number to
    which original observation i belongs.

Notes
-----
This function is similar to the MATLAB function clusterdata.


Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>n = Z.shape[<NUM_LIT:0>] + <NUM_LIT:1><EOL>ML = np.zeros((n,), dtype='<STR_LIT:i>')<EOL>[Z] = _copy_arrays_if_base_present([Z])<EOL>_hierarchy.prelist(Z, ML, int(n))<EOL>return ML<EOL>

Returns a list of leaf node ids

The return corresponds to the observation vector index as it appears
in the tree from left to right. Z is a linkage matrix.

Parameters
----------
Z : ndarray
    The hierarchical clustering encoded as a matrix.  `Z` is
    a linkage matrix.  See ``linkage`` for more information.

Returns
-------
leaves_list : ndarray
    The list of leaf node ids.


seen_before = set([])<EOL>L2 = []<EOL>for i in L:<EOL><INDENT>if i not in seen_before:<EOL><INDENT>seen_before.add(i)<EOL>L2.append(i)<EOL><DEDENT><DEDENT>return L2<EOL>

Removes duplicates AND preserves the original order of the elements.
The set class is not guaranteed to do this.


if type(palette) not in (list, tuple):<EOL><INDENT>raise TypeError("<STR_LIT>")<EOL><DEDENT>_ptypes = [isinstance(p, string_types) for p in palette]<EOL>if False in _ptypes:<EOL><INDENT>raise TypeError("<STR_LIT>")<EOL><DEDENT>for i in list(_link_line_colors):<EOL><INDENT>_link_line_colors.remove(i)<EOL><DEDENT>_link_line_colors.extend(list(palette))<EOL>

Set list of matplotlib color codes for dendrogram color_threshold.

Parameters
----------
palette : list
    A list of matplotlib color codes. The order of
    the color codes is the order in which the colors are cycled
    through when color thresholding in the dendrogram.


def dendrogram(Z, p=<NUM_LIT:30>, truncate_mode=None, color_threshold=None,<EOL>get_leaves=True, orientation='<STR_LIT>', labels=None,<EOL>count_sort=False, distance_sort=False, show_leaf_counts=True,<EOL>no_plot=False, no_labels=False, color_list=None,<EOL>leaf_font_size=None, leaf_rotation=None, leaf_label_func=None,<EOL>no_leaves=False, show_contracted=False,<EOL>link_color_func=None, ax=None):

<EOL>Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>if orientation not in ["<STR_LIT>", "<STR_LIT:left>", "<STR_LIT>", "<STR_LIT:right>"]:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>Zs = Z.shape<EOL>n = Zs[<NUM_LIT:0>] + <NUM_LIT:1><EOL>if type(p) in (int, float):<EOL><INDENT>p = int(p)<EOL><DEDENT>else:<EOL><INDENT>raise TypeError('<STR_LIT>')<EOL><DEDENT>if truncate_mode not in ('<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT:none>', None):<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>if truncate_mode == '<STR_LIT>' or truncate_mode == '<STR_LIT>':<EOL><INDENT>if p > n or p == <NUM_LIT:0>:<EOL><INDENT>p = n<EOL><DEDENT><DEDENT>if truncate_mode == '<STR_LIT>' or truncate_mode == '<STR_LIT>':<EOL><INDENT>if p <= <NUM_LIT:0>:<EOL><INDENT>p = np.inf<EOL><DEDENT><DEDENT>if get_leaves:<EOL><INDENT>lvs = []<EOL><DEDENT>else:<EOL><INDENT>lvs = None<EOL><DEDENT>icoord_list = []<EOL>dcoord_list = []<EOL>color_list = []<EOL>current_color = [<NUM_LIT:0>]<EOL>currently_below_threshold = [False]<EOL>if no_leaves:<EOL><INDENT>ivl = None<EOL><DEDENT>else:<EOL><INDENT>ivl = []<EOL><DEDENT>if color_threshold is None or(isinstance(color_threshold, string_types) and<EOL>color_threshold == '<STR_LIT:default>'):<EOL><INDENT>color_threshold = max(Z[:, <NUM_LIT:2>]) * <NUM_LIT><EOL><DEDENT>R = {'<STR_LIT>': icoord_list, '<STR_LIT>': dcoord_list, '<STR_LIT>': ivl,<EOL>'<STR_LIT>': lvs, '<STR_LIT>': color_list}<EOL>if show_contracted:<EOL><INDENT>contraction_marks = []<EOL><DEDENT>else:<EOL><INDENT>contraction_marks = None<EOL><DEDENT>_dendrogram_calculate_info(<EOL>Z=Z, p=p,<EOL>truncate_mode=truncate_mode,<EOL>color_threshold=color_threshold,<EOL>get_leaves=get_leaves,<EOL>orientation=orientation,<EOL>labels=labels,<EOL>count_sort=count_sort,<EOL>distance_sort=distance_sort,<EOL>show_leaf_counts=show_leaf_counts,<EOL>i=<NUM_LIT:2> * n - <NUM_LIT:2>, iv=<NUM_LIT:0.0>, ivl=ivl, n=n,<EOL>icoord_list=icoord_list,<EOL>dcoord_list=dcoord_list, lvs=lvs,<EOL>current_color=current_color,<EOL>color_list=color_list,<EOL>currently_below_threshold=currently_below_threshold,<EOL>leaf_label_func=leaf_label_func,<EOL>contraction_marks=contraction_marks,<EOL>link_color_func=link_color_func)<EOL>if not no_plot:<EOL><INDENT>mh = max(Z[:, <NUM_LIT:2>])<EOL>_plot_dendrogram(icoord_list, dcoord_list, ivl, p, n, mh, orientation,<EOL>no_labels, color_list, leaf_font_size=leaf_font_size,<EOL>leaf_rotation=leaf_rotation,<EOL>contraction_marks=contraction_marks,<EOL>ax=ax)<EOL><DEDENT>return R<EOL>

Plots the hierarchical clustering as a dendrogram.

The dendrogram illustrates how each cluster is
composed by drawing a U-shaped link between a non-singleton
cluster and its children. The height of the top of the U-link is
the distance between its children clusters. It is also the
cophenetic distance between original observations in the two
children clusters. It is expected that the distances in Z[:,2] be
monotonic, otherwise crossings appear in the dendrogram.

Parameters
----------
Z : ndarray
    The linkage matrix encoding the hierarchical clustering to
    render as a dendrogram. See the ``linkage`` function for more
    information on the format of ``Z``.
p : int, optional
    The ``p`` parameter for ``truncate_mode``.
truncate_mode : str, optional
    The dendrogram can be hard to read when the original
    observation matrix from which the linkage is derived is
    large. Truncation is used to condense the dendrogram. There
    are several modes:

    ``None/'none'``
      No truncation is performed (Default).

    ``'lastp'``
      The last ``p`` non-singleton formed in the linkage are the only
      non-leaf nodes in the linkage; they correspond to rows
      ``Z[n-p-2:end]`` in ``Z``. All other non-singleton clusters are
      contracted into leaf nodes.

    ``'mlab'``
      This corresponds to MATLAB(TM) behavior. (not implemented yet)

    ``'level'/'mtica'``
      No more than ``p`` levels of the dendrogram tree are displayed.
      This corresponds to Mathematica(TM) behavior.

color_threshold : double, optional
    For brevity, let :math:`t` be the ``color_threshold``.
    Colors all the descendent links below a cluster node
    :math:`k` the same color if :math:`k` is the first node below
    the cut threshold :math:`t`. All links connecting nodes with
    distances greater than or equal to the threshold are colored
    blue. If :math:`t` is less than or equal to zero, all nodes
    are colored blue. If ``color_threshold`` is None or
    'default', corresponding with MATLAB(TM) behavior, the
    threshold is set to ``0.7*max(Z[:,2])``.
get_leaves : bool, optional
    Includes a list ``R['leaves']=H`` in the result
    dictionary. For each :math:`i`, ``H[i] == j``, cluster node
    ``j`` appears in position ``i`` in the left-to-right traversal
    of the leaves, where :math:`j < 2n-1` and :math:`i < n`.
orientation : str, optional
    The direction to plot the dendrogram, which can be any
    of the following strings:

    ``'top'``
      Plots the root at the top, and plot descendent links going downwards.
      (default).

    ``'bottom'``
      Plots the root at the bottom, and plot descendent links going
      upwards.

    ``'left'``
      Plots the root at the left, and plot descendent links going right.

    ``'right'``
      Plots the root at the right, and plot descendent links going left.

labels : ndarray, optional
    By default ``labels`` is None so the index of the original observation
    is used to label the leaf nodes.  Otherwise, this is an :math:`n`
    -sized list (or tuple). The ``labels[i]`` value is the text to put
    under the :math:`i` th leaf node only if it corresponds to an original
    observation and not a non-singleton cluster.
count_sort : str or bool, optional
    For each node n, the order (visually, from left-to-right) n's
    two descendent links are plotted is determined by this
    parameter, which can be any of the following values:

    ``False``
      Nothing is done.

    ``'ascending'`` or ``True``
      The child with the minimum number of original objects in its cluster
      is plotted first.

    ``'descendent'``
      The child with the maximum number of original objects in its cluster
      is plotted first.

    Note ``distance_sort`` and ``count_sort`` cannot both be True.
distance_sort : str or bool, optional
    For each node n, the order (visually, from left-to-right) n's
    two descendent links are plotted is determined by this
    parameter, which can be any of the following values:

    ``False``
      Nothing is done.

    ``'ascending'`` or ``True``
      The child with the minimum distance between its direct descendents is
      plotted first.

    ``'descending'``
      The child with the maximum distance between its direct descendents is
      plotted first.

    Note ``distance_sort`` and ``count_sort`` cannot both be True.
show_leaf_counts : bool, optional
     When True, leaf nodes representing :math:`k>1` original
     observation are labeled with the number of observations they
     contain in parentheses.
no_plot : bool, optional
    When True, the final rendering is not performed. This is
    useful if only the data structures computed for the rendering
    are needed or if matplotlib is not available.
no_labels : bool, optional
    When True, no labels appear next to the leaf nodes in the
    rendering of the dendrogram.
leaf_rotation : double, optional
    Specifies the angle (in degrees) to rotate the leaf
    labels. When unspecified, the rotation is based on the number of
    nodes in the dendrogram (default is 0).
leaf_font_size : int, optional
    Specifies the font size (in points) of the leaf labels. When
    unspecified, the size based on the number of nodes in the
    dendrogram.
leaf_label_func : lambda or function, optional
    When leaf_label_func is a callable function, for each
    leaf with cluster index :math:`k < 2n-1`. The function
    is expected to return a string with the label for the
    leaf.

    Indices :math:`k < n` correspond to original observations
    while indices :math:`k \\geq n` correspond to non-singleton
    clusters.

    For example, to label singletons with their node id and
    non-singletons with their id, count, and inconsistency
    coefficient, simply do:

    >>> # First define the leaf label function.
    >>> def llf(id):
    ...       if id < n:
    ...           return str(id)
    ...       else:
    >>>           return '[%d %d %1.2f]' % (id, count, R[n-id,3])
    >>>
    >>>  # The text for the leaf nodes is going to be big so force
    >>>  # a rotation of 90 degrees.
    >>>  dendrogram(Z, leaf_label_func=llf, leaf_rotation=90)

show_contracted : bool, optional
    When True the heights of non-singleton nodes contracted
    into a leaf node are plotted as crosses along the link
    connecting that leaf node.  This really is only useful when
    truncation is used (see ``truncate_mode`` parameter).
link_color_func : callable, optional
    If given, `link_color_function` is called with each non-singleton id
    corresponding to each U-shaped link it will paint. The function is
    expected to return the color to paint the link, encoded as a matplotlib
    color string code. For example:

    >>> dendrogram(Z, link_color_func=lambda k: colors[k])

    colors the direct links below each untruncated non-singleton node
    ``k`` using ``colors[k]``.
ax : matplotlib Axes instance, optional
    If None and `no_plot` is not True, the dendrogram will be plotted
    on the current axes.  Otherwise if `no_plot` is not True the
    dendrogram will be plotted on the given ``Axes`` instance. This can be
    useful if the dendrogram is part of a more complex figure.

Returns
-------
R : dict
    A dictionary of data structures computed to render the
    dendrogram. Its has the following keys:

    ``'color_list'``
      A list of color names. The k'th element represents the color of the
      k'th link.

    ``'icoord'`` and ``'dcoord'``
      Each of them is a list of lists. Let ``icoord = [I1, I2, ..., Ip]``
      where ``Ik = [xk1, xk2, xk3, xk4]`` and ``dcoord = [D1, D2, ..., Dp]``
      where ``Dk = [yk1, yk2, yk3, yk4]``, then the k'th link painted is
      ``(xk1, yk1)`` - ``(xk2, yk2)`` - ``(xk3, yk3)`` - ``(xk4, yk4)``.

    ``'ivl'``
      A list of labels corresponding to the leaf nodes.

    ``'leaves'``
      For each i, ``H[i] == j``, cluster node ``j`` appears in position
      ``i`` in the left-to-right traversal of the leaves, where
      :math:`j < 2n-1` and :math:`i < n`. If ``j`` is less than ``n``, the
      ``i``-th leaf node corresponds to an original observation.
      Otherwise, it corresponds to a non-singleton cluster.


def _dendrogram_calculate_info(Z, p, truncate_mode,<EOL>color_threshold=np.inf, get_leaves=True,<EOL>orientation='<STR_LIT>', labels=None,<EOL>count_sort=False, distance_sort=False,<EOL>show_leaf_counts=False, i=-<NUM_LIT:1>, iv=<NUM_LIT:0.0>,<EOL>ivl=[], n=<NUM_LIT:0>, icoord_list=[], dcoord_list=[],<EOL>lvs=None, mhr=False,<EOL>current_color=[], color_list=[],<EOL>currently_below_threshold=[],<EOL>leaf_label_func=None, level=<NUM_LIT:0>,<EOL>contraction_marks=None,<EOL>link_color_func=None):

if n == <NUM_LIT:0>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if i == -<NUM_LIT:1>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if truncate_mode == '<STR_LIT>':<EOL><INDENT>if i < <NUM_LIT:2> * n - p and i >= n:<EOL><INDENT>d = Z[i - n, <NUM_LIT:2>]<EOL>_append_nonsingleton_leaf_node(Z, p, n, level, lvs, ivl,<EOL>leaf_label_func, i, labels,<EOL>show_leaf_counts)<EOL>if contraction_marks is not None:<EOL><INDENT>_append_contraction_marks(Z, iv + <NUM_LIT>, i, n, contraction_marks)<EOL><DEDENT>return (iv + <NUM_LIT>, <NUM_LIT>, <NUM_LIT:0.0>, d)<EOL><DEDENT>elif i < n:<EOL><INDENT>_append_singleton_leaf_node(Z, p, n, level, lvs, ivl,<EOL>leaf_label_func, i, labels)<EOL>return (iv + <NUM_LIT>, <NUM_LIT>, <NUM_LIT:0.0>, <NUM_LIT:0.0>)<EOL><DEDENT><DEDENT>elif truncate_mode in ('<STR_LIT>', '<STR_LIT>'):<EOL><INDENT>if i > n and level > p:<EOL><INDENT>d = Z[i - n, <NUM_LIT:2>]<EOL>_append_nonsingleton_leaf_node(Z, p, n, level, lvs, ivl,<EOL>leaf_label_func, i, labels,<EOL>show_leaf_counts)<EOL>if contraction_marks is not None:<EOL><INDENT>_append_contraction_marks(Z, iv + <NUM_LIT>, i, n, contraction_marks)<EOL><DEDENT>return (iv + <NUM_LIT>, <NUM_LIT>, <NUM_LIT:0.0>, d)<EOL><DEDENT>elif i < n:<EOL><INDENT>_append_singleton_leaf_node(Z, p, n, level, lvs, ivl,<EOL>leaf_label_func, i, labels)<EOL>return (iv + <NUM_LIT>, <NUM_LIT>, <NUM_LIT:0.0>, <NUM_LIT:0.0>)<EOL><DEDENT><DEDENT>elif truncate_mode in ('<STR_LIT>',):<EOL><INDENT>pass<EOL><DEDENT>if i < n:<EOL><INDENT>_append_singleton_leaf_node(Z, p, n, level, lvs, ivl,<EOL>leaf_label_func, i, labels)<EOL>return (iv + <NUM_LIT>, <NUM_LIT>, <NUM_LIT:0.0>, <NUM_LIT:0.0>)<EOL><DEDENT>aa = int(Z[i - n, <NUM_LIT:0>])<EOL>ab = int(Z[i - n, <NUM_LIT:1>])<EOL>if aa > n:<EOL><INDENT>na = Z[aa - n, <NUM_LIT:3>]<EOL>da = Z[aa - n, <NUM_LIT:2>]<EOL><DEDENT>else:<EOL><INDENT>na = <NUM_LIT:1><EOL>da = <NUM_LIT:0.0><EOL><DEDENT>if ab > n:<EOL><INDENT>nb = Z[ab - n, <NUM_LIT:3>]<EOL>db = Z[ab - n, <NUM_LIT:2>]<EOL><DEDENT>else:<EOL><INDENT>nb = <NUM_LIT:1><EOL>db = <NUM_LIT:0.0><EOL><DEDENT>if count_sort == '<STR_LIT>' or count_sort == True:<EOL><INDENT>if na > nb:<EOL><INDENT>ua = ab<EOL>ub = aa<EOL><DEDENT>else:<EOL><INDENT>ua = aa<EOL>ub = ab<EOL><DEDENT><DEDENT>elif count_sort == '<STR_LIT>':<EOL><INDENT>if na > nb:<EOL><INDENT>ua = aa<EOL>ub = ab<EOL><DEDENT>else:<EOL><INDENT>ua = ab<EOL>ub = aa<EOL><DEDENT><DEDENT>elif distance_sort == '<STR_LIT>' or distance_sort == True:<EOL><INDENT>if da > db:<EOL><INDENT>ua = ab<EOL>ub = aa<EOL><DEDENT>else:<EOL><INDENT>ua = aa<EOL>ub = ab<EOL><DEDENT><DEDENT>elif distance_sort == '<STR_LIT>':<EOL><INDENT>if da > db:<EOL><INDENT>ua = aa<EOL>ub = ab<EOL><DEDENT>else:<EOL><INDENT>ua = ab<EOL>ub = aa<EOL><DEDENT><DEDENT>else:<EOL><INDENT>ua = aa<EOL>ub = ab<EOL><DEDENT>(uiva, uwa, uah, uamd) =_dendrogram_calculate_info(<EOL>Z=Z, p=p,<EOL>truncate_mode=truncate_mode,<EOL>color_threshold=color_threshold,<EOL>get_leaves=get_leaves,<EOL>orientation=orientation,<EOL>labels=labels,<EOL>count_sort=count_sort,<EOL>distance_sort=distance_sort,<EOL>show_leaf_counts=show_leaf_counts,<EOL>i=ua, iv=iv, ivl=ivl, n=n,<EOL>icoord_list=icoord_list,<EOL>dcoord_list=dcoord_list, lvs=lvs,<EOL>current_color=current_color,<EOL>color_list=color_list,<EOL>currently_below_threshold=currently_below_threshold,<EOL>leaf_label_func=leaf_label_func,<EOL>level=level + <NUM_LIT:1>, contraction_marks=contraction_marks,<EOL>link_color_func=link_color_func)<EOL>h = Z[i - n, <NUM_LIT:2>]<EOL>if h >= color_threshold or color_threshold <= <NUM_LIT:0>:<EOL><INDENT>c = '<STR_LIT:b>'<EOL>if currently_below_threshold[<NUM_LIT:0>]:<EOL><INDENT>current_color[<NUM_LIT:0>] = (current_color[<NUM_LIT:0>] + <NUM_LIT:1>) % len(_link_line_colors)<EOL><DEDENT>currently_below_threshold[<NUM_LIT:0>] = False<EOL><DEDENT>else:<EOL><INDENT>currently_below_threshold[<NUM_LIT:0>] = True<EOL>c = _link_line_colors[current_color[<NUM_LIT:0>]]<EOL><DEDENT>(uivb, uwb, ubh, ubmd) =_dendrogram_calculate_info(<EOL>Z=Z, p=p,<EOL>truncate_mode=truncate_mode,<EOL>color_threshold=color_threshold,<EOL>get_leaves=get_leaves,<EOL>orientation=orientation,<EOL>labels=labels,<EOL>count_sort=count_sort,<EOL>distance_sort=distance_sort,<EOL>show_leaf_counts=show_leaf_counts,<EOL>i=ub, iv=iv + uwa, ivl=ivl, n=n,<EOL>icoord_list=icoord_list,<EOL>dcoord_list=dcoord_list, lvs=lvs,<EOL>current_color=current_color,<EOL>color_list=color_list,<EOL>currently_below_threshold=currently_below_threshold,<EOL>leaf_label_func=leaf_label_func,<EOL>level=level + <NUM_LIT:1>, contraction_marks=contraction_marks,<EOL>link_color_func=link_color_func)<EOL>max_dist = max(uamd, ubmd, h)<EOL>icoord_list.append([uiva, uiva, uivb, uivb])<EOL>dcoord_list.append([uah, h, h, ubh])<EOL>if link_color_func is not None:<EOL><INDENT>v = link_color_func(int(i))<EOL>if not isinstance(v, string_types):<EOL><INDENT>raise TypeError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT>color_list.append(v)<EOL><DEDENT>else:<EOL><INDENT>color_list.append(c)<EOL><DEDENT>return (((uiva + uivb) / <NUM_LIT:2>), uwa + uwb, h, max_dist)<EOL>

Calculates the endpoints of the links as well as the labels for the
the dendrogram rooted at the node with index i. iv is the independent
variable value to plot the left-most leaf node below the root node i
(if orientation='top', this would be the left-most x value where the
plotting of this root node i and its descendents should begin).

ivl is a list to store the labels of the leaf nodes. The leaf_label_func
is called whenever ivl != None, labels == None, and
leaf_label_func != None. When ivl != None and labels != None, the
labels list is used only for labeling the leaf nodes. When
ivl == None, no labels are generated for leaf nodes.

When get_leaves==True, a list of leaves is built as they are visited
in the dendrogram.

Returns a tuple with l being the independent variable coordinate that
corresponds to the midpoint of cluster to the left of cluster i if
i is non-singleton, otherwise the independent coordinate of the leaf
node if i is a leaf node.

Returns
-------
A tuple (left, w, h, md), where:

  * left is the independent variable coordinate of the center of the
    the U of the subtree

  * w is the amount of space used for the subtree (in independent
    variable units)

  * h is the height of the subtree in dependent variable units

  * md is the max(Z[*,2]) for all nodes * below and including
    the target node.


T1 = np.asarray(T1, order='<STR_LIT:c>')<EOL>T2 = np.asarray(T2, order='<STR_LIT:c>')<EOL>if type(T1) != np.ndarray:<EOL><INDENT>raise TypeError('<STR_LIT>')<EOL><DEDENT>if type(T2) != np.ndarray:<EOL><INDENT>raise TypeError('<STR_LIT>')<EOL><DEDENT>T1S = T1.shape<EOL>T2S = T2.shape<EOL>if len(T1S) != <NUM_LIT:1>:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>if len(T2S) != <NUM_LIT:1>:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>if T1S[<NUM_LIT:0>] != T2S[<NUM_LIT:0>]:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>n = T1S[<NUM_LIT:0>]<EOL>d = {}<EOL>for i in xrange(<NUM_LIT:0>, n):<EOL><INDENT>if T1[i] in d:<EOL><INDENT>if d[T1[i]] != T2[i]:<EOL><INDENT>return False<EOL><DEDENT><DEDENT>else:<EOL><INDENT>d[T1[i]] = T2[i]<EOL><DEDENT><DEDENT>return True<EOL>

Determines if two different cluster assignments are equivalent.

Parameters
----------
T1 : array_like
    An assignment of singleton cluster ids to flat cluster ids.
T2 : array_like
    An assignment of singleton cluster ids to flat cluster ids.

Returns
-------
b : bool
    Whether the flat cluster assignments `T1` and `T2` are
    equivalent.


Z = np.asarray(Z, order='<STR_LIT:c>', dtype=np.double)<EOL>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>n = Z.shape[<NUM_LIT:0>] + <NUM_LIT:1><EOL>MD = np.zeros((n - <NUM_LIT:1>,))<EOL>[Z] = _copy_arrays_if_base_present([Z])<EOL>_hierarchy.get_max_dist_for_each_cluster(Z, MD, int(n))<EOL>return MD<EOL>

Returns the maximum distance between any non-singleton cluster.

Parameters
----------
Z : ndarray
    The hierarchical clustering encoded as a matrix. See
    ``linkage`` for more information.

Returns
-------
maxdists : ndarray
    A ``(n-1)`` sized numpy array of doubles; ``MD[i]`` represents
    the maximum distance between any cluster (including
    singletons) below and including the node with index i. More
    specifically, ``MD[i] = Z[Q(i)-n, 2].max()`` where ``Q(i)`` is the
    set of all node indices below and including node i.


Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>R = np.asarray(R, order='<STR_LIT:c>')<EOL>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>is_valid_im(R, throw=True, name='<STR_LIT:R>')<EOL>n = Z.shape[<NUM_LIT:0>] + <NUM_LIT:1><EOL>if Z.shape[<NUM_LIT:0>] != R.shape[<NUM_LIT:0>]:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT>MI = np.zeros((n - <NUM_LIT:1>,))<EOL>[Z, R] = _copy_arrays_if_base_present([Z, R])<EOL>_hierarchy.get_max_Rfield_for_each_cluster(Z, R, MI, int(n), <NUM_LIT:3>)<EOL>return MI<EOL>

Returns the maximum inconsistency coefficient for each
non-singleton cluster and its descendents.

Parameters
----------
Z : ndarray
    The hierarchical clustering encoded as a matrix. See
    ``linkage`` for more information.
R : ndarray
    The inconsistency matrix.

Returns
-------
MI : ndarray
    A monotonic ``(n-1)``-sized numpy array of doubles.


Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>R = np.asarray(R, order='<STR_LIT:c>')<EOL>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>is_valid_im(R, throw=True, name='<STR_LIT:R>')<EOL>if type(i) is not int:<EOL><INDENT>raise TypeError('<STR_LIT>')<EOL><DEDENT>if i < <NUM_LIT:0> or i > <NUM_LIT:3>:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>if Z.shape[<NUM_LIT:0>] != R.shape[<NUM_LIT:0>]:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT>n = Z.shape[<NUM_LIT:0>] + <NUM_LIT:1><EOL>MR = np.zeros((n - <NUM_LIT:1>,))<EOL>[Z, R] = _copy_arrays_if_base_present([Z, R])<EOL>_hierarchy.get_max_Rfield_for_each_cluster(Z, R, MR, int(n), i)<EOL>return MR<EOL>

Returns the maximum statistic for each non-singleton cluster and
its descendents.

Parameters
----------
Z : array_like
    The hierarchical clustering encoded as a matrix. See
    ``linkage`` for more information.
R : array_like
    The inconsistency matrix.
i : int
    The column of `R` to use as the statistic.

Returns
-------
MR : ndarray
    Calculates the maximum statistic for the i'th column of the
    inconsistency matrix `R` for each non-singleton cluster
    node. ``MR[j]`` is the maximum over ``R[Q(j)-n, i]`` where
    ``Q(j)`` the set of all node ids corresponding to nodes below
    and including ``j``.


Z = np.asarray(Z, order='<STR_LIT:c>')<EOL>T = np.asarray(T, order='<STR_LIT:c>')<EOL>if type(T) != np.ndarray or T.dtype != '<STR_LIT:i>':<EOL><INDENT>raise TypeError('<STR_LIT>')<EOL><DEDENT>is_valid_linkage(Z, throw=True, name='<STR_LIT>')<EOL>if len(T) != Z.shape[<NUM_LIT:0>] + <NUM_LIT:1>:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>Cl = np.unique(T)<EOL>kk = len(Cl)<EOL>L = np.zeros((kk,), dtype='<STR_LIT:i>')<EOL>M = np.zeros((kk,), dtype='<STR_LIT:i>')<EOL>n = Z.shape[<NUM_LIT:0>] + <NUM_LIT:1><EOL>[Z, T] = _copy_arrays_if_base_present([Z, T])<EOL>s = _hierarchy.leaders(Z, T, L, M, int(kk), int(n))<EOL>if s >= <NUM_LIT:0>:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>') % s)<EOL><DEDENT>return (L, M)<EOL>

Returns the root nodes in a hierarchical clustering.

Returns the root nodes in a hierarchical clustering corresponding
to a cut defined by a flat cluster assignment vector ``T``. See
the ``fcluster`` function for more information on the format of ``T``.

For each flat cluster :math:`j` of the :math:`k` flat clusters
represented in the n-sized flat cluster assignment vector ``T``,
this function finds the lowest cluster node :math:`i` in the linkage
tree Z such that:

  * leaf descendents belong only to flat cluster j
    (i.e. ``T[p]==j`` for all :math:`p` in :math:`S(i)` where
    :math:`S(i)` is the set of leaf ids of leaf nodes descendent
    with cluster node :math:`i`)

  * there does not exist a leaf that is not descendent with
    :math:`i` that also belongs to cluster :math:`j`
    (i.e. ``T[q]!=j`` for all :math:`q` not in :math:`S(i)`).  If
    this condition is violated, ``T`` is not a valid cluster
    assignment vector, and an exception will be thrown.

Parameters
----------
Z : ndarray
    The hierarchical clustering encoded as a matrix. See
    ``linkage`` for more information.
T : ndarray
    The flat cluster assignment vector.

Returns
-------
L : ndarray
    The leader linkage node id's stored as a k-element 1-D array
    where ``k`` is the number of flat clusters found in ``T``.

    ``L[j]=i`` is the linkage cluster node id that is the
    leader of flat cluster with id M[j].  If ``i < n``, ``i``
    corresponds to an original observation, otherwise it
    corresponds to a non-singleton cluster.

    For example: if ``L[3]=2`` and ``M[3]=8``, the flat cluster with
    id 8's leader is linkage node 2.
M : ndarray
    The leader linkage node id's stored as a k-element 1-D array where
    ``k`` is the number of flat clusters found in ``T``. This allows the
    set of flat cluster ids to be any arbitrary set of ``k`` integers.


return self.id<EOL>

The identifier of the target node.

For ``0 <= i < n``, `i` corresponds to original observation i.
For ``n <= i < 2n-1``, `i` corresponds to non-singleton cluster formed
at iteration ``i-n``.

Returns
-------
id : int
    The identifier of the target node.


return self.count<EOL>

The number of leaf nodes (original observations) belonging to
the cluster node nd. If the target node is a leaf, 1 is
returned.

Returns
-------
get_count : int
    The number of leaf nodes below the target node.


return self.left<EOL>

Return a reference to the left child tree object.

Returns
-------
left : ClusterNode
    The left child of the target node.  If the node is a leaf,
    None is returned.


return self.right<EOL>

Returns a reference to the right child tree object.

Returns
-------
right : ClusterNode
    The left child of the target node.  If the node is a leaf,
    None is returned.


return self.left is None<EOL>

Returns True if the target node is a leaf.

Returns
-------
leafness : bool
    True if the target node is a leaf node.