HeatMap

Object containing matrix and heatmap display properties

Description

The HeatMap function creates a HeatMap object. You can use the object to display a heatmap (2-D color image) of matrix data.

Creation

Syntax

HeatMap(data)

HeatMap(data,Name,Value)

Description

hmObj = HeatMap(data) displays a heatmap (2-D color image) of data and returns an object containing the data and display properties.

hmObj = HeatMap(data,Name,Value) sets the object properties using name-value pairs. For example, HeatMap(data,'Annotate',true) displays data values in the heatmap. You can specify multiple name-value pairs. Enclose each property name in quotes.

Input Arguments

data — Heatmap data

DataMatrix object | numeric matrix

Heatmap data, specified as a DataMatrix object or numeric matrix.

Name-Value Pair Arguments

Use comma-separated name-value pair arguments to set the object properties. Enclose each property name in single quotes.

Example: hm = HeatMap(data,'Colormap',redbluecmap,'Annotate',true)

Properties

Standardize — Dimension for standardizing data values

'none' (default) | 'row' | 'column' | 3 | 2 | 1

Dimension for standardizing data values, specified as a character vector, string, or positive integer. Choices are:

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

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

• 'none' or 3 — Do not standardize.

If you specify 'column' or 'row', the function transforms the standardized values so that the mean is 0 and the standard deviation is 1 in the specified dimension.

Example: 'column'

Data Types: double | char | string

Symmetric — Flag to make the heatmap color scale symmetric around zero

true (default) | false

Flag to make the heatmap color scale symmetric around zero, specified as true or false.

Example: false

Data Types: logical

DisplayRange — Display range of standardize values

maximum absolute value in data (default) | positive scalar

Display range of standardize values, specified as a positive scalar. The default is the maximum absolute value in the input data.

For example, if you specify 3, there is a color variation for values between -3 and 3, but values greater than 3 are the same color as 3, and values less than -3 are the same color as -3.

For example, if you specify redgreencmap for the 'Colormap' property, pure red represents values greater than or equal to the specified display range value and pure green represents values less than or equal to the negative of the specified display range value.

Example: 3

Data Types: double

Colormap — Heatmap colors

redgreencmap (default) | matrix | name of function handle

heatmap colors, specified as a three-column (M-by-3) matrix of red-green-blue (RGB) values or the name of a function handle that returns a colormap, such as redgreencmap or redbluecmap.

The default colormap is redgreencmap, in which red represents values above the mean, black represents the mean, and green represents values below the mean of a row (gene) across all columns (samples).

Example: redbluecmap

Data Types: double | char

ImputeFun — Name of function or function handle to impute missing data

character vector | cell array

Name of a function or function handle to impute missing data, specified as a character vector or cell array. If you specify a cell array, the first element must be the name of a function or function handle, and the remaining elements must be name-value pairs used as inputs to the function. Missing data points are colored gray in the heatmap.

If data points are missing, you can use this property to impute the missing values.

Example: 'func1'

Data Types: char

ColumnLabels — Column labels

[1x0 double] (default) | string vector | cell array of character vectors | numeric vector

Column labels, specified as a string vector, cell array of character vectors, or numeric vector. The size of the vector must match the number of columns in the input data.

Example: ["sample1","sample2","sample3"]

Data Types: double | string | cell

RowLabels — Row labels

[] (default) | string vector | cell array of character vectors | numeric vector

Row labels, specified as a string vector, cell array of character vectors, or numeric vector. The size of the vector must match the number of rows in the input data.

Example: ["gene1","gene2","gene3"]

Data Types: double | string | cell

ColumnLabelsRotate — Orientation of column labels

90 (default) | numeric scalar

Orientation of column labels, specified as a numeric scalar. Specify the value of rotation in degrees (positive angles cause counterclockwise rotation).

Example: 30

Data Types: double

RowLabelsRotate — Orientation of row labels

0 (default) | numeric scalar

Orientation of row labels, specified as a numeric scalar. Specify the value of rotation in degrees (positive angles cause counterclockwise rotation).

Example: 30

Data Types: double

Annotate — Flag to display data values in heatmap

false (default) | true

Flag to display data values in the heatmap, specified as true or false.

Example: true

Data Types: logical

AnnotPrecision — Display precision of data values

2 (default) | numeric scalar

Display precision of data values in the heatmap, specified as a numeric scalar. The default number of digits of precision is 2.

Example: 3

Data Types: double

AnnotColor — Text color of displayed data values

'w' (default) | character vector | string | three-element numeric vector

Text color of displayed data values in the heatmap, specified as a character vector, string, or three-element numeric vector. For example, to use cyan, you can enter [0 1 1], 'c', "c", "cyan", or 'cyan'. For details, see Color Options.

Example: 'red'

Data Types: char | string | double

ColumnLabelsColor — Color information for column labels

[] (default) | structure | structure array

Warning

This property will be removed in a future release. Set LabelsWithMarkers to true for colored markers instead of colored texts.

Color information for column labels, specified as a structure or structure array.

For a single structure, you must specify the following fields:

• Labels — Cell array of character vectors specifying column labels listed in the ColumnLabels property.

• Colors — Character vector or string specifying a color for the column labels. If this field is empty, the default color (black) is used.

For a structure array, you must specify a single element in each field for each structure.

• Labels — Character vector or string specifying a column label listed in the ColumnLabels property.

• Colors — Character vector or string specifying a color for the column labels. If this field is empty, the default color (black) is used.

For more information on specifying colors, see Color Options.

Data Types: struct

RowLabelsColor — Color information for row labels

[] (default) | structure | structure array

Warning

This property will be removed in a future release. Set LabelsWithMarkers to true for colored markers instead of colored texts.

Color information for row labels, specified as a structure or structure array.

For a single structure, it must have following fields.

• Labels – Cell array of character vectors specifying row labels listed in the RowLabels property.

• Colors – Character vector or string specifying a color for the row labels. If this field is empty, the default color (black) is used.

For a structure array, each structure must have a single element in each field.

• Labels – Character vector or string specifying a row label listed in the RowLabels property.

• Colors – Character vector or string specifying a color for the row labels. If this field is empty, the default color (black) is used.

For more information on specifying colors, see Color Options.

LabelsWithMarkers — Flag to display colored markers for row and column labels

false (default) | true

Flag to display colored markers instead of colored text for the row and column labels, specified as true or false.

Example: true

Data Types: logical

Object Functions

view	Display heatmap or clustergram
plot	Render heatmap or clustergram
addTitle	Add title to heatmap or clustergram
addXLabel	Label x-axis of heatmap or clustergram
addYLabel	Label y-axis of heatmap or clustergram

Examples

Plot Heatmap of Data Matrix

Create a matrix of data.

data = gallery('invhess',20);

Display a 2-D color heatmap of the data.

hmo = HeatMap(data);

             Standardize: '[column | row | {none}]'
               Symmetric: '[true | false].'
            DisplayRange: 'Scalar.'
                Colormap: []
               ImputeFun: 'string -or- function handle -or- cell array'
            ColumnLabels: 'Cell array of strings, or an empty cell array'
               RowLabels: 'Cell array of strings, or an empty cell array'
      ColumnLabelsRotate: []
         RowLabelsRotate: []
                Annotate: '[on | {off}]'
          AnnotPrecision: []
              AnnotColor: []
       ColumnLabelsColor: 'A structure array.'
          RowLabelsColor: 'A structure array.'
       LabelsWithMarkers: '[true | false].'
    ColumnLabelsLocation: '[ top | {bottom} ]'
       RowLabelsLocation: '[ {left} | right ]'

Display the data values in the heatmap.

hmo.Annotate = true;
view(hmo)

Use the plot function to display the heatmap in another figure specified by the figure handle fH.

fH = figure;
hA = plot(hmo,fH);

Use the returned axes handle hA to specify the axes properties.

hA.Title.String = 'Inverse of an Upper Hessenberg Matrix';
hA.XTickLabelMode = 'auto';
hA.YTickLabelMode = 'auto';

Add Custom Title and Labels to Heatmap

Load a sample of gene expression data.

load bc_train_filtered

Display a heatmap of the gene expression values for 4918 genes from 78 samples.

hmo = HeatMap(bcTrainData.Log10Ratio);

             Standardize: '[column | row | {none}]'
               Symmetric: '[true | false].'
            DisplayRange: 'Scalar.'
                Colormap: []
               ImputeFun: 'string -or- function handle -or- cell array'
            ColumnLabels: 'Cell array of strings, or an empty cell array'
               RowLabels: 'Cell array of strings, or an empty cell array'
      ColumnLabelsRotate: []
         RowLabelsRotate: []
                Annotate: '[on | {off}]'
          AnnotPrecision: []
              AnnotColor: []
       ColumnLabelsColor: 'A structure array.'
          RowLabelsColor: 'A structure array.'
       LabelsWithMarkers: '[true | false].'
    ColumnLabelsLocation: '[ top | {bottom} ]'
       RowLabelsLocation: '[ {left} | right ]'

Add a title to the heatmap in red.

title = addTitle(hmo,'Gene Expression Data','Color','red');

Change the title font size.

title.FontSize = 12;

Add labels to the x-axis and y-axis.

addXLabel(hmo,'Samples','FontSize',12);
addYLabel(hmo,'Genes','FontSize',12);

More About

Color Options

The following lists the predefined colors and their RGB triplet equivalents. The short names and long names are character vectors that specify one of eight preset colors. The RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color; the intensities must be in the range [0 1].

RGB Triplet	Short Name	Long Name
[1 1 0]	y	yellow
[1 0 1]	m	magenta
[0 1 1]	c	cyan
[1 0 0]	r	red
[0 1 0]	g	green
[0 0 1]	b	blue
[1 1 1]	w	white
[0 0 0]	k	black