idendro: Interactive Dendrogram

In tsieger/idendro: Interactive Dendrograms

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 the 'cranvas' package. The integration with 'cranvas' (but also with the user's code) is made possible by communicating over mutable data frames (mutaframes) from the 'plumbr' package. 'idendro' can be used to inspect quite large dendrograms (tens of thousands of observations, at least).

Usage

idendro(h, qx = NULL, x = qx, zoomFactor = 1/240, 
    observationAnnotationEnabled = TRUE, 
    clusterColors = c("red", "green", "blue", "yellow", "magenta", 
        "cyan", "darkred", "darkgreen", "purple", "darkcyan"), 
    unselectedClusterColor = "black", maxClusterCount = length(clusterColors), 
    heatmapEnabled = TRUE, doSmoothHeatmap = NULL, heatmapSmoothing = c("none", 
        "cluster", "zoom"), heatmapColors = colorRampPalette(c("#00007F", 
        "blue", "#007FFF", "cyan", "#7FFF7F", "yellow", "#FF7F00", 
        "red", "#7F0000"))(10), heatmapColorCount = 10, doScaleHeatmap = TRUE, 
    doScaleHeatmapByRows = FALSE, heatmapRelSize = 0.2, 
    heatmapInspectFormatFun = format, brushedmapEnabled = !is.null(qx), 
    separateGui = FALSE, graphicalClusterInfos = TRUE, 
    textualClusterInfos = TRUE, geometry = c(0, 0, 600, 400), 
    clipDendro = TRUE, opengl = NULL)

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.
qx	mutaframe holding observations that were clustered giving rise to 'h', with metadata (special columns) for interaction, as created by 'cranvas::qdata'. If 'qx' is enriched with 'idendro'-specific metadata columns (i.e. '.cluster', '.inCurrentCluster'), the initial cluster selection is based on them; otherwise there are no clusters selected initially. A regular data frame can be passed instead of a mutaframe, in which case it will get converted into a mutaframe automatically. This parameter is optional.
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. If missing, it will be guessed from 'qx' by omitting any columns starting in '.'.
zoomFactor	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?
doSmoothHeatmap	(deprecated, use ‘heatmapSmoothing’ instead)
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(.)’. [DEPRECATED:] Alternatively, a function that takes a single numeric argument, the number of heat map colors (see the ‘heatmapColorCount’ argument) and returns colors to be used in heat map can be supplied. WARNING: the number of colors used by heat map can influence the time spent drawing the heat map significantly (for large data sets).
heatmapColorCount	[DEPRECATED] the number of colors used in the heat map. This argument gets used only if the ‘heatmapColors’ argument refers to a function that takes a single numeric argument, ‘n’, and generates a list of ‘n’ colors. If ‘heatmapColors’ refers to a function, ‘heatmapColorCount’ is passed as the argument to that function. WARNING: the number of colors used by heat map can influence the time spent drawing the heat map significantly (for large data sets).
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 both the dendrogram and the heat map. The default is 20%.
heatmapInspectFormatFun	function used to format features of observations when flying over the heatmap. By default, the 'format' function gets used.
brushedmapEnabled	shall brushed map be drawn?
separateGui	shall GUI be integrated into the dendrogram window, or shall it be separated in a standalone window? (The default is integrated GUI.)
graphicalClusterInfos	depict cluster-specific statistics graphically? (The default is TRUE.)
textualClusterInfos	depict cluster-specific statistics textually? (The default is TRUE.)
geometry	window geometry (The default is 600x400.)
clipDendro	clip dendrogram to the dendrogram layer? The default is TRUE, meaning the dendrogram does not interfere with other layers. On some systems, however, clipping might not work properly (border branches might not get rendered), so disabling dendrogram clipping might be desired.
opengl	use OpenGL for qtpaint scene rendering? If non-NULL, the value supplied is passed as the ‘opengl’ argument to qtpaint::qplotView. Useful when OpenGL does not work properly on your system. Note, however, that for large data sets it slows drawing down considerably.

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). Individual features of individual observations can be studied by flying over the heatmap having the left mouse button pressed.

The brushed map indicates which observations are currently selected by some external plot/tool 'idendro' is integrated with (e.g. a cranvas plot). Technically speaking, the current selection is determined by the value of the '.brushed' metadata column in the 'qx' mutable data frame. 'idendro' listens to changes made to the '.brushed' column by the external plot/tool.

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 (the amount of zoom can be controlled by the 'zoomFactor' argument). 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. The observations forming the current cluster are indicated by the '.inCurrentCluster' column in the 'qx' mutaframe, which can be used by external applications to display the current cluster-specific information (see 'idendroDemoWithUserCallback').

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

observations according to the color of the clusters they appear in, and listens to changes being made to the '.brushed' metadata to learn what observations are currently being brushed.

Note that if the value returned is passed to a subsequent call to 'idendro', the cluster selection saved in the mutaframe will get restored.

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

hclust, plclust, identify.hclust, rect.hclust, cutree, dendrogram, cranvas::qdata

Examples

data(iris, envir = environment())
hx <- hclust(dist(iris[, 1:4]))
idendro(hx, iris)

# see demos for more examples

tsieger/idendro documentation built on July 7, 2022, 2:24 a.m.