EVOLUTION-MANAGER

Edit File: dendrogram.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: General Tree Structures</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="R.css" />
</head><body>

<table width="100%" summary="page for dendrogram {stats}"><tr><td>dendrogram {stats}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>General Tree Structures</h2>

<h3>Description</h3>

Class <code>"dendrogram"</code> provides general functions for handling
tree-like structures. It is intended as a replacement for similar
functions in hierarchical clustering and classification/regression
trees, such that all of these can use the same engine for plotting or
cutting trees.

<h3>Usage</h3>

<pre>
as.dendrogram(object, ...)
## S3 method for class 'hclust'
as.dendrogram(object, hang = -1, check = TRUE, ...)

## S3 method for class 'dendrogram'
as.hclust(x, ...)

## S3 method for class 'dendrogram'
plot(x, type = c("rectangle", "triangle"),
      center = FALSE,
      edge.root = is.leaf(x) || !is.null(attr(x,"edgetext")),
      nodePar = NULL, edgePar = list(),
      leaflab = c("perpendicular", "textlike", "none"),
      dLeaf = NULL, xlab = "", ylab = "", xaxt = "n", yaxt = "s",
      horiz = FALSE, frame.plot = FALSE, xlim, ylim, ...)

## S3 method for class 'dendrogram'
cut(x, h, ...)

## S3 method for class 'dendrogram'
merge(x, y, ..., height,
      adjust = c("auto", "add.max", "none"))

## S3 method for class 'dendrogram'
nobs(object, ...)

## S3 method for class 'dendrogram'
print(x, digits, ...)

## S3 method for class 'dendrogram'
rev(x)

## S3 method for class 'dendrogram'
str(object, max.level = NA, digits.d = 3,
    give.attr = FALSE, wid = getOption("width"),
    nest.lev = 0, indent.str = "",
    last.str = getOption("str.dendrogram.last"), stem = "--",
    ...)

is.leaf(object)
</pre>

<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>object</code></td>
<td>
any R object that can be made into one of class
<code>"dendrogram"</code>.
</td></tr>
<tr valign="top"><td><code>x, y</code></td>
<td>
object(s) of class <code>"dendrogram"</code>.
</td></tr>
<tr valign="top"><td><code>hang</code></td>
<td>
numeric scalar indicating how the height of leaves
should be computed from the heights of their parents; see
<code><a href="hclust.html">plot.hclust</a></code>.
</td></tr>
<tr valign="top"><td><code>check</code></td>
<td>
logical indicating if <code>object</code> should be checked for
validity. This check is not necessary when <code>x</code> is known to be
valid such as when it is the direct result of <code>hclust()</code>. The
default is <code>check=TRUE</code>, e.g. for protecting against memory
explosion with invalid inputs.
</td></tr>
<tr valign="top"><td><code>type</code></td>
<td>
type of plot.
</td></tr>
<tr valign="top"><td><code>center</code></td>
<td>
logical; if <code>TRUE</code>, nodes are plotted centered with
respect to the leaves in the branch. Otherwise (default), plot them
in the middle of all direct child nodes.
</td></tr>
<tr valign="top"><td><code>edge.root</code></td>
<td>
logical; if true, draw an edge to the root node.
</td></tr>
<tr valign="top"><td><code>nodePar</code></td>
<td>
a <code>list</code> of plotting parameters to use for the
nodes (see <code><a href="../../graphics/html/points.html">points</a></code>) or <code>NULL</code> by default which
does not draw symbols at the nodes. The list may contain components
named <code>pch</code>, <code>cex</code>, <code>col</code>, <code>xpd</code>,
and/or <code>bg</code> each of
which can have length two for specifying separate attributes for
inner nodes and leaves. Note that the default of
<code>pch</code> is <code>1:2</code>, so you may want to use <code>pch = NA</code> if
you specify <code>nodePar</code>.
</td></tr>
<tr valign="top"><td><code>edgePar</code></td>
<td>
a <code>list</code> of plotting parameters to use for the
edge <code><a href="../../graphics/html/segments.html">segments</a></code> and labels (if there's an
<code>edgetext</code>). The list may contain components
named <code>col</code>, <code>lty</code> and <code>lwd</code> (for the segments),
<code>p.col</code>, <code>p.lwd</code>, and <code>p.lty</code> (for the
<code><a href="../../graphics/html/polygon.html">polygon</a></code> around the text) and <code>t.col</code> for the text
color. As with <code>nodePar</code>, each can have length two for
differentiating leaves and inner nodes.

</td></tr>
<tr valign="top"><td><code>leaflab</code></td>
<td>
a string specifying how leaves are labeled. The
default <code>"perpendicular"</code> write text vertically (by default). 
<code>"textlike"</code> writes text horizontally (in a rectangle), and 
<code>"none"</code> suppresses leaf labels.
</td></tr>
<tr valign="top"><td><code>dLeaf</code></td>
<td>
a number specifying the distance in user
coordinates between the tip of a leaf and its label. If <code>NULL</code>
as per default, 3/4 of a letter width or height is used.
</td></tr>
<tr valign="top"><td><code>horiz</code></td>
<td>
logical indicating if the dendrogram should be drawn
horizontally or not.
</td></tr>
<tr valign="top"><td><code>frame.plot</code></td>
<td>
logical indicating if a box around the plot should
be drawn, see <code><a href="../../graphics/html/plot.default.html">plot.default</a></code>.
</td></tr>
<tr valign="top"><td><code>h</code></td>
<td>
height at which the tree is cut.
</td></tr>
<tr valign="top"><td><code>height</code></td>
<td>
height at which the two dendrograms should be merged. If not
specified (or <code>NULL</code>), the default is ten percent larger than
the (larger of the) two component heights.
</td></tr>
<tr valign="top"><td><code>adjust</code></td>
<td>
a string determining if the leaf values should be
adjusted. The default, <code>"auto"</code>, checks if the (first) two
dendrograms both start at <code>1</code>; if they do, code&quot;add.max&quot; is
chosen, which adds the maximum of the previous dendrogram leaf
values to each leaf of the &ldquo;next&rdquo; dendrogram. Specifying
<code>adjust</code> to another value skips the check and hence is a tad
more efficient.
</td></tr>
<tr valign="top"><td><code>xlim, ylim</code></td>
<td>
optional x- and y-limits of the plot, passed to
<code><a href="../../graphics/html/plot.default.html">plot.default</a></code>. The defaults for these show the full
dendrogram.
</td></tr>
<tr valign="top"><td><code>..., xlab, ylab, xaxt, yaxt</code></td>
<td>
graphical parameters, or arguments for
other methods.
</td></tr>
<tr valign="top"><td><code>digits</code></td>
<td>
integer specifying the precision for printing, see
<code><a href="../../base/html/print.default.html">print.default</a></code>.
</td></tr>
<tr valign="top"><td><code>max.level, digits.d, give.attr, wid, nest.lev, indent.str</code></td>
<td>
arguments
to <code>str</code>, see <code><a href="../../utils/html/str.html">str.default</a>()</code>. Note that
<code>give.attr = FALSE</code> still shows <code>height</code> and <code>members</code>
attributes for each node.
</td></tr>
<tr valign="top"><td><code>last.str, stem</code></td>
<td>
strings used for <code>str()</code> specifying how the
last branch (at each level) should start and the stem
to use for each dendrogram branch. In some environments, using
<code>last.str = "'"</code> will provide much nicer looking output, than
the historical default <code>last.str = "`"</code>.
</td></tr>
</table>

<h3>Details</h3>

The dendrogram is directly represented as a nested list where each
component corresponds to a branch of the tree. Hence, the first
branch of tree <code>z</code> is <code>z[[1]]</code>, the second branch of the
corresponding subtree is <code>z[[1]][[2]]</code>, or shorter
<code>z[[c(1,2)]]</code>, etc.. Each node of the tree
carries some information needed for efficient plotting or cutting as
attributes, of which only <code>members</code>, <code>height</code> and
<code>leaf</code> for leaves are compulsory:

<dl>
<dt><code>members</code></dt><dd>total number of leaves in the branch
</dd>
<dt><code>height</code></dt><dd>numeric non-negative height at which the node
is plotted.
</dd>
<dt><code>midpoint</code></dt><dd>numeric horizontal distance of the node from
the left border (the leftmost leaf) of the branch (unit 1 between
all leaves). This is used for <code>plot(*, center = FALSE)</code>.
</dd>
<dt><code>label</code></dt><dd>character; the label of the node
</dd>
<dt><code>x.member</code></dt><dd>for <code>cut()$upper</code>,
the number of former members; more generally a substitute
for the <code>members</code> component used for &lsquo;horizontal&rsquo;
(when <code>horiz = FALSE</code>, else &lsquo;vertical&rsquo;) alignment.
</dd>
<dt><code>edgetext</code></dt><dd>character; the label for the edge leading to
the node
</dd>
<dt><code>nodePar</code></dt><dd>a named list (of length-1 components)
specifying node-specific attributes for <code><a href="../../graphics/html/points.html">points</a></code>
plotting, see the <code>nodePar</code> argument above.
</dd>
<dt><code>edgePar</code></dt><dd>a named list (of length-1 components)
specifying attributes for <code><a href="../../graphics/html/segments.html">segments</a></code> plotting of the
edge leading to the node, and drawing of the <code>edgetext</code> if
available, see the <code>edgePar</code> argument above.
</dd>
<dt><code>leaf</code></dt><dd>logical, if <code>TRUE</code>, the node is a leaf of
the tree.
</dd></dl>

<code>cut.dendrogram()</code> returns a list with components <code>$upper</code>
and <code>$lower</code>, the first is a truncated version of the original
tree, also of class <code>dendrogram</code>, the latter a list with the
branches obtained from cutting the tree, each a <code>dendrogram</code>.

There are <code><a href="../../base/html/Extract.html">[[</a></code>, <code><a href="../../base/html/print.html">print</a></code>, and <code><a href="../../utils/html/str.html">str</a></code>
methods for <code>"dendrogram"</code> objects where the first one
(extraction) ensures that selecting sub-branches keeps the class,
i.e., returns a dendrogram even if only a leaf.
On the other hand, <code><a href="../../base/html/Extract.html">[</a></code> (single bracket) extraction
returns the underlying list structure.

Objects of class <code>"hclust"</code> can be converted to class
<code>"dendrogram"</code> using method <code>as.dendrogram()</code>, and since R
2.13.0, there is also a <code><a href="as.hclust.html">as.hclust</a>()</code> method as an inverse.

<code>rev.dendrogram</code> simply returns the dendrogram <code>x</code> with
reversed nodes, see also <code><a href="reorder.dendrogram.html">reorder.dendrogram</a></code>.

The <code><a href="../../base/html/merge.html">merge</a>(x, y, ...)</code> method merges two or more
dendrograms into a new one which has <code>x</code> and <code>y</code> (and
optional further arguments) as branches. Note that before R 3.1.2,
<code>adjust = "none"</code> was used implicitly, which is invalid when,
e.g., the dendrograms are from <code><a href="dendrogram.html">as.dendrogram</a>(hclust(..))</code>.

<code><a href="nobs.html">nobs</a>(object)</code> returns the total number of leaves (the
<code>members</code> attribute, see above).

<code>is.leaf(object)</code> returns logical indicating if <code>object</code> is a
leaf (the most simple dendrogram).

<code>plotNode()</code> and <code>plotNodeLimit()</code> are helper functions.

<h3>Warning</h3>

Some operations on dendrograms such as <code>merge()</code> make use of
recursion. For deep trees it may be necessary to increase
<code><a href="../../base/html/options.html">options</a>("expressions")</code>: if you do, you are likely to need
to set the C stack size (<code><a href="../../base/html/Cstack_info.html">Cstack_info</a>()[["size"]]</code>) larger
than the default where possible.

<dl>
<dt><code>plot()</code>:</dt><dd>When using <code>type = "triangle"</code>,
<code>center = TRUE</code> often looks better.
</dd>
<dt><code>str(d)</code>:</dt><dd>If you really want to see the internal
structure, use <code>str(unclass(d))</code> instead.
</dd>
</dl>

<code><a href="dendrapply.html">dendrapply</a></code> for applying a function to each node.
<code><a href="order.dendrogram.html">order.dendrogram</a></code> and <code><a href="reorder.dendrogram.html">reorder.dendrogram</a></code>;
further, the <code><a href="../../base/html/labels.html">labels</a></code> method.

<h3>Examples</h3>

<pre>
require(graphics); require(utils)

hc &lt;- hclust(dist(USArrests), "ave")
(dend1 &lt;- as.dendrogram(hc)) # "print()" method
str(dend1)          # "str()" method
str(dend1, max = 2, last.str =  "'") # only the first two sub-levels
oo &lt;- options(str.dendrogram.last = "\\") # yet another possibility
str(dend1, max = 2) # only the first two sub-levels
options(oo)  # .. resetting them

op &lt;- par(mfrow =  c(2,2), mar = c(5,2,1,4))
plot(dend1)
## "triangle" type and show inner nodes:
plot(dend1, nodePar = list(pch = c(1,NA), cex = 0.8, lab.cex = 0.8),
      type = "t", center = TRUE)
plot(dend1, edgePar = list(col = 1:2, lty = 2:3),
     dLeaf = 1, edge.root = TRUE)
plot(dend1, nodePar = list(pch = 2:1, cex = .4*2:1, col = 2:3),
     horiz = TRUE)

## simple test for as.hclust() as the inverse of as.dendrogram():
stopifnot(identical(as.hclust(dend1)[1:4], hc[1:4]))

dend2 &lt;- cut(dend1, h = 70)
plot(dend2$upper)
## leaves are wrong horizontally:
plot(dend2$upper, nodePar = list(pch = c(1,7), col = 2:1))
##  dend2$lower is *NOT* a dendrogram, but a list of .. :
plot(dend2$lower[[3]], nodePar = list(col = 4), horiz = TRUE, type = "tr")
## "inner" and "leaf" edges in different type &amp; color :
plot(dend2$lower[[2]], nodePar = list(col = 1),   # non empty list
     edgePar = list(lty = 1:2, col = 2:1), edge.root = TRUE)
par(op)
d3 &lt;- dend2$lower[[2]][[2]][[1]]
stopifnot(identical(d3, dend2$lower[[2]][[c(2,1)]]))
str(d3, last.str = "'")

## to peek at the inner structure "if you must", use '[..]' indexing :
str(d3[2][[1]]) ## or the full
str(d3[])

## merge() to join dendrograms:
(d13 &lt;- merge(dend2$lower[[1]], dend2$lower[[3]]))
## merge() all parts back (using default 'height' instead of original one):
den.1 &lt;- Reduce(merge, dend2$lower)
## or merge() all four parts at same height --&gt; 4 branches (!)
d. &lt;- merge(dend2$lower[[1]], dend2$lower[[2]], dend2$lower[[3]],
            dend2$lower[[4]])
## (with a warning) or the same using  do.call :
stopifnot(identical(d., do.call(merge, dend2$lower)))
plot(d., main = "merge(d1, d2, d3, d4)  |-&gt;  dendrogram with a 4-split")

## "Zoom" in to the first dendrogram :
plot(dend1, xlim = c(1,20), ylim = c(1,50))

nP &lt;- list(col = 3:2, cex = c(2.0, 0.75), pch =  21:22,
           bg =  c("light blue", "pink"),
           lab.cex = 0.75, lab.col = "tomato")
plot(d3, nodePar= nP, edgePar = list(col = "gray", lwd = 2), horiz = TRUE)

addE &lt;- function(n) {
      if(!is.leaf(n)) {
        attr(n, "edgePar") &lt;- list(p.col = "plum")
        attr(n, "edgetext") &lt;- paste(attr(n,"members"),"members")
      }
      n
}
d3e &lt;- dendrapply(d3, addE)
plot(d3e, nodePar =  nP)
plot(d3e, nodePar =  nP, leaflab = "textlike")

</pre>

<hr /><div style="text-align: center;">[Package stats version 3.6.0 <a href="00Index.html">Index</a>]</div>
</body></html>