geobubble

Visualize data values at specific geographic locations

• 

Syntax

geobubble(tbl,latvar,lonvar)

geobubble(lat,lon)

geobubble(lat,lon,sizedata)

geobubble(lat,lon,sizedata,colordata)

geobubble(___,Name=Value)

geobubble(parent,___)

gb = geobubble(___)

Description

Table Data

geobubble(tbl,latvar,lonvar) creates a geographic bubble chart from the table tbl. The latvar argument indicates the table variables that contains latitudes. The lonvar argument indicates the table variables that contains longitudes. By default, all the bubbles are the same size and color.

Vector Data

geobubble(lat,lon) creates a geographic bubble chart from the latitudes in lat and the longitudes in lon. By default, all the bubbles are the same size and color.

geobubble(lat,lon,sizedata) scales the areas of the bubbles according to the numeric values in sizedata.

geobubble(lat,lon,sizedata,colordata) specifies the colors of the bubbles using the categorical values in colordata. The function chooses a color for each category in colordata, plus one additional color for any elements of colordata that are undefined. The function selects colors from an ordered list of seven standard colors. If your data specifies more than seven categories, then the function cyclically repeats the colors.

Additional Options

geobubble(___,Name=Value) specifies GeographicBubbleChart properties using name-value arguments. Specify the properties after all other input arguments. For example, the SizeVariable and ColorVariable properties enable you to specify table variables that determine the sizes and colors of the bubbles. For a list of properties, see GeographicBubbleChart Properties.

geobubble(parent,___) creates the geographic bubble chart in the figure, panel, tab, or tiled chart layout specified by parent.

gb = geobubble(___) returns the GeographicBubbleChart object. Use gb to modify properties of the chart after creating it. For a list of properties, see GeographicBubbleChart Properties.

Examples

Create Geographic Bubble Chart from Table

Read data about tsunamis into the workspace as a table. The table rows represent individual tsunami occurrences. The table variables include data about the tsunamis, such as the latitudes, longitudes, causes, and wave heights.

tsunamis = readtable("tsunamis.xlsx");

Prepare to color the bubbles according to the causes of the tsunamis. The Cause variable attributes a cause to each tsunami, such as 'Earthquake', 'Volcano', or 'Earthquake and Landslide'. Convert the Cause variable from a cell array of character vectors to a categorical vector.

tsunamis.Cause = categorical(tsunamis.Cause);

Create a geographic bubble chart from the table. Specify the tsunami locations using the Latitude and Longitude table variables. Specify the sizes of the bubble using the wave heights stored in the MaxHeight table variable. Specify the colors of the bubbles using the categories stored in the Cause table variable. When you create a geographic bubble chart from table data and specify the SizeVariable and ColorVariable arguments, the size and color legends display the names of the associated table variables.

geobubble(tsunamis,"Latitude","Longitude", ...
    SizeVariable="MaxHeight",ColorVariable="Cause")

Specify Bubble Sizes

Read data about tsunamis into the workspace as a table. The table rows represent individual tsunami occurrences. The table variables include data about the tsunamis, such as the latitudes, longitudes, causes, and wave heights.

tsunamis = readtable("tsunamis.xlsx");

Extract the latitudes, longitudes, and wave heights from the table.

lat = tsunamis.Latitude;
lon = tsunamis.Longitude;
sizedata = tsunamis.MaxHeight;

Create a geographic bubble chart from the latitudes, longitudes, and wave heights. Specify the bubble sizes using the wave heights. The geobubble function uses sizedata to control the relative distribution of the bubble sizes.

geobubble(lat,lon,sizedata)

Specify Bubble Colors

Read data about tsunamis into the workspace as a table. The table rows represent individual tsunami occurrences. The table variables include data about the tsunamis, such as the latitudes, longitudes, causes, and wave heights.

tsunamis = readtable("tsunamis.xlsx");

Extract the latitudes, longitudes, wave heights, and causes from the table.

lat = tsunamis.Latitude;
lon = tsunamis.Longitude;
sizedata = tsunamis.MaxHeight; 
colordata = tsunamis.Cause;

The colordata variable categorizes the tsunamis by seven criteria: Earthquake, Earthquake and Landslide, Volcano, Volcano and Landslide, Landslide, Meteorological, and Unknown Cause. Convert colordata to a categorical vector.

colordata = categorical(colordata); 

Create a geographic bubble chart from the latitudes, longitudes, wave heights, and causes. Specify the bubble sizes using the wave heights. Specify the bubble colors using the causes.

geobubble(lat,lon,sizedata,colordata)

Add Title and Legend Titles

When you create geographic bubble charts from vector data, the legends do not have titles. Add legend titles by specifying properties of the geographic bubble chart.

Read data about tsunamis into the workspace as a table. The table rows represent individual tsunami occurrences. The table variables include data about the tsunamis, such as the latitudes, longitudes, causes, and wave heights.

tsunamis = readtable("tsunamis.xlsx");

Extract the latitudes, longitudes, wave heights, and causes from the table.

lat = tsunamis.Latitude;
lon = tsunamis.Longitude;
sizedata = tsunamis.MaxHeight; 
colordata = tsunamis.Cause;

The colordata variable categorizes the tsunamis by seven criteria: Earthquake, Earthquake and Landslide, Volcano, Volcano and Landslide, Landslide, Meteorological, and Unknown Cause. Convert colordata to a categorical vector.

colordata = categorical(colordata); 

Create a geographic bubble chart from the data. Return the GeographicBubbleChart object as gb.

gb = geobubble(lat,lon,sizedata,colordata);

Add a title and legend titles by setting the Title, SizeLegendTitle, and ColorLegendTitle properties.

gb.Title = "Tsunamis";
gb.SizeLegendTitle = "Max Height";
gb.ColorLegendTitle = "Cause";

Input Arguments

tbl — Source table

table | timetable

Source table, specified as a table or a timetable.

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

The SourceTable property of the GeographicBubbleChart object stores the table that contains the plotted data.

latvar — Table variable containing latitude coordinates

string scalar | character vector | pattern | numeric scalar | logical vector | vartype()

Table variable containing the latitude coordinates, specified using one of these indexing schemes.

Indexing Scheme	Examples
Variable name: A string scalar or character vector. A pattern object. The pattern object must refer to only one variable.	"A" or 'A' — A variable named A "Var"+digitsPattern(1) — The variable with the name "Var" followed by a single digit
Variable index: An index number that refers to the location of a variable in the table. A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values.	3 — The third variable from the table [false false true] — The third variable
Variable type: A vartype subscript that selects a table variable of a specified type. The subscript must refer to only one variable.	vartype("double") — The variable containing double values

Regardless of the variable name, the axis label on the plot is always Latitude.

The variable you specify must contain numeric data of type single or double. The data must be in the range (–90, 90).

Example: geobubble(tbl,"lat1","lon") specifies the table variable named lat1 for the latitude coordinates.

Example: geobubble(tbl,2,"lon") specifies the second variable for the latitude coordinates.

Example: geobubble(tbl,vartype("numeric"),"lon") specifies a numeric variable for the latitude coordinates.

lonvar — Table variable containing longitude coordinates

string scalar | character vector | pattern | numeric scalar | logical vector | vartype()

Table variable containing the longitude coordinates, specified using one of these indexing schemes.

Indexing Scheme	Examples
Variable name: A string scalar or character vector. A pattern object. The pattern object must refer to only one variable.	"A" or 'A' — A variable named A "Var"+digitsPattern(1) — The variable with the name "Var" followed by a single digit
Variable index: An index number that refers to the location of a variable in the table. A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values.	3 — The third variable from the table [false false true] — The third variable
Variable type: A vartype subscript that selects a table variable of a specified type. The subscript must refer to only one variable.	vartype("double") — The variable containing double values

Regardless of the variable name, the axis label on the plot is always Longitude.

The variables you specify must contain numeric data of type single or double.

Example: geobubble(tbl,"lat","lon1") specifies the table variable named lon1 for the longitude coordinates.

Example: geobubble(tbl,"lat",2) specifies the second variable for the longitude coordinates.

Example: geobubble(tbl,"lat",vartype("numeric")) specifies a numeric variable for the longitude coordinates.

lat — Latitude coordinates in degrees

vector with elements in the range [–90, 90]

Latitude coordinates in degrees, specified as vector with elements in the range [–90, 90]. The vector can contain NaN values.

The sizes of lat and lon must match.

Example: [43.0327 38.8921 44.0435]

Data Types: single | double

lon — Longitude coordinates in degrees

vector

Longitude coordinates in degrees, specified as a vector. The vector can contain NaN values.

The sizes of lon and lat must match.

Example: [-107.5556 -77.0269 -72.5565]

Data Types: single | double

sizedata — Relative bubble sizes

scalar | vector | []

Relative bubble sizes, specified as a scalar, a vector, or an empty array ([]). Vector inputs can include NaN values.

sizedata controls the relative distribution of the bubble sizes. By default, geobubble linearly maps a range of bubble areas across the range of the sizedata values.

If sizedata is a vector, the sizes of sizedata, lat, and lon must match.

Example: [99 133 150]

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

colordata — Categories for bubble colors

categorical scalar | categorical vector

Categories that determine the bubble colors, specified as a categorical scalar or categorical vector. The categories are typically bins that data fall into.

Data Types: categorical

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.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: geobubble(tbl,latvar,lonvar,SizeVariable="MaxHeight",ColorVariable="Cause") specifies the table variables that contain bubble size data and bubble color data.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: geobubble(tbl,latvar,lonvar,"SizeVariable","MaxHeight","ColorVariable","Cause") specifies the table variables that contain bubble size data and bubble color data.

Note

Use name-value arguments to specify values for the properties of the GeographicBubbleChart objects created by this function. The properties listed here are only a subset. For a complete list, see GeographicBubbleChart Properties.

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

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

SizeVariable — Table variable containing bubble size data

table variable index

Table variable containing the bubble size data, specified using one of these indexing schemes.

Indexing Scheme	Examples
Variable name: A string scalar or character vector. A pattern object. The pattern object must refer to only one variable.	"A" or 'A' — A variable named A "Var"+digitsPattern(1) — The variable with the name "Var" followed by a single digit
Variable index: An index number that refers to the location of a variable in the table. A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values.	3 — The third variable from the table [false false true] — The third variable
Variable type: A vartype subscript that selects a table variable of a specified type. The subscript must refer to only one variable.	vartype("double") — The variable containing double values

The variable you specify can contain any numeric type. When you set the SizeVariable property, MATLAB updates the SizeData property.

ColorVariable — Table variable containing bubble color data

table variable index

Table variable containing the bubble color data, specified using one of these indexing schemes.

Indexing Scheme	Examples
Variable name: A string scalar or character vector. A pattern object. The pattern object must refer to only one variable.	"A" or 'A' — A variable named A "Var"+digitsPattern(1) — The variable with the name "Var" followed by a single digit
Variable index: An index number that refers to the location of a variable in the table. A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values.	3 — The third variable from the table [false false true] — The third variable
Variable type: A vartype subscript that selects a table variable of a specified type. The subscript must refer to only one variable.	vartype("double") — The variable containing double values

The variable you specify must contain categorical values. When you set the ColorVariable property, MATLAB updates the ColorData property.

Output Arguments

gb — Geographic bubble chart

GeographicBubbleChart object

Geographic bubble chart, returned as a GeographicBubbleChart object. A geographic bubble chart is a standalone visualization. Use gb to set properties of the geographic bubble chart after creating it.

More About

Geographic Bubble Chart

A geographic bubble chart displays your data on a map with a basemap that provides geographic context for your data. Initially, the chart sets the geographic limits of the map to encompass all of your data. The map is live, so you can pan the basemap to view other geographic locations. You can also zoom in and out on the map to view regions in more detail. The chart updates the map as you pan and zoom. For more information about geographic bubble charts and basemaps, see Geographic Bubble Charts Overview.

Standalone Visualization

A standalone visualization is a chart designed for a special purpose that works independently from other charts. Unlike other charts such as plot and surf, a standalone visualization has a preconfigured axes object built into it, and some customizations are not available. A standalone visualization also has these characteristics:

• It cannot be combined with other graphics elements, such as lines, patches, or surfaces. Thus, the hold command is not supported.

• The gca function can return the chart object as the current axes.

• You can pass the chart object to many MATLAB functions that accept an axes object as an input argument. For example, you can pass the chart object to the title function.

Tips

• If you create a geographic bubble chart from a table, then you can customize its data tips.

  • To add or remove a row from the data tip, right-click anywhere on the chart and point to Modify Data Tips. Then, select or deselect a variable.

  • To add or remove multiple rows, right-click on the chart, point to Modify Data Tips, and select More. Then, add variables by clicking >> or remove them by clicking <<.

• To programmatically bring focus to a geographic bubble chart, use the axes function, for example axes(gb).

• When you plot on geographic axes, the geobubble function assumes that coordinates are referenced to the WGS84 coordinate reference system. If you plot using coordinates that are referenced to a different coordinate reference system, then the coordinates may appear misaligned.

Alternative Functionality

• Geographic bubble charts do not support customizations such as changing the line width of bubbles, changing the transparency of bubbles, or adding text and line annotations. To create a similar chart that supports more customizations, create a geographic axes object by using the geoaxes function. Then, create a bubble chart in the geographic axes object by using the bubblechart function.

• To create a bubble chart in a map axes object (Mapping Toolbox™), use the bubblechart function.

Version History

Introduced in R2017b