clustergram object

Object containing hierarchical clustering analysis data

Description

A clustergram object contains hierarchical clustering analysis data that you can view in a heat map and dendrograms.

Create a clustergram object using the object constructor function clustergram. View a graphical representation of the clustergram object in a heat map and dendrograms using the view method.

The clustergram class is a subclass of the HeatMap class.

Method Summary

Following are methods of a clustergram object:

addTitle (clustergram)Add title to clustergram
addXLabel (clustergram)Label x-axis of clustergram
addYLabel (clustergram)Label y-axis of clustergram
clusterGroup (clustergram)Select cluster group
get (clustergram)Retrieve information about clustergram object
plot (clustergram)Render clustergram and dendrograms for clustergram object
set (clustergram)Set property of clustergram object
view (clustergram)View clustergram and dendrograms of clustergram object

Property Summary

Properties for Clustering Analysis and Clustergram Creation

Property NameDescription
Standardize

String or number specifying the dimension for standardizing the data values. This property transforms the standardized values so that the mean is 0 and the standard deviation is 1 in the specified dimension. Choices are:

  • 'column' or 1 — Standardize along the columns of data.

  • 'row' or 2 — Standardize along the rows of data.

  • 'none' or 3 (default) — Do not standardize.

Cluster

String or number specifying the dimension for clustering the values in the data. Choices are:

  • 'column' or 1 — Cluster along the columns of data only, which results in clustered rows.

  • 'row' or 2 — Cluster along the rows of data only, which results in clustered columns.

  • 'all' or 3 (default) — Cluster along the columns of data, then cluster along the rows of row-clustered data.

RowPDist

String specifying the distance metric to pass to the pdist function (Statistics Toolbox™ software) to calculate the pairwise distances between rows. For information on choices, see the pdist function. Default is 'euclidean'.

    Note:   If the distance metric requires extra arguments, then RowPDistValue is a cell array. For example, to use the Minkowski distance with exponent P, you would use {'minkowski', P}.

ColumnPDist

String specifying the distance metric to pass to the pdist function (Statistics Toolbox software) to calculate the pairwise distances between columns. For information on choices, see the pdist function. Default is 'euclidean'.

    Note:   If the distance metric requires extra arguments, then ColumnPDistValue is a cell array. For example, to use the Minkowski distance with exponent P, you would use {'minkowski', P}.

LinkageString or two-element cell array of strings specifying the linkage method to pass to the linkage function (Statistics Toolbox software) to create the hierarchical cluster tree for rows and columns. If a two-element cell array of strings, this property uses the first element for linkage between rows, and the second element for linkage between columns. For information on choices, see the linkage function. Default is 'average'.
DendrogramScalar or two-element numeric vector or cell array of strings specifying the 'colorthreshold' property to pass to the dendrogram function (Statistics Toolbox software) to create the dendrogram plot. If a two-element numeric vector or cell array, the first element is for the rows, and the second element is for the columns. For more information, see the dendrogram function.
OptimalLeafOrderEnables or disables the optimal leaf ordering calculation, which determines the leaf order that maximizes the similarity between neighboring leaves. Choices are true (enable) or false (disable). Default depends on the size of Data, the matrix of data used to create the clustergram object. If the number of rows or columns in Data exceeds 1500, default is false; otherwise, default is true.

    Tip   Disabling the optimal leaf ordering calculation can be useful when working with large data sets, because this calculation consumes a lot of memory and time.

Colormap

Either of the following:

  • M-by-3 matrix of RGB values

  • Name or function handle of a function that returns a colormap, such as redgreencmap or redbluecmap

Default is redgreencmap.
DisplayRange

Positive scalar specifying the display range of standardized values. Default is 3, which means there is a color variation for values between –3 and 3, but values >3 are the same color as 3, and values < –3 are the same color as –3.

For example, if you specify redgreencmap for the 'Colormap' property, pure red represents values ≥ DisplayRangeValue, and pure green represents values ≤ –DisplayRangeValue.

SymmetricForces the color scale of the heat map to be symmetric around zero. Choices are true (default) or false.
LogTransControls the log2 transform of the data from natural scale. Choices are true or false (default).
DisplayRatio

Either of the following:

  • Scalar

  • Two-element vector

This property specifies the ratio of space that the row and column dendrograms occupy relative to the heat map. If DisplayRatio is a scalar, it is used as the ratio for both dendrograms. If DisplayRatio is a two-element vector, the first element is used for the ratio of the row dendrogram width to the heat map width, and the second element is used for the ratio of the column dendrogram height to the heat map height. The second element is ignored for one-dimensional clustergrams. Default is 1/5.

ImputeFun

One of the following:

  • Name of a function that imputes missing data.

  • Handle to a function that imputes missing data.

  • Cell array where the first element is the name of or handle to a function that imputes missing data. The remaining elements are property name/property value pairs used as inputs to the function.

ShowDendrogram

Shows and hides the dendrogram tree diagrams with the clustergram. Choices are 'on' (default) or 'off'.

    Tip   After displaying a clustergram in a Clustergram window, click the Show Dendrogram button on the toolbar to show and hide the dendrograms.

Properties for Group Labels

Property NameDescription
RowGroupMarker

Structure or structure array containing information for annotating the groups (clusters) of rows determined by the clustergram function. The structure or structures contain the following fields. If a single structure, then the fields contain a cell array of elements. If a structure array, then the fields contain one element:

  • GroupNumber — Scalar specifying the row group number to annotate.

  • Annotation — String specifying text to annotate the row group.

  • Color — String or three-element vector of RGB values specifying a color to label the row group. For more information on specifying colors, see ColorSpec. If this field is empty, default is 'blue'.

ColumnGroupMarker

Structure or structure array containing information for annotating the groups (clusters) of columns determined by the clustergram function. The structure or structures contain the following fields. If a single structure, then the fields contain a cell array of elements. If a structure array, then the fields contain one element:

  • GroupNumber — Scalar specifying the column group number to annotate.

  • Annotation — String specifying text to annotate the column group.

  • Color — String or three-element vector of RGB values specifying a color to label the column group. For more information on specifying colors, see ColorSpec. If this field is empty, default is 'blue'.

Properties for Row and Column Labels

Property NameDescription
RowLabelsVector of numbers or cell array of text strings to label the rows in the dendrogram and heat map. Default is a vector of values 1 through M, where M is the number of rows in Data, the matrix of data used by the clustergram function to create the clustergram object.
ColumnLabelsVector of numbers or cell array of text strings to label the columns in the dendrogram and heat map. Default is a vector of values 1 through M, where M is the number of columns in Data, the matrix of data used by the clustergram function to create the clustergram object.
ColumnLabelsLocation

Read-only string specifying the location of the column labels. For clustergram objects, it is always 'bottom' (default).

RowLabelsLocation

Read-only string specifying the location of the row labels. For clustergram objects, it is always 'right' (default).

RowLabelsColor

Structure or structure array containing color information for labeling the rows (y-axis) of the clustergram. The structure or structures contain the following fields. If a single structure, then the fields contain a cell array of elements. If a structure array, then the fields contain one element:

  • Labels — String specifying a row label listed in the RowLabels vector.

  • Colors — String or three-element vector of RGB values specifying a color for the row label specified in the Labels field. For more information on specifying colors, see ColorSpec. If this field is empty, default colors are assigned to the row label.

ColumnLabelsColor

Structure or structure array containing color information for labeling the columns (x-axis) of the clustergram. The structure or structures contain the following fields. If a single structure, then the fields contain a cell array of elements. If a structure array, then the fields contain one element:

  • Labels — String specifying a column label listed in the ColumnLabels vector.

  • Colors — String or three-element vector of RGB values specifying a color for the column label specified in the Labels field. For more information on specifying colors, see ColorSpec. If this field is empty, default colors are assigned to the column label.

LabelsWithMarkers

Controls the display of colored markers instead of colored text for the row labels and column labels. Choices are true or false (default).

RowLabelsRotate

Numeric value in degrees rotation specifying the orientation of row (y-axis) labels. Default is 0 degrees, which is horizontal. Positive values cause counterclockwise rotation.

ColumnLabelsRotate

Numeric value in degrees rotation specifying the orientation of column (x-axis) labels. Default is 90 degrees, which is vertical. Values greater than 90 degrees cause counterclockwise rotation.

Properties for Annotating Data

Property NameDescription
Annotate

Controls the display of intensity values on each area of the heat map. Choices are true or false (default).

    Tip   After displaying a clustergram in a Clustergram window, click the Annotate button on the toolbar to show and hide the intensity values.

AnnotPrecision

Positive integer specifying the precision of the intensity values when displayed on the heat map. Default is 2.

AnnotColor

String or three-element vector of RGB values specifying a color, which is used for the text of the intensity values when displayed on the heat map. Default is 'white'. For more information on specifying colors, see ColorSpec.

Examples

    Note:   The following examples use the get and set methods with property names and values of a clustergram object. When supplying a PropertyName, be aware that it is case sensitive.

Determining Properties and Property Values of a Clustergram Object

Display all properties and their current values of a clustergram object, CGobj:

get(CGobj)

Return all properties and their current values of CGobj, a clustergram object, to CGstruct, a scalar structure, in which each field name is a property of a clustergram object, and each field contains the value of that property:

CGstruct = get(CGobj)

Return the value of a specific property of a clustergram object, CGobj, using either:

PropertyValue = get(CGobj, 'PropertyName')
PropertyValue = CGobj.PropertyName

Return the value of specific properties of a clustergram object, CGobj:

[Property1Value, Property2Value, ...] = get(CGobj, ...
'Property1Name', 'Property2Name', ...)

Determining Possible Values of Clustergram Object Properties

Display possible values for all properties that have a fixed set of property values in a clustergram object, CGobj:

set(CGobj)

Display possible values for a specific property that has a fixed set of property values in a clustergram object, CGobj:

set(CGobj,  'PropertyName')

Specifying Properties of a Clustergram Object

Set a specific property of a clustergram object, CGobj, using either:

set(CGobj, 'PropertyName', PropertyValue)
CGobj.PropertyName = PropertyValue

Set multiple properties of a clustergram object, CGobj:

set(CGobj,  'Property1Name', Property1Value, ...
    'Property2Name', Property2Value, ...)

More About

Was this topic helpful?