| Type: | Package |
| Title: | Interactive Dendrograms |
| Version: | 1.5.3 |
| Date: | 2017-02-22 |
| Author: | Tomas Sieger |
| Imports: | tcltk, tkrplot, grDevices, graphics, stats |
| Suggests: | rggobi, DendSer, cluster, RColorBrewer, datasets |
| URL: | http://github.com/tsieger/idendr0 |
| Maintainer: | Tomas Sieger <tomas.sieger@seznam.cz> |
| BugReports: | https://github.com/tsieger/idendr0/issues |
| Description: | Interactive dendrogram that enables the user to select and color clusters, to zoom and pan the dendrogram, and to visualize the clustered data not only in a built-in heat map, but also in 'GGobi' interactive plots and user-supplied plots. This is a backport of Qt-based 'idendro' (https://github.com/tsieger/idendro) to base R graphics and Tcl/Tk GUI. |
| License: | GPL-2 |
| LazyLoad: | yes |
| LazyData: | true |
| NeedsCompilation: | no |
| Packaged: | 2017-02-22 12:09:45 UTC; sieger |
| Repository: | CRAN |
| Date/Publication: | 2017-02-22 14:13:11 |
Interactive Dendrograms
Description
Interactive dendrogram that enables the user to select and color clusters, to zoom and pan the dendrogram, and to visualize the clustered data not only in a built-in heat map, but also in 'GGobi' interactive plots and user-supplied plots. This is a backport of Qt-based 'idendro' (<https://github.com/tsieger/idendro>) to base R graphics and Tcl/Tk GUI.
Details
| Package: | idendr0 |
| Type: | Package |
| Title: | Interactive Dendrograms |
| Version: | 1.5.3 |
| Date: | 2017-02-22 |
| Author: | Tomas Sieger |
| Depends: | |
| Imports: | tcltk, tkrplot, grDevices, graphics, stats |
| Suggests: | rggobi, DendSer, cluster, RColorBrewer, datasets |
| URL: | http://github.com/tsieger/idendr0 |
| Maintainer: | Tomas Sieger <tomas.sieger@seznam.cz> |
| BugReports: | https://github.com/tsieger/idendr0/issues |
| License: | GPL-2 |
| LazyLoad: | yes |
| LazyData: | true |
Author(s)
Tomas Sieger
References
Sieger, T., Hurley, C. B., Fiser, K., Beleites, C. (2017) Interactive Dendrograms: The R Packages idendro and idendr0. Journal of Statistical Software, 76(10), 1–22. doi:10.18637/jss.v076.i10
clusterId2SegmentIds
Description
Convert cluster IDs to indices of dendrogram segments.
Usage
clusterId2SegmentIds(ids)Arguments
ids |
cluster IDs |
Value
segment IDs
Author(s)
Tomas Sieger
computeLeafColorIdxs
Description
Compute colors of all leafs in dendrogram according to the current cluster selection.
Usage
computeLeafColorIdxs(df)Arguments
df |
dhared data frame, see 'prepareDendro' |
Value
leaf colors
Author(s)
Tomas Sieger
computeLeafOrder
Description
Compute the assignment of dendrogram leafs to the original observations.
Usage
computeLeafOrder(merging, dbg = 0)Arguments
merging |
(n-1) by 2 matrix describing HCA merging, usually the 'merge' component of the return value from 'hclust' |
dbg |
debug verbosity level |
Value
leaf ordering
Author(s)
Tomas Sieger
computeMemberIndices
Description
Compute indices of observations forming given cluster.
Usage
computeMemberIndices(h, clusterIdx)Arguments
h |
HCA result, usually 'hclust' return value |
clusterIdx |
cluster index |
Value
indices of observations forming cluster 'clusterIdx'
Author(s)
Tomas Sieger
computeSubclusterIndices
Description
Compute indices of all subclusters (even deep down the hierarchy) appearing in given cluster.
Usage
computeSubclusterIndices(h, clusterIdx)Arguments
h |
HCA result, usually 'hclust' return value |
clusterIdx |
cluster index |
Value
subclusters indices
Author(s)
Tomas Sieger
createClustersFromLeafColors
Description
Initialize clusters (i.e. cluster selection) from leaf colors (i.e. assignment of some observations to some clusters)
Usage
createClustersFromLeafColors(df, leafColors, maxClusterCount,
dbg = 0)Arguments
df |
shared data frame, see 'prepareDendro' |
leafColors |
leaf color indices, i.e. a nonnegative number assigned to each observation. 0 means given observation is not member of any cluster, a value i>0 means given observation is a member of cluster 'i'. |
maxClusterCount |
max cluster count |
dbg |
debug verbosity level |
Value
shared data frame 'df' with cluster selection based on 'leafColors'
Author(s)
Tomas Sieger
cutDendro
Description
Select clusters by cutting the current zoom of the dendrogram at a specified height.
Usage
cutDendro(df, cutG, dendroZoom, dbg = FALSE)Arguments
df |
shared data frame |
cutG |
cutting grow height |
dendroZoom |
current dendro zoom region |
dbg |
debug level |
Value
A list of shared data frame 'df' with new cluster selection, and the number of clusters selected.
Author(s)
Tomas Sieger
dendro2fig
Description
Dendrogram -> figure coords conversion.
Usage
dendro2fig(gw)Arguments
gw |
a list of 'g' and 'w' components, g=gw[1]: dendro height ... 0, w=gw[2]: n ... 1 (charm to strange) |
Value
converted values, a list of 'g' and 'w' components
Author(s)
Tomas Sieger
fig2dendro
Description
Fig -> dendro coord conversion.
Usage
fig2dendro(gw)Arguments
gw |
##<< a list of 'g' and 'w' components |
Value
converted values, a list of 'g' and 'w' components
Author(s)
Tomas Sieger
fig2heatmap
Description
Figure -> heatmap coord conversion.
Usage
fig2heatmap(gw)Arguments
gw |
a list of 'g' and 'w' components |
Value
a list of 'g' and 'w' components
Author(s)
Tomas Sieger
gw2xy
Description
Logical grow/width to physical x/y coord conversion.
Usage
gw2xy(gw)Arguments
gw |
a list of 'g' and 'w' components |
Value
a list of 'x' and 'y' components
Author(s)
Tomas Sieger
idendro demo data
Description
Hierarchical cluster analysis demonstration data consisting of raw data (5000 observations having 3 features measured) and clustered data (as computed by ‘hclust’).
Usage
data(hca5000)
Format
A list of 'x' and 'hx' elements. 'x' is a matrix of 5000 rows (observations) by 3 columns (dimensions). 'hx' is an object of class 'hclust' containing the result of hierarchical cluster analysis performed on 'x'.
Examples
if (interactive()) {
library(idendr0)
data(hca5000)
idendro(hca5000$hx, hca5000$x, observationAnnotationEnabled = FALSE)
}
heatmap2fig
Description
Heatmap -> figure coord conversion.
Usage
heatmap2fig(gw)Arguments
gw |
a list of 'g' and 'w' components |
Value
a list of 'g' and 'w' components
Author(s)
Tomas Sieger
Interactive Dendrogram
Description
'idendro' is a plot enabling users to visualize a dendrogram and inspect it interactively: to select and color clusters anywhere in the dendrogram, to zoom and pan the dendrogram, and to visualize the clustered data not only in a built-in heat map, but also in any interactive plot implemented in GGobi (as available using the 'rggobi' package). The integration with GGobi (enabled using the 'ggobi' argument), but also with the user's code is implemented in terms of two callbacks (see the 'colorizeCallback' and 'fetchSelectedCallback' arguments). 'idendro' can be used to inspect quite large dendrograms (tens of thousands of observations, at least).
The 'idendr0' package is a lightweight backport of the 'idendro' package. While the 'idendro' package depends on libraries not easily available on some platforms (e.g. Windows), the 'idendr0' package is based on platform-independent Tcl/Tk graphic widget toolkit, and thus made widely available. However, the 'idendro' package should be preferred, if available, for its better interactivity and performance.
Usage
idendro(h, x = NULL, qx = NULL, clusters = NULL, hscale = 1.5,
vscale = 1.5, silent = FALSE, zoomFactor = 1/240,
observationAnnotationEnabled = TRUE,
clusterColors = c("red", "green", "blue", "yellow", "magenta",
"cyan", "darkred", "darkgreen", "purple", "darkcyan"),
unselectedClusterColor = "black", maxClusterCount = max(length(clusterColors),
ifelse(!is.null(clusters), max(clusters), 0)), heatmapEnabled = TRUE,
heatmapSmoothing = c("none", "cluster", "zoom"),
heatmapColors = colorRampPalette(c("#00007F", "blue", "#007FFF", "cyan",
"#7FFF7F", "yellow", "#FF7F00", "red", "#7F0000"))(10),
doScaleHeatmap = TRUE, doScaleHeatmapByRows = FALSE,
heatmapRelSize = 0.2, colorizeCallback = NULL, fetchSelectedCallback = NULL,
brushedmapEnabled = !is.null(fetchSelectedCallback),
brushedmapRelSize = ifelse(!is.null(x), heatmapRelSize/ncol(x), 0.05),
geometry = NULL, ggobi = FALSE, ggobiGlyphType = 1, ggobiGlyphSize = 1,
ggobiFetchingStyle = "selected", ggobiColorScheme = "Paired 12", dbg = 0, ...)Arguments
h |
object of class 'stats::hclust' (or other class convertible to class 'hclust' by the 'as.hclust' function) describing a hierarchical clustering. If _inversions_ in heights (see 'hclust') is detected, the heights get fixed in a simple naive way by preserving non-negative relative differences in the heights, but changing negative differences to zero. Using clustering with monotone distance measure should be considered in that case. |
x |
data frame holding observations tha were clustered giving rise to 'h'. The heat map will depict this data. (The heat map can be scaled - see the 'doScaleHeatmap' and 'doScaleHeatmapByRows' arguments.) Non-numeric types will get converted to numeric using 'as.numeric'. This parameter is optional. |
qx |
(unused, appears for compatibility with idendro::idendro). |
clusters |
the assignment of observations to clusters to start with, typically the value of a previous call to 'idendro'. A numeric vector of length of the number of observations is expected, in which 0s denote unselected observations, and values of i > 0 mark members of the cluster ‘i’. |
hscale |
horizontal scaling factor of the dendrogram figure. As the dendrogram is implemented as a Tcl/Tk image, and rtcltk does not support image resizing (e.g. on window maximization), the dendrogram keeps its original size regardless of the size of its enclosing window. Thus specifying the hscale of more than 100% is preferred to make the dendrogram large enough. |
vscale |
vertical scaling factor of the dendrogram figure. See 'hscale'. |
silent |
if TRUE, no informative messages will be shown |
zoomFactor |
the amount of zoom in/out as controlled by the mouse wheel |
observationAnnotationEnabled |
shall the names of individual observations (rownames of 'x') be shown next to the dendrogram/heat map? |
clusterColors |
colors of individual clusters |
unselectedClusterColor |
the color of unselected dendrogram branches |
maxClusterCount |
the maximum number of clusters user can select. If greater than the number of 'clusterColors', cluster colors will get recycled. This parameter affects the size of the GUI and the number of clusters that can be selected automatically by "cutting" the dendrogram. |
heatmapEnabled |
shall the heat map be drawn? |
heatmapSmoothing |
heat map smoothing mode, one of 'none' - the heat map gets never smoothed, it displays the features of all the individual observations 'cluster' - the heat map depicts the average features for the currently selected clusters, 'zoom' - the heat map displays the average feature for each elementary (i.e. the finest) cluster seen in the dendrogram currently. |
heatmapColors |
heat map color palette represented by a list of colors, e.g. a sequential palette generated by ‘brewer.pal’, or ‘colorRampPalette(.)(.)’, ‘gray.colors(.)’, or ‘hsv(.)’. |
doScaleHeatmap |
scale each heat map column to the <0,1> range? (The default is TRUE.) |
doScaleHeatmapByRows |
scale heat map rows, not columns (The default is FALSE.) |
heatmapRelSize |
relative size of the heat map - the ratio of the heat map width to the width of the dendrogram, the heat map, and the brushed map. The default is 20%. |
colorizeCallback |
callback function called when cluster selection changes; the argument is a vector assigning color indices (0=no color, >0 colors) to individual observations. |
fetchSelectedCallback |
callback function used to fetch observation selection made externally. The callback must return a boolean vector of length of the number of observations in ‘x’. i-th element in the vector specifies whether given observation is selected. |
brushedmapEnabled |
shall brushed map be drawn? If TRUE, a column vector is drawn next to dendrogram (and heatmap, if there is one) depicting observation that were fetched by fetchSelectedCallback. The color of the observations is the color of the cluster used to fetch observations into. |
brushedmapRelSize |
relative size of the brushed map - the ratio of the brushed map width to the width of the dendrogram, the heat map, and the brushed map. The default is the size of a single column in the heat map, or 5% if there is no heatmap. |
geometry |
window geometry ("width x height + xoffset + yoffset"). Almost useless as the dendrogram does not resize, see the 'hscale' and 'vscale' arguments instead. |
ggobi |
plot feature space projections of ‘x’ in ggobi and bidirectionally integrate with the plot? (defaults to FALSE as some users may not have ggobi available) |
ggobiGlyphType |
ggobi glyph type used to draw observations in ggobi (defaults to a single pixel; see rggobi::glyph_type) |
ggobiGlyphSize |
size of ggobi glyphs (see rggobi::glyph_size) |
ggobiFetchingStyle |
how should we recognize ggobi-selected observations to be fetched to idendro? Use 'selected' to fetch observations selected by ggobi brush, or glyph type number 2-6 to fetch observations selected by ggobi persistent brushing with a specific glyph type. |
ggobiColorScheme |
GGobi color scheme used to color observations in ggobi plots according to the clusters selected in the dendrogram |
dbg |
debug level (0=none, 1=brief, 2=verbose) |
... |
additional graphical parameters to be passed to the dendrogram plot. |
Details
'idendro' displays an interactive dendrogram enriched, optionally, with a heat map and/or a brushed map.
The dendrogram represents the result of a hierarchical cluster analysis performed on a set of observations (see e.g. 'hclust'). There is an axis drawn below the dendrogram displaying the "height" of the clusters in the dendrogram.
The heat map visualizes the observations living in k-dimensional feature space by mapping their features onto a color scale and displaying them as rows of 'k' colored rectangles. By default, normalization (scaling) of individual features to a common visual scale is enabled. Scaling of observations is also supported (see the 'doScaleHeatmapByRows' argument).
The brushed map can indicate which observations are currently selected in some external plot/tool 'idendro' is integrated with (e.g. a GGobi scatter plot matrix). Technically speaking, the current selection must be determined explicitly by clicking the "fetCh selected" button (or pressing the 'Alt+C' shortcut), which results in calling the 'fetchSelectedCallback' function (see arguments).
The dendrogram can be zoomed and panned. To zoom in a specific region, right click and drag in the dendrogram. Mouse wheel can also be used to zoom in and out. To pan a zoomed dendrogram, middle click and drag the mouse. Zooming and panning history is available (see 'GUI').
User can select clusters manually one by one (by clicking at individual clusters in the dendrogram), or automatically by "cutting" the dendrogram at a specified height. To cut the dendrogram, navigate the mouse close to the dendrogram axis (a dashed line will appear across the dendrogram at a specified height), and left click. Clusters just beneath the cutting height will get selected, replacing the clusters currently selected. Selection history is available (see 'GUI').
Graphic User interface (GUI):
In the left part of the dendrogram window, there is a simple GUI. In the top part of the GUI come cluster-specific controls and info panels arranged in rows. (The number of rows is determined by the 'maxClusterCount' argument.) In each row, there is the current cluster selector (a radio button decorated with a cluster ID and a color code (determined by the 'clusterColors' argument)), and cluster-specific statistics: the total number (and the ratio) of the observations in that specific cluster out of the total number of observations, and the number (and the ratio) of the observations in that cluster out of the observations brushed. The current cluster determines which color and ID will be associated with a cluster selected in the dendrogram, At any time, exactly one cluster is selected as the current cluster.
At the bottom of the GUI window, there are buttons controling zooming, cluster selection, and heat map smoothing:
"Undo zoom" - retrieves the previous zoom region from history
"Full view" - zooms the dendrogram out maximally
"Undo selection" - retrieves the previous cluster selection from history
"Unselect" - unselects the current cluster in the dendrogram
"Unselect all" - unselects all clusters
The "heat map smoothing" mode can be set to one of:
"none" - the heat map gets never smoothed, it displays the features of all the individual observations
"cluster" - the heat map displays the average features for the currently selected clusters
"zoom" - the heat map displays the average feature for each elementary (i.e. the finest) cluster seen in the dendrogram currently. When the dendrogram is zoomed out maximally, the features of all the elementary clusters (i.e. the individual observations) are displayed. When the user zooms in the dendrogram, such that some clusters get hidden, the features of the observations forming the hidden clusters get averaged.
"Quit"
Value
vector of colors assigned to observations. 0s denote unselected observations, while values of i > 0 denote the cluster ‘i’.
Author(s)
Tomas Sieger
References
Sieger, T., Hurley, C. B., Fiser, K., Beleites, C. (2017) Interactive Dendrograms: The R Packages idendro and idendr0. Journal of Statistical Software, 76(10), 1–22. doi:10.18637/jss.v076.i10
See Also
idendro::idendro, stats::hclust, stats::plot.hclust
Examples
if (interactive()) {
data(iris, envir = environment())
hc <- hclust(dist(iris[, 1:4]))
idendro(hc, iris)
}
# see demos for more examples
mySeq
Description
Sequence generation resembling matlab ':' operator. The difference from R ‘seq’ is the behaviour in case when from=2, to=1 and b=1 - in that case R seq raises an error, while matlab returns an empty sequence. This function returns an empty sequence as well in this case.
Usage
mySeq(from, to, by = 1)Arguments
from |
starting value |
to |
ending value |
by |
step (defaults to 1) |
Author(s)
Tomas Sieger
popDendroZoomHistory
Description
Restore (and discard from history) the last dendro zoom.
Usage
popDendroZoomHistory(df, dbg = FALSE)Arguments
df |
shared data frame |
dbg |
debug flag/level |
Value
dendro zoom popped (or NULL if stack empty)
Author(s)
Tomas Sieger
popSelectionHistory
Description
Restore (and discard from history) the last cluster selection.
Usage
popSelectionHistory(df, dbg = FALSE)Arguments
df |
shared data frame |
dbg |
debug flag/level |
Value
shared data frame holding cluster selection (or NULL if no selection found in the selection history)
Author(s)
Tomas Sieger
prepareDendro
Description
Perform all computations needed to display a dendrogram and initialize a shared data frame.
This is an internal function not to be called by the user.
Usage
prepareDendro(h, x = NULL, xOrig = NULL, doFlipG = TRUE, dbg = 0)Arguments
h |
an object of class 'stats::hclust' describing a clustering |
x |
a data frame holding observations tha were clustered giving rise to 'h', converted to numeric, and scaled |
xOrig |
a data frame holding observations tha were clustered giving rise to 'h' |
doFlipG |
should branches' heights ("grow") be flipped such that the heights of elementary observations correspond not to 0, but to the height of the dendrogram? |
dbg |
debug verbosity level |
Value
shared data frame
Author(s)
Tomas Sieger
printVar
Description
Print the name, type and value of a variable.
Usage
printVar(x)Arguments
x |
variable to print |
Author(s)
Tomas Sieger
pushDendroZoomHistory
Description
Save the current dendroZoom (as stored in '.sharedEnv').
Usage
pushDendroZoomHistory(df, dendroZoom, dbg = FALSE)Arguments
df |
shared data frame |
dendroZoom |
dendro zoom to push |
dbg |
debug flag/level |
Value
shared data frame with dendro zoom pushed on top of the dendro zoom stack
Author(s)
Tomas Sieger
pushSelectionHistory
Description
Save the current cluster selection (as stored in df).
Usage
pushSelectionHistory(df, dbg = FALSE)Arguments
df |
shared data frame |
dbg |
debug flag/level |
Value
shared data frame with cluster selection pushed on top of the selection stack.
Author(s)
Tomas Sieger
selectCluster
Description
Select the nearest cluster to the position 'pos'.
Usage
selectCluster(pos, df, dendroZoom, dbg = FALSE)Arguments
pos |
(x,y) position in the dendro figure |
df |
shared data frame |
dendroZoom |
the current dendro zoom region (used to determine the scaling) |
dbg |
debug flag/level |
Value
shared data frame
Author(s)
Tomas Sieger
smoothHeatmap
Description
Smooth heatmap by averaging data over observations in clusters.
Usage
smoothHeatmap(x, ch, dbg.heatmap = 0)Arguments
x |
a data frame holding observations tha were clustered |
ch |
number of clusters specifying the amount of smoothing: observations in clusters will get smoothed together, the value of 'n' specifies no smoothing while the value of 1 would lead to maximal smoothing |
dbg.heatmap |
debug verbosity level |
Value
a data frame holding smoothed observations
Author(s)
Tomas Sieger
smoothHeatmapAccordingToClusters
Description
Smooth heatmap by averaging the observations associated with the currently selected clusters. Observations that are not contained in any cluster currently selected stay untouched.
Usage
smoothHeatmapAccordingToClusters(df, dbg.heatmap.smooth = 0)Arguments
df |
shared data frame |
dbg.heatmap.smooth |
debug verbosity level |
Author(s)
Tomas Sieger
unselectAllClusters
Description
Unselect all clusters.
Usage
unselectAllClusters(df, dbg)Arguments
df |
shared data frame |
dbg |
debug flag/level |
Value
a list of a shared data frame 'df' and a boolean flag 'selectionChanged' determing if cluster selection has changed (so the caller can learn whether to redraw clusters).
Author(s)
Tomas Sieger
unselectCurrentCluster
Description
Unselect the current cluster.
Usage
unselectCurrentCluster(df, dbg = FALSE)Arguments
df |
shared data frame |
dbg |
debug flag/level |
Value
a list of shared data frame 'df' and a boolean flag 'selectionChanged' determing if clsuter selection has changed (so the caller can learn whether to redraw clusters).
Author(s)
Tomas Sieger
xy2gw
Description
Physical x/y to logical grow/width coord conversion.
Usage
xy2gw(xy)Arguments
xy |
a list of 'x' and 'y' components |
Value
a list of 'g' and 'w' components
Author(s)
Tomas Sieger