geoscatter

Scatter chart in geographic coordinates

• 

Syntax

geoscatter(lat,lon)

geoscatter(lat,lon,A)

geoscatter(lat,lon,A,C)

geoscatter(___,'filled')

geoscatter(___,M)

geoscatter(tbl,latvar,lonvar)

geoscatter(tbl,latvar,lonvar,'filled')

geoscatter(gx,___)

geoscatter(___,Name,Value)

s = geoscatter(___)

Description

Vector Data

geoscatter(lat,lon) displays colored circles in a geographic axes at the latitude-longitude locations specified (in degrees) by the vectors lat and lon. lat and lon must be the same size.

geoscatter(lat,lon,A) uses A to specify the area of each marker (in points^2). To draw all the markers with the same size, specify A as a scalar. To draw the markers with different sizes, specify A as a vector the same length as lat and lon. If you do not specify A, geoscatter uses the default size.

geoscatter(lat,lon,A,C) uses C to specify the color of each marker.

geoscatter(___,'filled') fills the markers.

geoscatter(___,M) creates a scatter plot where M specifies the marker used. By default, geoscatter uses circles as the marker.

Table Data

geoscatter(tbl,latvar,lonvar) plots the variables latvar and lonvar from the table tbl. To plot one data set, specify one variable for latvar and one variable for lonvar. To plot multiple data sets, specify multiple variables for latvar, lonvar, or both. If both arguments specify multiple variables, they must specify the same number of variables. (Since R2022b)

geoscatter(tbl,latvar,lonvar,'filled') plots the specified variables from the table with filled circles. (Since R2022b)

Additional Options

geoscatter(gx,___) plots into the geographic axes specified by gx instead of into the current axes.

geoscatter(___,Name,Value) specifies properties of the scatter plot using one or more name-value arguments. The property settings apply to all the scatter plots.

s = geoscatter(___) returns the Scatter object. Use S to modify properties of the object after it is created.

Examples

Create Geographic Scatter Plot Controlling Color, Size, and Shape of Markers

Set up latitude and longitude data.

lon = (-170:10:170);
lat = 50 * cosd(3*lon);

Define data that controls the area of each marker.

A = 101 + 100*(sind(2*lon));

Define data to control the color of each marker.

C = cosd(4*lon);

Plot the data on a geographic scatter plot, specifying the marker size data and the color data. Specify the marker as a triangle, rather than the default circle.

geoscatter(lat,lon,A,C,'^')

Plot Data from a Table

Since R2022b

A convenient way to plot data from a table is to pass the table to the geoscatter function and specify the variables to plot.

Load a file containing county data into the workspace as a table. The table includes latitude and longitude coordinates in the table variables Latitude and Longitude, respectively.

tbl = readtable("counties.xlsx"); 

Plot the latitude and longitude coordinates over a two-tone basemap. Return the Scatter object as s.

s = geoscatter(tbl,"Latitude","Longitude");
geobasemap grayland

Change the marker style and color of the plot by setting the Marker and MarkerEdgeColor properties.

s.Marker = "*";
s.MarkerEdgeColor = "m";

Plot Table Data with Custom Colors and Marker Sizes

Since R2022b

One way to plot data from a table and customize the colors and marker sizes is to set the ColorVariable and SizeData properties. You can set these properties as name-value arguments when you call the geoscatter function, or you can set them on the Scatter object later.

For example, load a file containing county data into the workspace as a table. The table includes latitude and longitude coordinates in the table variables Latitude and Longitude, respectively.

tbl = readtable("counties.xlsx");

Plot the latitude and longitude coordinates using filled markers. Return the Scatter object as s.

s = geoscatter(tbl,"Latitude","Longitude","filled");

Change the marker sizes to 100 points by setting the SizeData property.

s.SizeData = 100;

Vary the marker colors by setting the ColorVariable property to a table variable. Then, add a colorbar.

s.ColorVariable = "Population2010";
c = colorbar;
c.Label.String = "County Population in 2010";

Change Basemap of Geographic Scatter Plot

Specify the coordinates of sample latitude and longitude data.

lon = (-170:10:170);
lat = 50 * cosd(3*lon);

Define the data that controls the area of each marker.

A = 101 + 100*(sind(2*lon));

Define the data that controls the color of each marker.

C = cosd(4*lon);

Create a geographic scatter plot, specifying the marker size data, the color data, and the marker type. Then, change the basemap.

geoscatter(lat,lon,A,C,'^')
geobasemap colorterrain

Input Arguments

lat — Latitude coordinates in degrees

real, numeric, finite vector within the range [-90 90]

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

lon — Longitude coordinates in degrees

real, numeric, finite vector

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

A — Marker sizes in points squared

36 (default) | scalar | vector | []

Marker sizes in points squared, specified in one of these forms:

• Scalar — Uniform marker size. For example, A = 100 creates all markers with an area of 100 points squared.

• Vector — Different marker size for each data point. The vector must be the same length as lat and lon.

• Empty brackets [] — Default marker size with an area of 36 points squared. Use this option if you want to specify the color input argument, but use the default marker area; for example, geoscatter(lat,lon,[],c).

The SizeData property of the scatter object stores the marker sizes.

Example: 50

Example: [36 25 25 17 46]

C — Marker color

RGB triplet | three-column matrix of RGB triplets | vector | 'r' | 'g' | 'b' | ...

Marker color, specified in one of these forms:

• RGB triplet or color name — Plot all markers with the same color.

• Three-column matrix of RGB triplets — Use different colors for each marker. Each row of the matrix specifies an RGB triplet color for the corresponding marker. The number of rows must equal the length of lat and lon.

• Vector — Use different colors for each marker and linearly map values in C to the current colormap. The length of C must equal the length of lat and lon. To change the colormap for the axes, use the colormap function.

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]. Alternatively, you can specify some common colors by name. This table lists the long and short color name options and the equivalent RGB triplet values.

Color Name	Short Name	RGB Triplet	Appearance
"red"	"r"	[1 0 0]
"green"	"g"	[0 1 0]
"blue"	"b"	[0 0 1]
"cyan"	"c"	[0 1 1]
"magenta"	"m"	[1 0 1]
"yellow"	"y"	[1 1 0]
"black"	"k"	[0 0 0]
"white"	"w"	[1 1 1]

When you specify marker colors, geoscatter sets the MarkerFaceColor property of the Scatter object to 'flat' and stores the marker colors in the CData property.

Example: 'green'

Example: 'g'

Example: [0 1 0]

M — Marker symbol

'o' (default) | '+' | '*' | '.' | 'x' | ...

Marker symbol, specified as one of these values.

Marker	Description	Resulting Marker
"o"	Circle
"+"	Plus sign
"*"	Asterisk
"."	Point
"x"	Cross
"_"	Horizontal line
"|"	Vertical line
"square"	Square
"diamond"	Diamond
"^"	Upward-pointing triangle
"v"	Downward-pointing triangle
">"	Right-pointing triangle
"<"	Left-pointing triangle
"pentagram"	Pentagram
"hexagram"	Hexagram

'filled' — Option to fill the interior of the markers

'filled'

Option to fill the interior of the markers, specified as 'filled'. Use this option with markers that have a face, for example, 'o' or 'square'.

tbl — Source table

table | timetable

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

latvar — Table variables containing latitude coordinates

string array | character vector | cell array | pattern | numeric scalar or vector | logical vector | vartype()

Table variables containing the latitude coordinates, specified using one of the indexing schemes from the table.

Indexing Scheme	Examples
Variable names: A string, character vector, or cell array. A pattern object.	"A" or 'A' — A variable called A ["A","B"] or {'A','B'} — Two variables called A and B "Var"+digitsPattern(1) — Variables named "Var" followed by a single digit
Variable index: 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("categorical") — All the variables containing categorical values

Regardless of the variable name, 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 both specify multiple variables, the number of variables must be the same.

Example: geoscatter(tbl,["lat1","lat2"],"lon") specifies the table variables named lat1 and lat2 for the latitude coordinates.

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

Example: geoscatter(tbl,vartype("numeric"),"lon") specifies all numeric variables for the latitude coordinates.

lonvar — Table variables containing longitude coordinates

string array | character vector | cell array | pattern | numeric scalar or vector | logical vector | vartype()

Table variables containing the longitude coordinates, specified using one of the indexing schemes from the table.

Indexing Scheme	Examples
Variable names: A string, character vector, or cell array. A pattern object.	"A" or 'A' — A variable called A ["A","B"] or {'A','B'} — Two variables called A and B "Var"+digitsPattern(1) — Variables named "Var" followed by a single digit
Variable index: 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("categorical") — All the variables containing categorical 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.

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

Example: geoscatter(tbl,"lat",["lon1","lon2"]) specifies the table variables named lon1 and lon2 for the longitude coordinates.

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

Example: geoscatter(tbl,"lat",vartype("numeric")) specifies all numeric variables for the longitude coordinates.

gx — Parent geographic axes object

GeographicAxes object

Parent geographic axes object, 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.

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: geoscatter(lat,lon,'filled','MarkerFaceAlpha',.5) creates filled, semi-transparent markers.

The scatter object properties listed here are only a subset. For a complete list, see Scatter Properties.

Marker — Marker type

'o' (default) | '+' | '*' | '.' | 'x' | ...

Marker symbol, specified as one of these options.

Marker	Description	Resulting Marker
"o"	Circle
"+"	Plus sign
"*"	Asterisk
"."	Point
"x"	Cross
"_"	Horizontal line
"|"	Vertical line
"square"	Square
"diamond"	Diamond
"^"	Upward-pointing triangle
"v"	Downward-pointing triangle
">"	Right-pointing triangle
"<"	Left-pointing triangle
"pentagram"	Pentagram
"hexagram"	Hexagram
"none"	No markers	Not applicable

MarkerEdgeColor — Marker outline color

"flat" (default) | RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

Marker outline color, specified "flat", an RGB triplet, a hexadecimal color code, a color name, or a short name. The default value of "flat" uses colors from the CData property.

For a custom color, specify an RGB triplet or a hexadecimal color code.

• 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. Therefore, 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"
"none"	Not applicable	Not applicable	Not applicable	No color

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"

Example: [0.5 0.5 0.5]

Example: "blue"

Example: "#D2F9A7"

MarkerFaceColor — Marker fill color

"none" (default) | "flat" | "auto" | RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

Marker fill color, specified as "flat", "auto", an RGB triplet, a hexadecimal color code, a color name, or a short name. The "flat" option uses the CData values. The "auto" option uses the same color as the Color property for the axes.

For a custom color, specify an RGB triplet or a hexadecimal color code.

• 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. Therefore, 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"
"none"	Not applicable	Not applicable	Not applicable	No color

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"

Example: [0.3 0.2 0.1]

Example: "green"

Example: "#D2F9A7"

LineWidth — Width of marker edge

0.5 (default) | positive value

Width of marker edge, specified as a positive value in point units.

Example: 0.75

Output Arguments

s — Geographic scatter plot

Scatter object

Geographic scatter plot, returned as a Scatter object. Use s to access and modify properties of the geographic scatter plot after it has been created.

Tips

• To customize the geographic axes containing your scatter object, obtain the object's parent, gx = s.Parent, and modify its properties. For a list of properties, see GeographicAxes Properties.

• If you have Mapping Toolbox™, you can specify basemaps of your own choosing by using the addCustomBasemap function.

• When you plot on geographic axes, the geoscatter 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 R2018b

R2022b: Pass tables directly to geoscatter

Create a plot by passing a table to the geoscatter function followed by the 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 geoscatter 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 scatter plot over the basemap. In R2022b, the basemap does not reset. In R2022a and earlier releases, the basemap resets to the default streets-light.

lat = [35 -22 51 39 37 42 47 -33];
lon = [139 -43 0 116 23 -71 -122 18];
 
figure
geobasemap streets
geoscatter(lat,lon,"filled")

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

lat = [35 -22 51 39 37 42 47 -33];
lon = [139 -43 0 116 23 -71 -122 18];
 
figure
geobasemap streets
cla reset
geoscatter(lat,lon,"filled")

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.