BubbleCloud Properties

Bubble cloud appearance and behavior

Since R2021a

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

b = bubblecloud(1:100);
b.Title = 'My Bubble Cloud';

Title

Title — Chart title

character vector | cell array of character vectors | string array | categorical array

Chart title, specified as a character vector, cell array of character vectors, string array, or categorical array. To create a mutliline title, specify a cell array of character vectors or a string array. Each element in the array is a separate line of text.

Alternatively, you can call the title function to add a title to the chart.

bubblecloud(rand(1,20))
title("Random Bubbles")

LegendTitle — Legend title

character vector | cell array of character vectors | string array | categorical array

Legend title, specified as a character vector, cell array of character vectors, string array, or categorical array. To create a mutliline title, specify a cell array of character vectors or a string array. Each element in the array is a separate line of text.

If you specify your data in a table, then the default legend title is the name of the variable that specifies the groups.

Color and Styling

FaceColor — Bubble fill color

'flat' (default) | RGB triplet | hexadecimal color code | color name | short name | 'none'

Bubble fill color, specified as a value from this table.

FaceColor Value	Description
'flat'	Let MATLAB® assign a different color to each group of bubbles. The colors are defined in the ColorOrder property of the chart.
RGB triplet or hexadecimal color code	Assign one custom color to all the groups of bubbles: RGB triplet — 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]. Hexadecimal color code — A character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes '#FF8800', '#ff8800', '#F80', and '#f80' are equivalent. The two tables below provide the RGB triplets and hexadecimal color codes for some common colors.
Color name or short name	Assign one predefined color to all the groups of bubbles using a color name such as 'red', or a short name such as 'r'. The table below lists the available color names and short names.
'none'	Display all groups of bubbles without any color.

This table lists the available color names and short names with corresponding RGB triplets and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

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

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	"#0072BD"
[0.8500 0.3250 0.0980]	"#D95319"
[0.9290 0.6940 0.1250]	"#EDB120"
[0.4940 0.1840 0.5560]	"#7E2F8E"
[0.4660 0.6740 0.1880]	"#77AC30"
[0.3010 0.7450 0.9330]	"#4DBEEE"
[0.6350 0.0780 0.1840]	"#A2142F"

EdgeColor — Bubble edge color

[0 0 0] (default) | 'flat' | RGB triplet | hexadecimal color code | color name | short name | 'none'

Bubble edge color, specified as a value from this table.

EdgeColor Value	Description
'flat'	Let MATLAB assign a different edge color to each group of bubbles. The colors are defined in the ColorOrder property of the chart.
RGB triplet or hexadecimal color code	Assign one custom edge color to all the groups of bubbles: RGB triplet — 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]. Hexadecimal color code — A character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes '#FF8800', '#ff8800', '#F80', and '#f80' are equivalent. The two tables below provide the RGB triplets and hexadecimal color codes for some common colors.
Color name or short name	Assign one predefined edge color to all the groups of bubbles using a color name such as 'red', or a short name such as 'r'. The table below lists the available color names and short names.
'none'	Display all groups of bubbles without any edge color.

This table lists the available color names and short names with corresponding RGB triplets and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

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

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	"#0072BD"
[0.8500 0.3250 0.0980]	"#D95319"
[0.9290 0.6940 0.1250]	"#EDB120"
[0.4940 0.1840 0.5560]	"#7E2F8E"
[0.4660 0.6740 0.1880]	"#77AC30"
[0.3010 0.7450 0.9330]	"#4DBEEE"
[0.6350 0.0780 0.1840]	"#A2142F"

ColorOrder — Color order

seven predefined colors (default) | three-column matrix of RGB triplets

Color order, specified as a three-column matrix of RGB triplets. This property defines the palette of colors MATLAB uses to create multiple bubble clouds when you specify group data. Each row of the array is an RGB triplet. An RGB triplet is a three-element vector whose elements specify the intensities of the red, green, and blue components of a color. The intensities must be in the range [0, 1]. This table lists the default colors.

Colors	ColorOrder Matrix
	[ 0 0.4470 0.7410 0.8500 0.3250 0.0980 0.9290 0.6940 0.1250 0.4940 0.1840 0.5560 0.4660 0.6740 0.1880 0.3010 0.7450 0.9330 0.6350 0.0780 0.1840]

MATLAB assigns colors to each bubble cloud according to the order of the values in the GroupData property.

An alternative way to set this property is to pass the BubbleCloud object to the colororder function.

FaceAlpha — Bubble fill color transparency

0.60 (default) | scalar in range [0,1].

Bubble fill color transparency, specified as a scalar in the range [0,1]. A value of 1 makes the bubbles opaque, and 0 makes them completely transparent. Values between 0 and 1 correspond to partially transparent bubbles.

LegendVisible — Visibility of legend

on/off logical value

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

MATLAB sets this property to 'on' and displays a legend when you create a bubble cloud with grouping data. Otherwise, the value is 'off' and there is no legend.

MaxDisplayBubbles — Maximum number of bubbles

1000 (default) | positive number

Maximum number of bubbles to display, specified as a positive number.

Bubble Labels Font

FontName — Font name

supported font name | "FixedWidth"

Font name, specified as a supported font name or "FixedWidth". To display and print text properly, you must choose a font that your system supports. The default font depends on your operating system and locale.

To use a fixed-width font that looks good in any locale, use "FixedWidth". The fixed-width font relies on the root FixedWidthFontName property. Setting the root FixedWidthFontName property causes an immediate update of the display to use the new font.

FontSize — Font size

scalar value greater than zero

Font size, specified as a scalar value greater than zero in point units. The default font size depends on the specific operating system and locale. One point equals 1/72 inch.

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

FontColor — Font color

RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

Font color, specified as an RGB triplet, a hexadecimal color code, or one of the options listed in the table.

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

• 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].

• A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

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

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

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

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	"#0072BD"
[0.8500 0.3250 0.0980]	"#D95319"
[0.9290 0.6940 0.1250]	"#EDB120"
[0.4940 0.1840 0.5560]	"#7E2F8E"
[0.4660 0.6740 0.1880]	"#77AC30"
[0.3010 0.7450 0.9330]	"#4DBEEE"
[0.6350 0.0780 0.1840]	"#A2142F"

Table Data

SourceTable — Table containing bubble data

table | timetable

Table containing bubble data. The table must have at least one variable that specifies the bubble sizes. The bubble sizes can include nonnegative numeric, NaN, and Inf values. Only bubbles with positive sizes appear in the chart. Zero, NaN, and Inf values are ignored.

The table can optionally include variables containing the following data:

• Bubble labels — Create this variable using a cell array of character vectors or a string vector.

• Grouping data — Create this variable using a cell array of character vectors, string vector, categorical vector, numeric vector, or logical vector.

Grouping data is useful for displaying multiple clouds with different colors. For example, you can display car data grouped by manufacturer.

SizeVariable — Table variable for bubble sizes

variable name | variable index | logical vector

Table variable for the bubble sizes, specified as one of the following values:

• Variable name — Character vector or string scalar with the name of the table variable containing the size data.

• Variable index — Index of the table variable containing the size data. Specify the index as a number between 1 and the number of table variables.

• Logical vector — Vector of logical values that has the same number of elements as there are variables in the table. The vector must contain only one true value.

LabelVariable — Table variable for bubble labels

variable name | variable index | logical vector

Table variable for the bubble labels, specified as one of the following values:

• Variable name — Character vector or string scalar with the name of the table variable containing the labels.

• Variable index — Index of the table variable containing the labels. Specify the index as a number between 1 and the number of table variables.

• Logical vector — Vector of logical values that has the same number of elements as there are variables in the table. The vector must contain only one true value.

GroupVariable — Table variable for bubble groups

variable name | variable index | logical vector

Table variable for the bubble groups, specified as one of the following values:

• Variable name — Character vector or string scalar with the name of the table variable containing the grouping data.

• Variable index — Index of the table variable containing the grouping data. Specify the index as a number between 1 and the number of table variables.

• Logical vector — Vector of logical values that has the same number of elements as there are variables in the table. The vector must contain only one true value.

When you specify a bubble groups, bubblecloud divides your data into separate bubble clouds. Each bubble cloud has a different color, and the colors are determined by the ColorOrder property.

Vector Data

SizeData — Bubble sizes

numeric vector

Bubble sizes, specified as numeric vector containing nonnegative values. Zero, NaN, and Inf values are ignored. For example bubblecloud(1:10) creates ten bubbles with sizes 1 through 10.

When you create a bubble cloud with table data, MATLAB automatically populates this property with the data specified by the SizeVariable property.

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

LabelData — Bubble labels

cell array of character vectors | string vector

Bubble labels, specified as a cell array of character vectors or a string vector. The number of elements in the cell array or string vector must match the number of elements in the SizeData vector. For example bubblecloud(1:3,["one" "two" "three"]) creates three bubbles with the labels "one","two", and "three".

When you create a bubble cloud with a table that includes labels, MATLAB automatically populates this property with the data specified by the LabelVariable property.

Data Types: cell | string

GroupData — Bubble groups

cell array of character vectors | string vector | categorical vector | logical vector

Bubble groups, specified as a cell array of character vectors, string vector, categorical vector, or logical vector. The number of elements must match the number of elements in the SizeData vector. For example bubblecloud(1:3,["one" "two" "three"],["Group1" "Group2" "Group2"]) creates three bubbles that are divided into two groups.

When you specify a bubble groups, bubblecloud divides your data into separate bubble clouds. Each bubble cloud has a different color, and the colors are determined by the ColorOrder property.

When you create a bubble cloud with a table that includes group data, MATLAB automatically populates this property with the data specified by the GroupVariable property.

Data Types: cell | string | categorical | logical

Position

PositionConstraint — Position to hold constant

"outerposition" | "innerposition"

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

• "outerposition" — The OuterPosition property remains constant when you add, remove, or change decorations such as a title or an axis label. If any positional adjustments are needed, MATLAB adjusts the InnerPosition property.

• "innerposition" — The InnerPosition property remains constant when you add, remove, or change decorations such as a title or an axis label. If any positional adjustments are needed, MATLAB adjusts the OuterPosition property.

Note

Setting this property has no effect when the parent container is a TiledChartLayout object.

OuterPosition — Outer size and location

[0 0 1 1] (default) | four-element vector

Outer size and location of the bubble cloud within the parent container (typically a figure, panel, or tiled chart layout), specified as a four-element vector of the form [left bottom width height]. The outer size and location includes the legend and title.

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

• The width and height elements are the bubble cloud dimensions, which include a margin for the surrounding legend and title.

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.

Note

Setting this property has no effect when the parent container is a TiledChartLayout object.

InnerPosition — Inner size and location

four-element vector

Inner size and location of the bubble cloud within the parent container (typically a figure, panel, or tiled chart layout) returned as a four-element vector of the form [left bottom width height]. The inner size and location does not include the legend or title.

• The left and bottom elements define the distance from the lower left corner of the container to the lower left corner of the box that encloses the bubble cloud.

• The width and height elements are the dimensions of the box that encloses the bubble cloud.

Note

Setting this property has no effect when the parent container is a TiledChartLayout object.

Position — Inner size and location

four-element vector

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

Note

Setting this property has no effect when the parent container is a TiledChartLayout object.

Units — Position units

'normalized' (default) | 'inches' | 'centimeters' | 'points' | 'pixels' | 'characters'

Position units, specified as one of these values.

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

Layout — Layout options

empty LayoutOptions array (default) | TiledChartLayoutOptions object | GridLayoutOptions object

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.

Visible — State of visibility

'on' (default) | on/off logical value

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.

• 'on' — Display the bubble cloud.

• 'off' — Hide the bubble cloud without deleting it. You still can access the properties of an invisible BubbleCloud object.

Parent/Child

Parent — Parent container

Figure object | Panel object | Tab object | TiledChartLayout object | GridLayout object

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

Version History

Introduced in R2021a