GeographicBubbleChart Properties

Control geographic bubble chart appearance and behavior

GeographicBubbleChart properties control the appearance and behavior of a GeographicBubbleChart object. By changing property values, you can modify aspects of the chart display. Use dot notation to refer to a particular object and property. The following example specifies the name of the size legend by using the SizeLegendTitle property.

tsunamis = readtable('tsunamis.xlsx');
tsunamis.Cause = categorical(tsunamis.Cause);
figure
gb = geobubble(tsunamis,'Latitude','Longitude', ...
        'SizeVariable','MaxHeight','ColorVariable','Cause', ...
        'Basemap','colorterrain')
geolimits([10 65],[-180 -80])
title 'Tsunamis in North America';
gb.SizeLegendTitle = 'Maximum Height';

Bubble Location

LatitudeData — Latitude coordinates of bubble locations

real, finite, numeric vector | []

Latitude coordinates of bubble locations, specified as a real, finite, numeric vector of values in the range [-90,90], or as an empty ([]) array. LatitudeData must be the same size as LongitudeData and can contain NaNs.

Bubbles with latitudes outside the approximate limits [-85 85], beyond which the basemap tiles do not extend, are permissible. However these values are not typically seen unless the map extent is controlled manually using the MapCenter and ZoomLevel properties. Also, bubbles very close to 90 degrees and -90 degrees can never be seen, because they map to infinite or near-infinite y-values.

Data Types: single | double

LatitudeVariable — Table variable used for bubble latitude

character vector | string scalar | numeric scalar | logical vector

Table variable used for bubble latitude, specified in one of these forms:

• A string scalar or character vector specifying the name of the table variable you want to use for latitude. For example, geobubble(__,'LatitudeVariable','Latitude') specifies the variable named 'Latitude'.

• A numeric scalar indicating the table variable index. For example, geobubble(__,'LatitudeVariable',1) specifies the first variable in the table for latitudes.

• A logical vector containing one true element.

The values associated with this table variable must be numeric. You can use this property only when specifying a table as input. geobubble stores the value of this variable in the 'LatitudeData' property and sets the 'LatitudeData' property to read-only.

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

LongitudeData — Longitude coordinates of bubble locations

real, finite numeric vector | []

Longitude coordinates of bubble locations, specified as a real, finite, numeric vector of values in the range (-Inf,Inf), or as an empty ([]) array. LongitudeData must be the same size as LatitudeData and can contain NaNs.

Data Types: single | double

LongitudeVariable — Table variable used for bubble longitude

character vector | string scalar | numeric scalar | logical vector

Table variable used for bubble longitude, specified in one of these forms:

• A string or character vector specifying the name of the table variable you want to use for longitude information. For example, geobubble(__,'LongitudeVariable','Longitude') specifies the table variable named 'Longitude'.

• A numeric scalar indicating the table variable index. For example, geobubble(__,'LongitudeVariable',16) specifies the sixteenth variable in the table for longitudes.

• A logical vector containing one true element.

The values associated with this table variable must be numeric. You can use this property only when specifying a table as input. geobubble stores the value of this variable in the 'LongitudeData' property and sets the 'LongitudeData' property to read-only.

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

Bubble Size

BubbleWidthRange — Minimum and maximum width of bubbles

[5 20] (default) | numeric scalar | 1-by-2 numeric vector

Minimum and maximum width of bubbles, measured in points, specified as a numeric scalar or a 1-by-2 numeric vector. Values must be non-descending. Use a scalar when you want all the bubbles to have the same (uniform) size. Values must fall within the range [1 100].

Example: [4 10]

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

SizeData — Data controlling bubble size

numeric vector | numeric scalar | []

Data controlling bubble size, specified as a numeric vector or scalar in the range (-Inf,Inf), or as an empty ([]) array. If you specify a vector, SizeData must be the same size as LatitudeData and LongitudeData. If you specify a scalar value, the geographic bubble chart treats the value with scalar expansion. sizedata can contain NaNs.

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

SizeLimits — Limits for mapping SizeData values to bubble width

1-by-2 vector of real, finite values

Limits for mapping SizeData values to bubble width, specified as a 1-by-2 vector of real, finite, numeric values, or as an empty ([]) matrix. Values must be non-descending. To create bubbles that are all the same size, specify the same value for each element.

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

SizeVariable — Table variable used to determine bubble size

character vector | string scalar | numeric scalar | logical vector

Table variable used to determine bubble size, specified in one of these forms:

• A string scalar or character vector specifying the name of the table variable you want to use for size information. For example, geobubble(__,'SizeVariable','MaxHeight') specifies the variable named 'MaxHeight'.

• A numeric scalar indicating the table variable index. For example, geobubble(__,'SizeVariable',16) specifies the sixteenth variable in the table.

• A logical vector containing one true element. For example, sizevar = logical([0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1]) specifies the 16th variable in the table.

This property can only be used when specifying a table as input. The values associated with this table variable must be of a numeric type. When you specify this variable, geobubble stores the data values associated with this variable in the 'SizeData' property and sets the property to read-only.

Bubble Color

BubbleColorList — Colors used to display bubbles and color code by category

MATLAB color specification | cell array of strings | string vector of colors | m-by-3 RGB color matrix

The BubbleColorList property controls the colors used for the bubbles. The value is an m-by-3 array where each row is an RGB color triplet, where m equals the number categories in the ColorData vector, or the number of categories plus 1 if any elements of ColorData are undefined, or 1 if ColorData is empty. By default, geobubble selects colors from an ordered list of 7 standard colors. If m is greater than 7, the colors repeat cyclically. To change the colors used, use one of the MATLAB colormap functions, such as parula or jet, or specify a custom list of your own RGB values.

Data Types: cell | double

ColorData — Data controlling bubble color

categorical vector | []

Data controlling bubble color, specified as a categorical vector or as empty array ([]). Bubbles assigned to the same category have the same color on the map. The geographic bubble chart assigns a color to each category, using the colors listed in the BubbleColorList property. The size of ColorData must match LatitudeData and LongitudeData, except when you specify an empty array.

If you use a color legend, the geographic bubble chart displays the category values in the legend. If any of the values contain TeX markup characters, such as an underscore (_), you might see unexpected formatting in your color legend. MATLAB® uses a subset of TeX markup for the text displayed in legends. To use a TeX markup character in regular text, edit the name of the category (using renamecats) and insert the TeX escape character, the backslash (\), before the character you want to include. For information about using TeX markup to add superscripts and subscripts, modify font type and color, and include special characters in the text, see the Interpreter property of the text object.

Data Types: categorical

ColorVariable — Table variable used to determine bubble color

character vector | string scalar | numeric scalar | logical vector

Table variable used to determine bubble color, specified in one of these forms:

• A string scalar or character vector specifying the name of the table variable you want to use for color information. For example, geobubble(__,'ColorVariable','Cause') specifies the variable named 'Cause'.

• A numeric scalar indicating the table variable index. For example, geobubble(__,'ColorVariable',12) specifies the 12th variable in the table.

• A logical vector containing one true element. For example, sizevar = logical([0 0 0 0 0 0 0 0 0 0 0 1]) specifies the 12th variable in the table.

You can use this property only when specifying a table as input. The values associated with this table variable must be categorical. When you specify the color variable, geobubble stores the data values associated with this variable in the ColorData property and sets the ColorData property to read-only.

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

Labels

Title — Title of geographic bubble chart

'' (default) | character array | cell array of character vectors | string scalar | string array | numeric value | categorical

Title of geographic bubble chart, specified as a character vector, cell array of character vectors, scalar string, string array, numeric value, or a categorical value. If you specify this property as a categorical array, MATLAB uses the values in the array, not the categories. You can also use the title function to set this value.

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

ColorLegendTitle — Text to display as title of color legend

'' (default) | character vector | string scalar | string array | cell array of character vectors | numeric value | categorical

Text to display as title of color legend, specified as a character vector, string scalar, string array, cell array of character vectors, numeric value, or categorical value. If you specify this property as a categorical array, MATLAB uses the values in the array, not the categories.

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

Data Types: char | cell | string | single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

SizeLegendTitle — Size legend title

'' (default) | character vector | string scalar | string array | cell array of character vectors | numeric value | categorical

Size legend title, specified as a character vector, string scalar, string array, cell array of character vectors, numeric value, or categorical value. If you specify this property as a categorical array, MATLAB uses the values in the array, not the categories.

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

LegendVisible — Visibility of bubble size and color legends

'on' (default) | 'off' | true | false

Visibility of bubble size and color legends, specified as 'on' or 'off' or the logical values true or false. You can also toggle the visibility of the legends by using the legend function.

Data Types: char | string | logical

Font

FontName — Font used in the geographic bubble chart

character vector | string scalar | 'FixedWidth'

Font used in the geographic bubble chart, specified as a string scalar or character vector. To display and print properly, the font name must be a font that your system supports. The default font depends on the specific operating system and locale. To use a fixed-width font that looks good in any locale, use 'FixedWidth'. The 'FixedWidth' value relies on the root FixedWidthFontName property. Setting the root FixedWidthFontName property causes an immediate update of the display to use the new font.

Example: 'Cambria'

Data Types: char | string

FontSize — Font size used in geographic bubble chart

system dependent (default) | real, finite, positive, numeric scalar

Font size used in geographic bubble chart, specified as a real, finite, positive, numeric scalar. The value is in point units, where one point equals 1/72 inches.

Map

Basemap — Map on which to plot data

'streets-light' (default) | 'streets-dark' | 'streets' | 'satellite' | 'topographic' | ...

Map on which to plot data, specified as one of the values listed in the table. Six of the basemaps are tiled data sets created using Natural Earth. Five of the basemaps are high-zoom-level maps hosted by Esri^®.

	'streets-light' (default) Map designed to provide geographic context while highlighting user data on a light background. Hosted by Esri.		'streets-dark' Map designed to provide geographic context while highlighting user data on a dark background. Hosted by Esri.
	'streets' General-purpose road map that emphasizes accurate, legible styling of roads and transit networks. Hosted by Esri.		'satellite' Full global basemap composed of high-resolution satellite imagery. Hosted by Esri.
	'topographic' General-purpose map with styling to depict topographic features. Hosted by Esri.		'landcover' Map that combines satellite-derived land cover data, shaded relief, and ocean-bottom relief. The light, natural palette is suitable for thematic and reference maps. Created using Natural Earth.
	'colorterrain' Shaded relief map blended with a land cover palette. Humid lowlands are green and arid lowlands are brown. Created using Natural Earth.		'grayterrain' Terrain map in shades of gray. Shaded relief emphasizes both high mountains and micro-terrain found in lowlands. Created using Natural Earth.
	'bluegreen' Two-tone, land-ocean map with light green land areas and light blue water areas. Created using Natural Earth.		'grayland' Two-tone, land-ocean map with gray land areas and white water areas. Created using Natural Earth.
	'darkwater' Two-tone, land-ocean map with light gray land areas and dark gray water areas. This basemap is installed with MATLAB®. Created using Natural Earth.		'none' Blank background that plots your data with a latitude-longitude grid, ticks, and labels.

All basemaps except 'darkwater' require Internet access. The 'darkwater' basemap is included with MATLAB.

If you do not have consistent access to the Internet, you can download the basemaps created using Natural Earth onto your local system by using the Add-On Explorer. The five high-zoom-level maps are not available for download. For more about downloading basemaps and changing the default basemap on your local system, see Access Basemaps for Geographic Axes and Charts.

The basemaps hosted by Esri update periodically. As a result, you might see differences in your visualizations over time.

Alignment of boundaries and region labels are a presentation of the feature provided by the data vendors and do not imply endorsement by MathWorks^®.

Example: gb = geobubble(1:10,1:10,'Basemap','bluegreen')

Example: gb.Basemap = 'bluegreen'

Data Types: char | string

SourceTable — Table containing data to be plotted

table

Table containing data to be plotted, specified as a table.

Data Types: table

GridVisible — Visibility of the latitude and longitude lines on the map

'on' (default) | 'off' | true | false

Visibility of the latitude and longitude lines on the map, specified as 'on' or 'off', or the logical values true or false. You can also use the grid function to toggle grid visibility.

Data Types: logical | char | string

LatitudeLimits — Latitude limits of map

1-by-2 vector of real, finite values

This property is read-only.

Latitude limits of map, specified as a 1-by-2 vector of real, finite values of the form [southern_limit northern_limit] in the range [-90,90]. To set latitude limits use the geolimits function.

Data Types: double

LongitudeLimits — Longitude limits of map

1-by-2 vector of real, finite values

This property is read-only.

Longitude limits of map, specified as a 1-by-2 vector of real, finite values of the form [western_limit eastern_limit]. Values must be in the range (-Inf, Inf). To set longitude limits use the geolimits function.

Example: [-100 100]

Data Types: double

MapCenter — Center point of map in latitude and longitude

two-element numeric vector of real, finite values

Center point of map in latitude and longitude, specified as a two-element vector of real, finite values of the form [center_latitude center_longitude]. Values must be in the range [(-90,90),(-Inf, Inf)].

Example: [38.6292 -95.2520]

Data Types: single | double

MapLayout — Layout of map

'normal' (default) | 'maximized'

Layout of map, including insets and decorations, specified as either of the following.

Value	Description	Illustration
'normal'	Map is inset from the edges of the chart, as defined by its OuterPosition property. Axes labels ('Latitude' and 'Longitude'), ticks, and tick labels are visible. If the Title property value is set, the chart includes a title. Legends, if present, appear outside and to the right of the map.
'maximized'	Map fills the entire space, defined by the OuterPosition property. Axes labels, ticks, and tick labels are hidden. The title is hidden, even if the Title property is set. The grid is hidden, even if GridVisible is set to 'on'. Legends, if present, appear within the map, toward the upper-right corner.

Example: gb = geobubble(__,'MapLayout','maximized')

Example: gb.MapLayout = 'maximized'

Data Types: char | string

ScalebarVisible — Visibility of the scale bar on the map

'on' (default) | 'off' | true | false

Visibility of the scale bar on the map, specified as 'on' or 'off', or the logical values true or false.

Data Types: logical | char | string

ZoomLevel — Magnification level of map

real, finite, numeric scalar between 0 and 25, inclusive

Magnification level of map, specified as a real, finite, numeric scalar between 0 and 25, inclusive. The value is a base 2 logarithmic map scale. Increasing the ZoomLevel value by 1 doubles the map scale.

Data Types: single | double

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 — Size and position of geographic bubble chart within parent

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

Size and position of the geographic bubble chart within its parent, specified as a four-element numeric vector of the form [left bottom width height]. The default value of [0 0 1 1] includes the whole interior of the container.

This figure shows the areas defined by the OuterPosition values (blue) and the InnerPosition values (red).

Note

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

InnerPosition — Inner size and position

four-element vector

Inner size and position of the geographic bubble chart 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 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 geographic bubble chart.

• The width and height elements are the geographic bubble chart dimensions.

This figure shows the areas defined by the OuterPosition values (blue) and the InnerPosition values (red).

Note

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

Position — Inner size and position

four-element vector

Inner size and position of the geographic bubble chart 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.

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

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 — Visibility of the geographic bubble chart

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

Visibility of the geographic bubble chart, 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/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.

HandleVisibility — Visibility of object handle

"on" (default) | "off" | "callback"

Visibility of the 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 by another function. Set the HandleVisibility to "off" to temporarily hide the handle during the execution of that function.

• "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 permits 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. Examples of such functions include the get, findobj, gca, gcf, gco, newplot, cla, clf, and close functions.

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

Version History

Introduced in R2017b

R2023b: Some basemaps have improved appearance at high zoom levels

The "streets-light", "streets-dark", "streets", and "topographic" basemaps hosted by Esri have an improved visual appearance at high zoom levels. For example, this image compares a basemap at zoom level 21 in R2023a with the same basemap and zoom level in R2023b.

The basemaps can also have different appearances at other zoom levels. For example, this image compares a basemap at zoom level 15 in R2023a with the same basemap and zoom level in R2023b.

R2020a: ActivePositionProperty is not recommended

Starting in R2020a, setting or getting ActivePositionProperty is not recommended. Use the PositionConstraint property instead.

There are no plans to remove ActivePositionProperty at this time, but the property is no longer listed when you call the set, get, or properties functions on the chart object.

To update your code, make these changes:

• Replace all instances of ActivePositionProperty with PositionConstraint.

• Replace all references to the "position" option with the "innerposition" option.