Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

HeatmapChart Properties

Control heatmap chart appearance and behavior

HeatmapChart properties control the appearance and behavior of a HeatmapChart object. By changing property values, you can modify certain aspects of the heatmap chart. For example, you can add a title:

h = heatmap([1 3 5; 2 4 6]);
h.Title = 'My Heatmap Title';

Tabular Data

expand all

Source table, specified as a table or a timetable.

You can create a table from workspace variables using the table function, or you can import data as a table using the readtable function. You can create a timetable from workspace variables using the timetable function.

Note

The property is ignored and read-only when you use matrix data.

Table variable for x-axis, specified in one of these forms:

  • Character vector or string indicating one of the variable names

  • Numeric scalar indicating the table variable index

  • Logical vector containing one true element

The values associated with your table variable must be grouped into a finite set of discrete categories that the categorical function accepts. If the values are not grouped into a finite set of categories, use the discretize function to group them.

If you set the XVariable property value, then the XData and XDisplayData properties automatically update to appropriate values.

The labels that appear along the x-axis are in alphabetical order. You can customize the labels using XDisplayData, yDisplayData, or categorical arrays. For an example, see Create Heatmap from Tabular Data.

Note

The property is ignored and read-only when you use matrix data.

Example: h.XVariable = 'Location' specifies the variable named 'Location'.

Table variable for y-axis, specified in one of these forms:

  • Character vector or string indicating one of the variable names

  • Numeric scalar indicating the table variable index

  • Logical vector containing one true element

The values associated with your table variable must be grouped into a finite set of discrete categories that the categorical function accepts. If the values are not grouped into a finite set of categories, use the discretize function to group them.

If you set the YVariable property value, then the YData and YDisplayData properties automatically update to appropriate values.

The labels that appear along the y-axis are in alphabetical order. You can customize the labels using categorical arrays. For an example, see Create Heatmap from Tabular Data.

Note

The property is ignored and read-only when you use matrix data.

Example: h.YVariable = 'Location' specifies the variable named 'Location'.

Table variable for color data, specified in one of these forms:

  • Character vector or string indicating one of the variable names.

  • Numeric scalar indicating the table variable index.

  • Logical vector containing one true element.

The values associated with your table variable must be of a numeric type or logical.

When you specify the color variable, MATLAB® updates the ColorData property values. Also, the ColorMethod property changes to 'mean', unless you previously specified a different value.

Note

This property is ignored and read-only when you use matrix data. It is also ignored when the ColorMethod property is set to 'count'.

Example: h = heatmap(__,'ColorVariable','Temperature')

Example: h.ColorVariable = 'Temperature'

Matrix Data

expand all

Data to color each heatmap cell, specified as a matrix of numeric values.

If you are using tabular data, you cannot set this property. The ColorData values automatically populate based on the table variable you select with the ColorVariable property.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

x values associated with the color data matrix columns, specified as a cell array of character vectors, a string array, or a categorical array. The XDisplayData property controls the order in which the values appear along the x-axis in the chart.

If you change the XData property value, then the XDisplayData property automatically updates to appropriate values.

If you are using tabular data, you cannot set this property. The XData values automatically populate based on the table variable you select with the XVariable property.

Example: h.XData = {'small','large','medium'}

Data Types: char | string | cell | categorical

y values associated with the color data matrix rows, specified as a cell array of character vectors, a string array, or a categorical array. The YDisplayData property controls the order in which the values appear along the y-axis in the chart.

If you change the YData property value, then the YDisplayData property automatically updates to appropriate values.

If you are using tabular data, you cannot set this property. The YData values automatically populate based on the table variable you select with the YVariable property.

Example: h.YData = {'small','large','medium'}

Data Types: char | string | cell | categorical

Displayed Data

expand all

This property is read-only.

Sorted color data, returned as a matrix of values as they appear in the heatmap chart. The values are sorted based on the XDisplayData and YDisplayData properties.

Data Types: double

Display order of x-axis values, specified as a cell array of character vectors, a string array, or a categorical array. You can set this property to a subset, superset, or permutation of the values in XData. By default, the values are the same as the XData values.

If you specify a value that is not in XData, then the heatmap shows a row of either NaN values or zeros.

  • If the ColorMethod property is 'sum' or 'count', then the heatmap shows a row of zeros.

  • If the ColorMethod property is 'mean', 'median', or 'none', then the heatmap shows a row of NaN values.

If you want to specify the XDisplayData as a name-value pair during object creation, you must specify the XDisplayData property before specifying the XDisplayLabels or XLimits properties.

Example: h.XDisplayData = {'small','medium','large'}

Data Types: char | string | cell | categorical

Display order of y-axis values, specified as a cell array of character vectors, a string array, or a categorical array. You can set this property to a subset, superset, or permutation of the values in YData. By default, the values are the same as the YData values.

If you specify a value that is not in YData, then the heatmap shows a row of either NaN values or zeros.

  • If the ColorMethod property is 'sum' or 'count', then the heatmap shows a row of zeros.

  • If the ColorMethod property is 'mean', 'median', or 'none', then the heatmap shows a row of NaN values.

If you want to specify YDisplayData as a name-value pair during object creation, you must specify the YDisplayData property before specifying the YDisplayLabels or YLimits properties.

Example: h.YDisplayData = {'small','medium','large'}

Data Types: char | string | cell | categorical

Labels for the x-axis values, specified as a cell array of character vectors or a string array. The array must be a column vector the same size as the XDisplayData vector. Specify one label for each value in XDisplayData. By default, the values are the same as the XDisplayData values.

If you add a value, delete a value, or rearrange the values in the XDisplayData property, then this property updates accordingly to maintain the pairings of values and labels.

If you want to specify both XDisplayLabels and XDisplayData as name-value pairs during object creation, then specify the XDisplayData property first.

Example: h.XDisplayLabels = {'SM','MED','LG'}

Data Types: char | string | cell | categorical

Labels for the y-axis values, specified as a cell array of character vectors or a string array. The array must be a column vector the same size as the YDisplayData vector. Specify one label for each value in YDisplayData. By default, the values are the same as the YDisplayData values.

If you add a value, delete a value, or rearrange the values in the YDisplayData property, then this property updates accordingly to maintain the pairings of values and labels.

If you want to specify both YDisplayLabels and YDisplayData as name-value pairs during object creation, then specify the YDisplayData property first.

Example: h.YDisplayLabels = {'SM','MED','LG'}

Data Types: char | string | cell | categorical

x-axis limits, specified as a two-element row vector of values from XDisplayData.

If you want to specify both XLimits and XDisplayData as name-value pairs during object creation, then specify the XDisplayData property first.

Example: h.XLimits = {'small','medium'}

Data Types: char | string | cell | categorical

y-axis limits, specified as a two-element row vector of values from YDisplayData.

If you want to specify both YLimits and YDisplayData as name-value pairs during object creation, then specify the YDisplayData property first.

Example: h.YLimits = {'small','medium'}

Data Types: char | string | cell | categorical

Color Scaling

expand all

Method to calculate the color data values (stored in ColorData), specified as 'count', 'mean', 'median', 'sum', or 'none'.

If you do not want to use a third variable from the table for the color data, then specify the method in this table.

MethodDescription
'count'Count the number of times each pair of x and y values appears in the source table. The heatmap does not use the ColorVariable property. This value is the default value when you are using tabular data and do not specify the ColorVariable parameter.

If you want to use a third variable from the table for the color data, then set the ColorVariable property to the variable you want and specify the ColorMethod property as one of the methods listed in this table. For each pair of x and y values, the methods use the corresponding values in the ColorVariable column of the source table to calculate the data.

MethodDescription
'mean'Calculate the average value. This value is the default value when you specify the ColorVariable property.
'median'Calculate the median value.
'sum'Sum the values.
'none'Use the value exactly. The table cannot contain more than one instance of each pair of x and y values. This value is the default value when using matrix data.

If you want to compute your own matrix of aggregated data, use the accumarray function. Specify the matrix as input to the heatmap function.

Example: h = heatmap(__,'ColorMethod','median')

Example: h.ColorMethod = 'median'

Mapping of color data to colormap colors, specified as one of these values:

  • 'scaled' — Map values in the ColorData property that are less than or equal to the minimum color limit to the first color in the colormap. Map values greater than or equal to the maximum color limit to the last color. The ColorLimits property contains the color limit values.

  • 'scaledcolumns' — Normalize each column in the ColorData property to values from 0 through 1. Map the smallest value to the first color in the colormap and the largest value to the last color. If all the values in a column are the same, then the heatmap uses the middle color of the colormap.

  • 'scaledrows' — Normalize each row in the ColorData property to values from 0 to 1. Map the smallest value to the first color in the colormap and the largest value to the last color. If all the values in a row are the same, then the heatmap uses the middle color of the colormap.

  • 'log' — Calculate the log of each value in the ColorData property before mapping the values to colors in the colormap. Negative values appear as missing data. However, if all the values are negative, then this option uses -log(-value).

The heatmap ignores NaN, Inf, and -Inf values when determining the color scaling.

When ColorScaling is set to 'scaledcolumns' or 'scaledrows', the default tick labels on the colorbar range from 0 to 1. The smallest value within a column or row of the heatmap chart maps to 0 on the colorbar. The largest value within a column or row maps to 1 on the colorbar.

Example: h = heatmap(__,'ColorScaling','scaledcolumns')

Example: h.ColorScaling = 'scaledcolumns'

Color limits, specified as a two-element vector of the form [min max]. The color limits indicate the color data values that map to the first and last colors in the colormap.

Note

The default values of min and max reflect the range of your data after the ColorScaling option is applied.

Example: h = heatmap(__,'ColorLimits',[0 10])

Example: h.ColorLimits = [0 10]

Colormap for coloring heatmap cells, specified as a predefined colormap name or an m-by-3 array of RGB (red, green, blue) triplets that define m individual colors. You can specify one of the predefined colormaps, or you can create a custom one.

  • Predefined colormaps — Specify the colormap name in command form, such as parula or summer. For a full list of options, see colormap.

  • Custom colormap — Specify an m-by-3 array of RGB triplets.

Example: h = heatmap(__,'Colormap',summer)

Example: h.Colormap = parula

Color for cells with no data value, specified as a color name or an RGB triplet.

An 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]; for example, [0.4 0.6 0.7]. Alternatively, you can specify some common colors by name. This table lists the long and short color name options and the equivalent RGB triplet values.

OptionDescriptionEquivalent RGB Triplet
'red' or 'r'Red[1 0 0]
'green' or 'g'Green[0 1 0]
'blue' or 'b'Blue[0 0 1]
'yellow' or 'y'Yellow[1 1 0]
'magenta' or 'm'Magenta[1 0 1]
'cyan' or 'c'Cyan[0 1 1]
'white' or 'w'White[1 1 1]
'black' or 'k'Black[0 0 0]

Example: h = heatmap(__,'MissingDataColor',[0.8 0.8 0.8])

Example: h.MissingDataColor = [0.8 0.8 0.8]

Label for missing data icon that displays below the colorbar, specified as a character vector. If you do not want a label to display, use an empty character vector ''.

Example: h = heatmap(__,'MissingDataLabel','No data')

Example: h.MissingDataLabel = 'No data'

Display of colorbar, specified as 'on' or 'off'.

Example: h = heatmap(__,'ColorbarVisible','off')

Example: h.ColorbarVisible = 'off'

Display of grid lines, specified as 'on' or 'off'.

Example: h = heatmap(__,'GridVisible','off')

Example: h.GridVisible = 'off'

Text and Font Style

expand all

Chart title, specified as a string, character vector, or '' for no title. For tabular data, the default chart has an autogenerated title.

Example: h = heatmap(__,'Title','My Title Text')

Example: h.Title = 'My Title Text'

Label for the x-axis, specified as a string, character vector, or '' for no label. For tabular data, the default chart has an autogenerated label.

Example: h = heatmap(__,'XLabel','My Label')

Example: h.XLabel = 'My Label'

Label for the y-axis, specified as a string, character vector, or '' for no label. For tabular data, the default chart has an autogenerated label.

Example: h = heatmap(__,'YLabel','My Label')

Example: h.YLabel = 'My Label'

Text color for data labels, specified as 'auto', a color name, an RGB triplet, or 'none'. The default value of 'auto' chooses an appropriate text color, depending on the color of each heatmap cell.

To customize the color, specify one of the predefined long or short color names listed in the table or specify an RGB triplet. If you do not want the labels to display, specify 'none'.

An 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]; for example, [0.4 0.6 0.7]. Alternatively, you can specify some common colors by name. This table lists the long and short color name options and the equivalent RGB triplet values.

OptionDescriptionEquivalent RGB Triplet
'red' or 'r'Red[1 0 0]
'green' or 'g'Green[0 1 0]
'blue' or 'b'Blue[0 0 1]
'yellow' or 'y'Yellow[1 1 0]
'magenta' or 'm'Magenta[1 0 1]
'cyan' or 'c'Cyan[0 1 1]
'white' or 'w'White[1 1 1]
'black' or 'k'Black[0 0 0]

Example: h = heatmap(__,'CellLabelColor','blue')

Example: h.CellLabelColor = 'blue'

Format for data labels, specified as a character vector of format options.

Most elements of the character vector are optional, except the percent sign and conversion character. Construct the character vector in this order:

  • One or more flags — Options. For example, add a plus sign before positive values. For a full list of options, see the table of Optional Flags.

  • Field width — Minimum number of characters to print in the tick label. Specify the field width as an integer value. If the number of significant digits in the tick value is smaller than the field width, then the label is padded with spaces.

  • Precision — Number of digits to the right of the decimal point or the number of significant digits, depending on the conversion character. Specify the precision as an integer value.

  • Conversion character — Value type. For a full list of options, see the table of Conversion Characters. If you specify a conversion that does not fit the data, then MATLAB overrides the specified conversion, and uses %e.

Also, you can specify literal text at the beginning or end of the format. To print a single quotation mark, use ''. To print a percent character, use %%.

Example: h.CellLabelFormat = '%.2f' displays the values using fixed-point notation with two decimal places.

Example: h.CellLabelFormat ='$%.2f' displays a dollar sign before each value.

Example: h.CellLabelFormat = '%.2f lbs' displays lbs after each value.

Optional Flags

IdentifierDescriptionExample of Numeric Format
,Display commas every three digits, such as '1,000'.'%,4.4g'
+Print the sign character (+) for positive values, such as '+100'.'%+4.4g'
0Pad the field width with leading zeros instead of spaces, such as '0100'.'%04.4g'
Left justify, which pads the end of the value with spaces instead of the beginning. For example, if the field width is 4, then this flag formats the label as '100 ' instead of ' 100'.'%-4.4g'
#

For the %f, %e, and %g conversion characters, print the decimal point even when the precision is 0, such as '100.'. For %g, do not remove trailing zeros.

'%#4.4g'

Conversion Characters

IdentifierDescriptionExample
d or iSigned integer with base 10. The precision value indicates the number of significant digits. '%.4d' displays π as 0003.
fFixed-point notation. The precision value indicates the number of decimal places.'%.4f' displays π as 3.1416.
eExponential notation. The precision value indicates the number of decimal places.'%.4e' displays π as 3.1416x100.
gThe more compact version of e or f, with no trailing zeros. The precision value indicates the maximum number of decimal places.'%.4g' displays π as 3.1416.

Font size used for the title, axis labels, and cell labels, specified as a scalar value. The default font depends on the specific operating system and locale.

The title and axis labels use a slightly larger font size (scaled up by 10%). If there is not enough room to display the text within each cell, then the text might use a smaller font size or the text might not appear.

Example: h = heatmap(__,'FontSize',12)

Example: h.FontSize = 12

Font name, specified as a system supported font name. The default font depends on the specific operating system and locale.

Example: h = heatmap(__,'FontName','Cambria')

Example: h.FontName = 'Cambria'

Text color for title, axis labels, and tick labels, specified as a color name or an RGB triplet.

Example: h = heatmap(__,'FontColor','blue')

Example: h.FontColor = 'blue'

Size and Position

expand all

Position property to hold constant during resize operations, specified as 'outerposition' or 'innerposition'. The default value of 'outerposition' means that the OuterPosition property remains constant. The InnerPosition property value can change when the parent container changes size, the data changes, or the labels change. The InnerPosition property value also can change when you display or remove the colorbar.

Example: h.ActivePositionProperty = 'outerposition'

Outer size and position of the heatmap within the parent container (typically a figure, panel, or tab), specified as a four-element vector of the form [left bottom width height]. The outer position includes the colorbar, title, and axis labels.

  • The left and bottom elements define the distance from the lower left corner of the container to the lower left corner of the heatmap.

  • The width and height elements are the heatmap dimensions, which include the heatmap cells, plus a margin for the surrounding text and colorbar.

The default value of [0 0 1 1] is the whole interior of the container.

By default, the values are normalized to the container. To change the units, set the Units property.

Inner size and position of the heatmap within the parent container (typically a figure, panel, or tab) returned as a four-element vector of the form [left bottom width height]. The inner position does not include the colorbar, title, or axis labels.

  • The left and bottom elements define the distance from the lower left corner of the container to the lower left corner of the heatmap.

  • The width and height elements are the heatmap dimensions, which include only the heatmap cells.

Inner size and position of the heatmap within the parent container (typically a figure, panel, or tab) returned as a four-element vector of the form [left bottom width height]. This property is equivalent to the InnerPosition property.

Position units, specified as one of these values.

UnitsDescription
'normalized' (default)Normalized with respect to the container, which is typically the figure or a panel. The lower left corner of the container maps to (0,0), and the upper right corner maps to (1,1).
'inches'Inches.
'centimeters'Centimeters.
'characters'Based on the default uicontrol font of the graphics root object:
  • Character width = width of letter x.

  • Character height = distance between the baselines of two lines of text.

'points'Typography points. One point equals 1/72 inch.
'pixels'

Pixels.

Starting in R2015b, distances in pixels are independent of your system resolution on Windows® and Macintosh systems:

  • On Windows systems, a pixel is 1/96th of an inch.

  • On Macintosh systems, a pixel is 1/72nd of an inch.

On Linux® systems, the size of a pixel is determined by your system resolution.

When specifying the units as a name-value pair during object creation, you must set the Units property before specifying the properties that you want to use these units, such as OuterPosition.

State of visibility, specified as one of these values:

  • 'on' — Display the heatmap.

  • 'off' — Hide the heatmap without deleting it. You still can access the properties of an invisible HeatmapChart object.

Parent and Identifiers

expand all

Parent container, specified as a figure, panel, or tab object.

Visibility of HeatmapChart object handle in the Children property of the parent, specified as one of these values:

  • 'on' — Object handle is always visible.

  • 'off' — Object handle is invisible at all times. This option is useful for preventing unintended changes to the UI by another function. To temporarily hide the handle during the execution of that function, set the HandleVisibility to 'off'.

  • 'callback' — Object handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This option blocks access to the object at the command-line, but allows callback functions to access it.

If the object is not listed in the Children property of the parent, then functions that obtain object handles by searching the object hierarchy or querying handle properties cannot return it. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close.

Hidden object handles are still valid. Set the root ShowHiddenHandles property to 'on' to list all object handles, regardless of their HandleVisibility property setting.

Introduced in R2017a

Was this topic helpful?