geodensityplot

R2026b

Density plot in geographic coordinates

• 

Syntax

geodensityplot(lat,lon)

geodensityplot(lat,lon,weights)

geodensityplot(tbl,latvar,lonvar)

geodensityplot(tbl,latvar,lonvar,wvar)

geodensityplot(gx,___)

geodensityplot(___,Name=Value)

dp = geodensityplot(___)

Description

Vector and Matrix Data

geodensityplot(lat,lon) creates a density plot in geographic coordinates. Specify the latitude coordinates in degrees using lat, and specify the longitude coordinates in degrees using lon.

• To plot one set of coordinates, specify lat and lon as vectors of the same length.

• To plot multiple sets of coordinates on the same set of axes, specify at least one of lat or lon as a matrix. (since R2026b)

If the current axes is not a geographic axes, or if there is no current axes, then the function creates the density plot in a new geographic axes.

geodensityplot(lat,lon,weights) specifies weights for the data points. To use the same weight for all the points, specify weights as a scalar. To use a different weight for each point, specify weights as a vector or a matrix.

Table Data

geodensityplot(tbl,latvar,lonvar) creates a density plot using the variables latvar and lonvar from the table tbl.

geodensityplot(tbl,latvar,lonvar,wvar) specifies weights for the data points using the table variable wvar.

Additional Options

geodensityplot(gx,___) plots into the geographic axes specified by gx. Specify the axes as the first argument followed by any of the input argument combinations in the previous syntaxes.

geodensityplot(___,Name=Value) specifies properties of the density plot using one or more name-value arguments. For a list of properties, see DensityPlot Properties.

dp = geodensityplot(___) returns the DensityPlot object or a vector of DensityPlot objects. Use dp to set properties after creating the plot. For a full list of properties, see DensityPlot Properties.

Examples

Create Geographic Density Plot

Load a table containing cell tower data for California. Each table row represents a cell tower. The table variables include data about the cell towers, such as the latitude and longitude coordinates. Extract the latitude and longitude coordinates from the table.

load cellularTowers.mat
lat = cellularTowers.Latitude;
lon = cellularTowers.Longitude;

Create a density plot from the coordinates. By default, the geodensityplot function visualizes density by varying the transparency of the plot. Regions with high density are more opaque, and regions with low density are more transparent.

figure
geodensityplot(lat,lon)

Specify Weights for Points

Load a table containing cyclone track data. The table includes the locations and wind speeds of over 200 cyclones, measured at six-hour intervals. Extract the latitude coordinates, the longitude coordinates, and the wind speeds from the table.

load cycloneTracks.mat
lat = cycloneTracks.Latitude;
lon = cycloneTracks.Longitude;
windspeed = cycloneTracks.WindSpeed;

Create a density plot from the coordinates, and weight the points using the wind speeds. The resulting density plot highlights the areas where the cyclones have the highest wind speeds.

geodensityplot(lat,lon,windspeed)

This example uses modified RSMC Best Track Data from the Japan Meteorological Agency.

Specify Radius of Influence

Load a table containing cell tower data for California. Each table row represents a cell tower. The table variables include data about the cell towers, such as the latitude and longitude coordinates. Extract the latitude and longitude coordinates from the table.

load cellularTowers.mat
lat = cellularTowers.Latitude;
lon = cellularTowers.Longitude;

Create a density plot from the coordinates. Specify the radius of influence for each point as 50 km.

geodensityplot(lat,lon,Radius=50e3)

Visualize Density by Varying Colors

By default, the geodensityplot function visualizes density by varying the transparency of the density plot. You can also visualize density by varying the plot colors.

Load a table containing cyclone track data. The table records the tracks of over 200 cyclones, measured at six-hour intervals. Extract the latitude and longitude coordinates from the table.

load cycloneTracks.mat
lat = cycloneTracks.Latitude;
lon = cycloneTracks.Longitude;

Create a density plot from the coordinates. Vary the plot colors by setting the FaceColor property to "interp".

geodensityplot(lat,lon,FaceColor="interp")

Change the colormap, and add a labeled color bar. When you do not weight the data, the units of the density plot are points per square meter. Note that the plot visualizes the density using both transparency and color.

colormap turbo
c = colorbar;
c.Label.String = "Data points per square meter";

This example uses modified RSMC Best Track Data from the Japan Meteorological Agency.

Plot Data from Table

Since R2026a

You can plot data directly from a table by passing the table to the geodensityplot function and specifying the variables to plot.

Load a table containing cell tower data for California. The table stores the latitude and longitude coordinates in the table variables Latitude and Longitude, respectively.

load cellularTowers.mat

Create a density plot from the table. Return the DensityPlot object as dp.

dp = geodensityplot(cellularTowers,"Latitude","Longitude");

Change the face color of the plot by setting the FaceColor property.

dp.FaceColor = "m";

Input Arguments

lat — Latitude coordinates in degrees

vector with elements in range [–90, 90] | matrix with elements in range [–90, 90] (since R2026b)

Latitude coordinates in degrees, specified as a vector or matrix with elements in the range [–90, 90]. This argument can contain NaN values.

The size and shape of lat depends on the shape of your data and the type of plot you want to create. This table describes the most common situations.

Type of Plot	How to Specify Coordinates
One set of points	Specify lat and lon as any combination of row or column vectors of the same length. For example: geodensityplot([1 2 3],[4; 5; 6])
Multiple sets of points, using vectors	Specify consecutive pairs of lat and lon as vectors. For example: geodensityplot([1 2 3],[4 5 6],[1 2 3],[7 8 9])
Multiple sets of points, using matrices (since R2026b)	If all the sets share the same latitude or longitude coordinates, specify the shared coordinates as a vector and the other coordinates as a matrix. The length of the vector must match one of the dimensions of the matrix. For example: geodensityplot([1 2 3],[4 5 6; 7 8 9]) If the matrix is square, the function plots one line for each column in the matrix. Alternatively, specify lat and lon as matrices of equal size. In this case, the function plots each column of lon against the corresponding column of lat. For example: geodensityplot([1 2 3; 4 5 6],[7 8 9; 10 11 12])

Data Types: single | double

lon — Longitude coordinates in degrees

vector | matrix (since R2026b)

Longitude coordinates in degrees, specified as a vector or matrix. This argument can contain NaN values.

The size and shape of lon depends on the shape of your data and the type of plot you want to create. This table describes the most common situations.

Type of Plot	How to Specify Coordinates
One set of points	Specify lat and lon as any combination of row or column vectors of the same length. For example: geodensityplot([1 2 3],[4; 5; 6])
Multiple sets of points, using vectors	Specify consecutive pairs of lat and lon as vectors. For example: geodensityplot([1 2 3],[4 5 6],[1 2 3],[7 8 9])
Multiple sets of points, using matrices (since R2026b)	If all the sets share the same latitude or longitude coordinates, specify the shared coordinates as a vector and the other coordinates as a matrix. The length of the vector must match one of the dimensions of the matrix. For example: geodensityplot([1 2 3],[4 5 6; 7 8 9]) If the matrix is square, the function plots one line for each column in the matrix. Alternatively, specify lat and lon as matrices of equal size. In this case, the function plots each column of lon against the corresponding column of lat. For example: geodensityplot([1 2 3; 4 5 6],[7 8 9; 10 11 12])

Data Types: single | double

weights — Weights assigned to data

[] (default) | numeric scalar | numeric vector | numeric matrix (since R2026b)

Weights assigned to the data, specified as a numeric scalar, vector, matrix, or empty array ([]). This argument typically specifies additional data that is related to the location data in lat and lon.

The way you specify the weights depends on how you specify lat and lon. This table describes the most common situations.

lat and lon	weights	Example
Any valid combination of vectors or matrices described for lat and lon	Scalar	Specify lat as a vector, lon as a matrix, and weights as a scalar. lat = [1 2 3 4]; lon = [1 6; 3 8; 2 7; 4 9]; geodensityplot(lat,lon,100)
Vectors of the same length	A vector with the same length as lat and lon. A matrix with at least one dimension that matches the lengths of lat and lon.	Specify lat, lon, and weights as vectors. lat = [1 2 3 4]; lon = [1 3 2 4]; weights = [80 150 700 50]; geodensityplot(lat,lon,weights) Specify lat and lon as vectors and weights as a matrix. lat = [1 2 3 4]; lon = [1 3 2 4]; weights = [80 30; 150 900; 50 2000; 200 350]; geodensityplot(lat,lon,weights)
At least one of lat or lon is a matrix for plotting multiple data sets	A vector with the same number of elements as there are points in each data set. A matrix that has the same size as the lat or lon matrix.	Specify lat as a vector, lon as a matrix, and weights as a vector. lat = [1 2 3 4]; lon = [1 6; 3 8; 2 7; 4 9]; weights = [80 150 50 700]; geodensityplot(lat,lon,weights) Specify lat as a vector, lon as a matrix, and weights as a matrix the same size as lon. lat = [1 2 3 4]; lon = [1 6; 3 8; 2 7; 4 9]; weights = [80 30; 150 900; 50 2000; 200 350]; geodensityplot(lat,lon,weights)

tbl — Source table

table | timetable

Source table containing the data to plot, specified as a table or timetable.

latvar — Table variable containing latitude coordinates

table variable index | multiple table variable indices (since R2026b)

Since R2026a

Table variables containing the latitude coordinates, specified as one or more table variable indices.

Specify the variable or variables using one of the indexing schemes from the table.

Indexing Scheme	Examples
Variable names: A string array, character vector, or cell array. A pattern object.	"A" or 'A' — A variable named A ["A","B"] or {'A','B'} — Two variables named A and B "Var"+digitsPattern(1) — Variables named "Var" followed by a single digit
Variable indices: An index number that refers to the location of a variable in the table. A vector of numbers. 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 [2 3] — The second and third variables from the table [false false true] — The third variable
Variable type: A vartype subscript that selects variables of a specified type.	vartype("double") — All the variables containing double values

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

The variables you specify must contain numeric data of type single or double. The data must be in the range [–90, 90].

If latvar and lonvar specify multiple variables, the number of variables must be the same.

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

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

lonvar — Table variable containing longitude coordinates

table variable index | multiple table variable indices (since R2026b)

Since R2026a

Table variables containing the latitude coordinates, specified as one or more table variable indices.

Specify the variable or variables using one of the indexing schemes from the table.

Indexing Scheme	Examples
Variable names: A string array, character vector, or cell array. A pattern object.	"A" or 'A' — A variable named A ["A","B"] or {'A','B'} — Two variables named A and B "Var"+digitsPattern(1) — Variables named "Var" followed by a single digit
Variable indices: An index number that refers to the location of a variable in the table. A vector of numbers. 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 [2 3] — The second and third variables from the table [false false true] — The third variable
Variable type: A vartype subscript that selects variables of a specified type.	vartype("double") — All the variables containing double values

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

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

If latvar and lonvar specify multiple variables, the number of variables must be the same.

Example: geodensityplot(tbl,"lat","lon") specifies the table variable lon for the longitude coordinates.

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

wvar — Table variable containing weights assigned to data

table variable index | multiple table variable indices (since R2026b)

Since R2026a

Table variables containing the latitude coordinates, specified as one or more table variable indices.

Specify the variable or variables using one of the indexing schemes from the table.

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 variables you specify must contain numeric data.

If wvar specifies multiple variables, the number of variables must match that of latvar or lonvar.

Example: geodensityplot(tbl,"lat","lon","wgt") specifies the table variable named wgt for the weights.

Example: geodensityplot(tbl,"lat","lon",2) specifies the second table variable for the weights.

gx — Target geographic axes

GeographicAxes object

Target geographic axes, specified as a GeographicAxes object.¹ You can modify the appearance and behavior of a GeographicAxes object by setting its properties. For a list of properties, see GeographicAxes Properties.

If you do not specify this argument, then the function plots into the current axes, provided that the current axes is a geographic axes. If the current axes is not a geographic axes, or if there is no current axes, then the function plots into a new geographic axes.

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: geodensityplot(lat,lon,FaceColor="g") sets the face color of the density plot to green.

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

Example: geodensityplot(lat,lon,"FaceColor","g") sets the face color of the density plot to green.

Note

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

Radius — Radius of influence, in meters

numeric scalar

Radius of influence on the density calculation, in meters, specified as a numeric scalar.

FaceAlpha — Face transparency

'interp' (default) | scalar in range [0, 1]

Face transparency, specified as one of these values:

• 'interp' — Use interpolated transparency based on the density values.

• Scalar in the range [0, 1] — Use uniform transparency across all the faces. A value of 1 is opaque and a value of 0 is completely transparent. Values between 0 and 1 are semitransparent.

The appearance of the density plot depends on both the FaceAlpha and FaceColor properties. This table shows how different combinations of FaceAlpha and FaceColor affect the appearance of the plot.

Values of FaceColor and FaceAlpha	Effect	Sample Density Plot
FaceAlpha is "interp" FaceColor is an RGB triplet, a hexadecimal color code, a color name, or a short name	The density plot uses one color and conveys density by varying the transparency.
FaceAlpha is "interp" FaceColor is "interp"	The density plot conveys density by varying the transparency and the color.
FaceAlpha is a scalar value FaceColor is "interp"	The density plot uses one transparency value and conveys density by varying the color.

For more information about controlling the transparency of a density plot, see Adjust Transparency of Geographic Density Plots.

FaceColor — Face color

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

Face color, specified as one of these options:

• 'interp' — Use interpolated coloring based on the density values. MATLAB^® chooses colors from the colormap of the parent axes. When you choose this option, the appearance of the density plot also depends on the value of the FaceAlpha property. For more information, see the FaceAlpha property.

• An RGB triplet, a hexadecimal color code, a color name, or a short name — Apply one color to the density plot. When you choose this option, the value of FaceAlpha must be "interp".

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"

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default Before R2025a: Most plots use these colors by default.
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Output Arguments

dp — Geographic density plot

DensityPlot object | vector of DensityPlot objects

Geographic density plot, returned as a DensityPlot object or a vector of DensityPlot objects. Use dp to access and modify properties of the density plot after creating it.

Tips

When you plot on geographic axes, the geodensityplot 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 might appear misaligned.

Algorithms

A density plot is a surface with varying transparency. The geodensityplot function creates the surface by calculating a cumulative probability distribution from the specified points and varying the transparency with the density of the points.

By default, each point contributes equally to the density plot. When you weight the points, the function multiplies the contribution of the associated points to the density plot.

Alternative Functionality

A density plot is a type of heatmap. Other types of heatmaps that you can create on maps include:

• Choropleth maps, which display the values of numeric attributes within polygons. For an example, see Create Choropleth Map from Table Data (Mapping Toolbox).

• Binned scatter plots, which partition points into bins and display the number of points in each bin. For an example, see Create Binned Scatter Plot from Latitude and Longitude Data (Mapping Toolbox).

• Pseudocolor raster plots, which display the values stored in a raster. For examples, see the geopcolor (Mapping Toolbox) reference page.

Version History

Introduced in R2018b

R2026b: Pass matrices and multiple table variables to geodensityplot

Create multiple plots at once by passing matrices or multiple table variables to the geodensityplot function.

R2026a: Pass tables directly to geodensityplot

Create a plot by passing a table to the geodensityplot function followed by the table variables you want to plot.

R2022b: Adding new plots to geographic axes does not reset basemap

When you plot into geographic axes by using functions such as geodensityplot and geoplot, MATLAB does not reset the basemap. In R2022a and earlier releases, the basemap resets when you add new plots.

As a result, you can specify a basemap and then visualize data without using the hold function between commands. For example, this code creates a map using the streets basemap. Then it displays a density plot over the basemap. In R2022b, the basemap does not reset. In R2022a and earlier releases, the basemap resets to the default streets-light.

load cycloneTracks;
lat = cycloneTracks.Latitude;
lon = cycloneTracks.Longitude;
 
figure
geobasemap streets
geodensityplot(lat,lon,"FaceColor","m")

This change does not affect existing code that sets the hold state to "on" between commands.

To reset the basemap when you add a new plot, use the cla reset syntax of the cla function before you create the plot. For example, to update the preceding code, use cla reset between the calls to geobasemap and geodensityplot.

load cycloneTracks;
lat = cycloneTracks.Latitude;
lon = cycloneTracks.Longitude;
 
figure
geobasemap streets
cla reset
geodensityplot(lat,lon,"FaceColor","m")

Alternatively, you can change the basemap to the default streets-light by using the geobasemap function. For more information about changing the basemap of geographic axes, see Access Basemaps for Geographic Axes and Charts.