HeatmapChart Properties

Chart title, specified as a character vector, cell array of character vectors, string array, or categorical array.

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

Example: h.Title = 'My Title Text';

To create a multiline title, specify a cell array of character vectors or a string array. Each element in the array corresponds to a line of text.

Example: h.Title = {'My','Title'};

If you specify the title as a categorical array, MATLAB^® uses the values in the array, not the categories.

If you create the chart using tabular data, the default chart has an autogenerated title. If you do not want a title, specify ''.

By default, heatmaps support a subset of TeX markup for the text you specify. Use TeX markup to add superscripts and subscripts, modify the font type and color, and include special characters in the text. If you want a TeX markup character in regular text, such as an underscore (_), then insert a backslash (\) before the character you want to include. The backslash is the TeX escape character. For more information, see the Interpreter property of the text object.

Label for the x-axis, specified as a character vector, cell array of character vectors, string array, or categorical array.

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

Example: h.XLabel = 'My Label';

To create a multiline label, specify a cell array of character vectors or a string array. Each element in the array corresponds to a line of text.

Example: h.XLabel = {'My','Label'};

If you specify the label as a categorical array, MATLAB uses the values in the array, not the categories.

If you create the chart using tabular data, the default chart has an autogenerated label. If you do not want a label, specify ''.

By default, heatmaps support a subset of TeX markup for the text you specify. Use TeX markup to add superscripts and subscripts, modify the font type and color, and include special characters in the text. If you want a TeX markup character in regular text, such as an underscore (_), then insert a backslash (\) before the character you want to include. The backslash is the TeX escape character. For more information, see the Interpreter property of the text object.

Label for the y-axis, specified as a character vector, cell array of character vectors, string array, or categorical array.

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

Example: h.YLabel = 'My Label';

To create a multiline label, specify a cell array of character vectors or a string array. Each element in the array corresponds to a line of text.

Example: h.YLabel = {'My','Label'};

If you specify the label as a categorical array, MATLAB uses the values in the array, not the categories.

If you create the chart using tabular data, the default chart has an autogenerated label. If you do not want a label, specify ''.

By default, heatmaps support a subset of TeX markup for the text you specify. Use TeX markup to add superscripts and subscripts, modify the font type and color, and include special characters in the text. If you want a TeX markup character in regular text, such as an underscore (_), then insert a backslash (\) before the character you want to include. The backslash is the TeX escape character. For more information, see the Interpreter property of the text object.

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 ''.

By default, heatmaps support a subset of TeX markup for the text you specify. Use TeX markup to add superscripts and subscripts, modify the font type and color, and include special characters in the text. If you want a TeX markup character in regular text, such as an underscore (_), then insert a backslash (\) before the character you want to include. The backslash is the TeX escape character. For more information, see the Interpreter property of the text object.

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

Example: h.MissingDataLabel = 'No data'

Since R2023b

Text interpreter, specified as one of these values:

The heatmap function uses the interpreter when displaying the chart title, axis labels, or any data that includes text or symbols.

TeX Markup

By default, MATLAB supports a subset of TeX markup. Use TeX markup to add superscripts and subscripts, modify the font type and color, and include special characters in the text.

Modifiers remain in effect until the end of the text. Superscripts and subscripts are an exception because they modify only the next character or the characters within the curly braces. When you set the interpreter to 'tex', the supported modifiers are as follows.

This table lists the supported special characters for the 'tex' interpreter.

LaTeX Markup

To use LaTeX markup, set the interpreter to 'latex'. For inline mode, surround the markup with single dollar signs ($). For display mode, surround the markup with double dollar signs ($$).

'$\int_1^{20} x^2 dx$'

'$$\int_1^{20} x^2 dx$$'

The displayed text uses the default LaTeX font style. To change the font style, use LaTeX markup.

The maximum size of the text that you can use with the LaTeX interpreter is 1200 characters. For multiline text, this reduces by about 10 characters per line.

For examples that use TeX and LaTeX, see Greek Letters and Special Characters in Chart Text. For more information about the LaTeX system, see The LaTeX Project website at https://www.latex-project.org/.

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.

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

Example: h.Colormap = parula

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

If you do not want to use a third variable from the table for the color data, then specify the method as 'count'. When the method is 'count', the heatmap does not use the ColorVariable property and instead counts the number of times each pair of x and y values appears in the source table. 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.

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:

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.

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

Example: h.ColorLimits = [0 10]

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

RGB triplets and hexadecimal color codes are useful for specifying custom colors.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

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

Example: h.MissingDataColor = [0.8 0.8 0.8]

Display the colorbar, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

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

Example: h.ColorbarVisible = 'off'

Display grid lines, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

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

Example: h.GridVisible = 'off'

Text color for data labels, specified as 'auto', an RGB triplet, a hexadecimal color code, a color name, or a short name. The default value of 'auto' chooses an appropriate text color, depending on the color of each heatmap cell. If you do not want the labels to display, specify 'none'.

RGB triplets and hexadecimal color codes are useful for specifying custom colors.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

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:

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.

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'

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'

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

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.

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

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.

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

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

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.

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

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

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.

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

Example: h.ColorVariable = 'Temperature'

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

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 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. Use the XDisplayLabels property to change the displayed text.

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 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. Use the YDisplayLabels property to change the displayed text.

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, string array, or categorical 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. When you specify this property as a categorical array, MATLAB uses the values in the array, not the categories.

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.

By default, heatmaps support a subset of TeX markup for the text you specify. Use TeX markup to add superscripts and subscripts, modify the font type and color, and include special characters in the text. If you want a TeX markup character in regular text, such as an underscore (_), then insert a backslash (\) before the character you want to include. The backslash is the TeX escape character. For more information, see the Interpreter property of the text object.

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, string array, or categorical 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. When you specify this property as a categorical array, MATLAB uses the values in the array, not the categories.

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.

By default, heatmaps support a subset of TeX markup for the text you specify. Use TeX markup to add superscripts and subscripts, modify the font type and color, and include special characters in the text. If you want a TeX markup character in regular text, such as an underscore (_), then insert a backslash (\) before the character you want to include. The backslash is the TeX escape character. For more information, see the Interpreter property of the text object.

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

Position property to hold constant when adding, removing, or changing decorations, specified as one of the following values:

Outer size and location 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 default value of [0 0 1 1] covers the whole interior of the container. The units are normalized relative to the size of the container. To change the units, set the Units property.

Inner size and location 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.

Inner size and location 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.

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.

Layout options, specified as a TiledChartLayoutOptions or GridLayoutOptions object. This property is useful when the chart is either in a tiled chart layout or a grid layout.

To position the chart within the grid of a tiled chart layout, set the Tile and TileSpan properties on the TiledChartLayoutOptions object. For example, consider a 3-by-3 tiled chart layout. The layout has a grid of tiles in the center, and four tiles along the outer edges. In practice, the grid is invisible and the outer tiles do not take up space until you populate them with axes or charts.

This code places the chart c in the third tile of the grid.

c.Layout.Tile = 3;

To make the chart span multiple tiles, specify the TileSpan property as a two-element vector. For example, this chart spans 2 rows and 3 columns of tiles.

c.Layout.TileSpan = [2 3];

To place the chart in one of the surrounding tiles, specify the Tile property as "north", "south", "east", or "west". For example, setting the value to "east" places the chart in the tile to the right of the grid.

c.Layout.Tile = "east";

To place the chart into a layout within an app, specify this property as a GridLayoutOptions object. For more information about working with grid layouts in apps, see uigridlayout.

If the chart is not a child of either a tiled chart layout or a grid layout (for example, if it is a child of a figure or panel) then this property is empty and has no effect.

State of visibility, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

Parent container, specified as a Figure, Panel, Tab, TiledChartLayout, or GridLayout object.

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

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.