Main Content

geobubble

Visualize data values at specific geographic locations

  • Bubble chart of data values at specific geographic locations

Description

geobubble(tbl,latvar,lonvar) creates a geographic bubble chart with filled circles (bubbles) representing the geographic locations specified in the table tbl displayed on a map. latvar identifies the table variable (column) that specifies bubble latitudes. lonvar identifies the table variable that specifies bubble longitudes. By default, the bubbles are all the same size and the same color.

The geographic bubble chart displays your data on a map, called a basemap. Initially, the chart sets the geographic limits of the chart to encompass all of your data. The map is live, that is, 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.

geobubble(lat,lon) creates a geographic bubble chart where lat and lon specify the geographic locations. By default, the bubbles are all the same size and color.

example

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

example

geobubble(lat,lon,sizedata,colordata) uses the categorical data in colordata to determine the color of the bubbles. geobubble chooses a color for each category in colordata, plus one additional color if any element of colordata is undefined. Colors are drawn from an ordered list of 7 standard colors. If there are more than seven categories (more than six, if undefined values are present), the colors repeat cyclically.

example

geobubble(___,Name,Value) specifies additional options for the geographic bubble chart using one or more name-value pair arguments. Specify the options after all other input arguments. For a list of properties, see GeographicBubbleChart Properties. Two key properties are SizeVariable and ColorVariable, which specify the table variables that determine the size and color of the bubbles.

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

collapse all

Read data about tsunamis into the workspace as a table. The rows represent individual tsunami occurrences. The columns represent data about a set of variables for each tsunami, such as their locations (latitude and longitude), causes, and wave heights.

tsunamis = readtable('tsunamis.xlsx');

Convert one of the table variables into a categorical variable to specify the color of the bubbles. 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 into a categorical variable.

tsunamis.Cause = categorical(tsunamis.Cause);

Create a geographic bubble chart, plotting the locations of the tsunamis on a map. Specify the names of the table variables that hold location information: Latitude and Longitude. Use the MaxHeight table variable to specify the size of the bubbles. The example uses the Cause variable, converted earlier into a categorical variable, to specify the color of the bubbles.

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

Read data about tsunamis into the workspace as a table. The rows represent individual tsunami occurrences. The columns represent data about a set of variables for each tsunami, such as their locations (latitude and longitude), causes, and wave heights.

tsunamis = readtable('tsunamis.xlsx');

Create a geographic bubble chart, plotting the locations of the tsunamis on a map. Use the data from the MaxHeight variable to specify the size of the bubble. In this example, you pass the data directly to geobubble. Alternatively, you can also pass geobubble the name of the table and then specify the data by table variable names.

geobubble(tsunamis.Latitude,tsunamis.Longitude,tsunamis.MaxHeight)

Read data about tsunamis into the workspace as a table. The rows represent individual tsunami occurrences. The columns represent data about each occurrence, such as the cause of each tsunami.

tsunamis = readtable('tsunamis.xlsx');

Create a categorical variable because the data that controls the color of the bubbles must be a categorical variable. The tsunami table variable Cause already categorizes the tsunamis by seven criteria: Earthquake, Earthquake and Landslide, Volcano, Volcano and Landslide, Landslide, Meteorological, and Unknown Cause. Put the Cause variable data into a categorical variable.

cause = categorical(tsunamis.Cause);

Create a geographic bubble chart, plotting the locations of the tsunamis on a map. Use bubble size to indicate the size of the wave, and use bubble color to indicate the cause. When you pass in the data, rather than specifying the names of table variables that contain the data, geobubble does not automatically add titles to the size and color legends.

geobubble(tsunamis.Latitude,tsunamis.Longitude,tsunamis.MaxHeight,cause)

Read data about tsunamis into the workspace as a table. The rows represent individual tsunami occurrences. The columns represent data about a set of variables for each tsunami, such as its location (latitude and longitude), cause, and maximum height of the wave.

tsunamis = readtable('tsunamis.xlsx');

Turn one of the table variables into a categorical variable to specify the color of the bubbles. 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 into a categorical variable.

colordata = categorical(tsunamis.Cause);

Create a geographic bubble chart, plotting the locations of the tsunamis on a map. Use bubble size to indicate the size of the wave, and use bubble color to indicate the cause of the tsunami. Add a title using a name-value pair.

gb = geobubble(tsunamis.Latitude,tsunamis.Longitude,tsunamis.MaxHeight,colordata,'Title','Tsunamis');

Use properties of the geographic bubble chart to modify the chart. For example, add titles to the size and color legends. (If you specify the table as an argument, geobubble adds legend titles automatically, using the names of table variables.)

gb.SizeLegendTitle = 'Max Height';
gb.ColorLegendTitle = 'Cause';

Input Arguments

collapse all

Table containing data to be plotted, specified as a table or timetable. You can import data as a table using the readtable function or create a table from workspace variables using the table function. You can create a timetable from workspace variables using the timetable function.

The SourceTable property of the GeographicBubbleChart object stores the table containing data to be plotted.

Data Types: table

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

  • String scalar or character vector specifying one of the table variable names. For example, geobubble(tbl,'Latitude','Longitude') selects the variable named 'Latitude' for latvar.

  • Numeric scalar indicating the table variable index. For example, geobubble(tbl,1,2) selects the first variable in the table for latitude.

  • Logical vector containing one true element.

The LatitudeVariable property of the GeographicBubbleChart object stores the selected variable.

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

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

  • String scalar or character vector specifying one of the table variable names. For example, geobubble(tbl,'Latitude','Longitude') selects the variable named 'Longitude' for lonvar.

  • Numeric scalar indicating the table variable index. For example, geobubble(tbl,1,2) selects the second variable in the table for longitude.

  • Logical vector containing one true element.

The LongitudeVariable property of the GeographicBubbleChart object stores the selected variable.

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

Latitude coordinates in degrees, specified as a real, numeric, finite vector within the range [-90 90]. The vector can contain embedded NaNs. lat must be the same size as lon.

Example: [43.0327 38.8921 44.0435]

Data Types: single | double

Longitude coordinates in degrees, specified as a real, numeric, finite vector. The vector can contain embedded NaNs. lon must be the same size as lat.

Example: [-107.5556 -77.0269 -72.5565]

Data Types: single | double

Data that determines bubble size, specified as a real, numeric, finite vector or scalar, or an empty ([]) array. If you specify a vector, sizedata must be the same size as lat and lon. If you specify a scalar value, the geographic bubble chart treats the value with scalar expansion. sizedata can contain NaNs.

Example: [99 133 150]

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

Data categories that determine bubble color, specified as a categorical variable. The categories are typically bins that data fall into.

Data Types: categorical

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.

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

Example: p = geobubble(tbl,latvar,lonvar,'SizeVariable','MaxHeight','ColorVariable','Cause')

Note

The geographic bubble chart properties listed here are frequently used properties. For a complete list, see GeographicBubbleChart Properties.

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

'streets-light' (default)

Map designed to provide geographic context while highlighting user data on a light background.

Hosted by Esri.

'streets-dark' basemap

'streets-dark'

Map designed to provide geographic context while highlighting user data on a dark background.

Hosted by Esri.

'streets' basemap

'streets'

General-purpose road map that emphasizes accurate, legible styling of roads and transit networks.

Hosted by Esri.

'satellite' basemap

'satellite'

Full global basemap composed of high-resolution satellite imagery.

Hosted by Esri.

'topographic' basemap

'topographic'

General-purpose map with styling to depict topographic features.

Hosted by Esri.

'landcover' basemap

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

'colorterrain'

Shaded relief map blended with a land cover palette. Humid lowlands are green and arid lowlands are brown.

Created using Natural Earth.

'grayterrain' basemap

'grayterrain'

Terrain map in shades of gray. Shaded relief emphasizes both high mountains and micro-terrain found in lowlands.

Created using Natural Earth.

'bluegreen' basemap

'bluegreen'

Two-tone, land-ocean map with light green land areas and light blue water areas.

Created using Natural Earth.

'grayland' basemap

'grayland'

Two-tone, land-ocean map with gray land areas and white water areas.

Created using Natural Earth.

'darkwater' basemap

'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

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

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

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

Geographic bubble chart with a normal layout

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

Geographic bubble charted with a maximized layout

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

Example: gb.MapLayout = 'maximized'

Data Types: char | string

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.

Output Arguments

collapse all

GeographicBubbleChart object, which is a standalone visualization. Use gb to set properties on the geographic bubble chart after creating it.

More About

collapse all

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 bring focus to a geographic bubble chart programmatically, use the axes function, 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.

Version History

Introduced in R2017b