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.