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
h.Title = 'My Heatmap Title';

Tabular Data Options

expand all

Source table, specified as a table.

You can create a table from variables in your workspace using the table function, or you can import a file as a table using the readtable.

    Note:   The property is ignored when using 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.

The labels that appear along the x-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 when using 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.

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 when using 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 when using matrix data or when the ColorMethod property is set to 'count'.

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

Example: h.ColorVariable = 'Temperature'

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. This option does not use the ColorVariable property and is the default value when you 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.

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

    Note:   This property is ignored when using matrix data. The value appears as 'none'.

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

Example: h.ColorMethod = 'median'

Color

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

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 between 0 and 1. Map the smallest value to the first color in the colormap and the largest value to the last color.

  • 'scaledrows' — Normalize each row in the ColorData property to values between 0 and 1. Map the smallest value to the first color in the colormap and the largest value to the last color.

  • '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 of the values are negative, then this option uses -log(-value).

    Note:   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

Title and Labels

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]. This table lists the long and short color name options and the equivalent RGB triplet values.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black''k'[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.

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]. This table lists the long and short color name options and the equivalent RGB triplet values.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black''k'[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'

Appearance

expand all

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'

Font size used for the title, axis labels, and cell labels, specified as a scalar value. 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.

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 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 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] includes the whole interior of the container.

By default, the values are normalized to the container. To change the units, set the Units 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.

Was this topic helpful?