Scatter Geo

A scatter geo plot is a geographic visualization that displays individual data points on a map using latitude and longitude coordinates or locations. The points are ideal for visualizing the distribution of data across geographic areas.

Scatter geo plots are appropriate when the dataset contains geographic coordinates (latitude and longitude) or locations that represent individual points on a map. scatter_geo visualizes data using a basic map projection, without a high degree of detail. For richer tile maps, use scatter_map. For visualizing connections between locations, consider using line_geo.

What are scatter geo plots useful for?

Geographic distribution: They are excellent for showing the distribution of individual geographic locations on a map.
Simple geographic context: Scatter geo plots provide a clear and straightforward way to visualize geographic data that does not require detailed map features.

Examples

A basic scatter geo plot

Visualize geographic points by passing longitude and latitude column names to the lon and lat arguments. It’s recommended to set fitbounds to "locations", which automatically adjusts the map view to include all points, unless a broader view is desired. Click and drag on the resulting map to pan and zoom.

import deephaven.plot.express as dx

# Load the flights dataset
# The speed_multiplier parameter speeds up the flight
flights_table = dx.data.flights(speed_multiplier=50)

# Plot a single flight path
# color is set for visibility
# fitbounds is set for better initial view
single_flight = flights_table.where("FlightId = `SAL101`")
scatter_geo_plot = dx.scatter_geo(
    single_flight,
    lat="Lat",
    lon="Lon",
    color_discrete_sequence="red",
    fitbounds="locations",
)

Color by group

Denote different categories by using the color of the points as group indicators by passing the grouping column name to the by argument. Set the color of each group using the color_discrete_sequence argument.

import deephaven.plot.express as dx

# Load the flights dataset
# The speed_multiplier parameter speeds up the flight
flights_table = dx.data.flights(speed_multiplier=50)

# Color each flight path differently
# fitbounds is set for better view
scatter_geo_plot = dx.scatter_geo(
    flights_table,
    lat="Lat",
    lon="Lon",
    by="FlightId",
    color_discrete_sequence=["red", "blue", "green", "orange"],
    fitbounds="locations",
)

Use different projections and scopes

Change the map projection using the projection argument. Options include “natural earth”, “mercator”, and “orthographic”. Adjust the geographic scope using the scope argument to focus on specific regions such as “world”, “usa”, “europe,” or “north american”. Set the center argument for a better initial view, especially when scoping to a specific region.

import deephaven.plot.express as dx

# Load the flights dataset
# The speed_multiplier parameter speeds up the flight
flights_table = dx.data.flights(speed_multiplier=50)

# Use an orthographic (globe) projection and set scope to North America
# center is set for better initial view
scatter_geo_plot = dx.scatter_geo(
    flights_table,
    lat="Lat",
    lon="Lon",
    by="FlightId",
    projection="orthographic",
    scope="north america",
    center=dx.data.FLIGHT_CENTER
)

API Reference

Create a scatter_geo plot

Returns: DeephavenFigure A DeephavenFigure that contains the scatter_geo figure

Parameters	Type	Default	Description
table	PartitionedTable \| Table \| DataFrame		A table to pull data from.
lat	str \| None	None	A column name to use for latitude values.
lon	str \| None	None	A column name to use for longitude values.
locations	str \| None	None	A column name to use for location values.
locationmode	str \| None	None	A location mode to use. One of ‘ISO-3’, ‘USA-states’, or ‘country names’. These map locations to predefined geographic regions.
geojson	str \| dict \| None	None	GeoJSON data to use for geographic regions.
featureidkey	str	'id'	The feature ID key to use for geographic regions.
by	str \| list[str] \| None	None	A column or list of columns that contain values to plot the figure traces by. All values or combination of values map to a unique design. The variable by_vars specifies which design elements are used. This is overriden if any specialized design variables such as color are specified
by_vars	str \| list[str]	'color'	A string or list of string that contain design elements to plot by. Can contain size, color, and symbol. If associated maps or sequences are specified, they are used to map by column values to designs. Otherwise, default values are used.
filter_by	str \| list[str] \| bool \| None	None	A column or list of columns that contain values to filter the chart by. If a boolean is passed and the table is partitioned, all partition key columns used to create the partitions are used. If no filters are specified, all partitions are shown on the chart.
required_filter_by	str \| list[str] \| bool \| None	None	A column or list of columns that contain values to filter the chart by. Values set in input filters or linkers for the relevant columns determine the exact values to display. If a boolean is passed and the table is partitioned, all partition key columns used to create the partitions are used. All required input filters or linkers must be set for the chart to display any data.
color	str \| list[str] \| None	None	A column or list of columns that contain color values. If only one column is passed, and it contains numeric values, the value is used as a value on a continuous color scale. Otherwise, the value is used for a plot by on color. See color_discrete_map for additional behaviors.
symbol	str \| list[str] \| None	None	A column or list of columns that contain symbol values. The value is used for a plot by on symbol. See color_discrete_map for additional behaviors.
size	str \| list[str] \| None	None	A column or list of columns that contain size values. If only one column is passed, and it contains numeric values, the value is used as a size. Otherwise, the value is used for a plot by on size. See size_map for additional behaviors.
text	str \| None	None	A column that contains text annotations.
hover_name	str \| None	None	A column that contains names to bold in the hover tooltip.
labels	dict[str, str] \| None	None	A dictionary of labels mapping columns to new labels.
color_discrete_sequence	str \| list[str] \| None	None	A list of colors to sequentially apply to the series. The colors loop, so if there are more series than colors, colors will be reused. This is overriden if "color" is specified.
color_discrete_map	str \| tuple[str, dict[str \| tuple[str], str]] \| dict[str \| tuple[str], str] \| None	None	If dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to colors. If "identity", the values are taken as literal colors. If "by" or ("by", dict) where dict is as described above, the colors are forced to by
symbol_sequence	list[str] \| None	None	A list of symbols to sequentially apply to the markers in the series. The symbols loop, so if there are more series than symbols, symbols will be reused. This is overriden if "symbol" is specified.
symbol_map	dict[str \| tuple[str], str] \| None	None	If dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to symbols.
size_sequence	list[int] \| None	None	A list of sizes to sequentially apply to the markers in the series. The sizes loop, so if there are more series than symbols, sizes will be reused. This is overriden if "size" is specified.
size_map	str \| tuple[str, dict[str \| tuple[str], str]] \| dict[str \| tuple[str], str] \| None	None	If dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to sizes. If "identity", the values are taken as literal sizes. If "by" or ("by", dict) where dict is as described above, the sizes are forced to by
color_continuous_scale	list[str] \| None	None	A list of colors for a continuous scale
range_color	list[float] \| None	None	A list of two numbers that form the endpoints of the color axis
color_continuous_midpoint	float \| None	None	A number that is the midpoint of the color axis
opacity	float \| None	None	Opacity to apply to all markers. 0 is completely transparent and 1 is completely opaque.
projection	str \| None	None	The projection type to use. Default depends on scope. One of 'equirectangular', 'mercator', 'orthographic', 'natural earth', 'kavrayskiy7', 'miller', 'robinson', 'eckert4', 'azimuthal equal area', 'azimuthal equidistant', 'conic equal area', 'conic conformal', 'conic equidistant', 'gnomonic', 'stereographic', 'mollweide', 'hammer', 'transverse mercator', 'albers usa', 'winkel tripel', 'aitoff', or 'sinusoidal'
scope	str \| None	None	The scope of the map. Default of 'world', but forced to 'usa' if projection is 'albers usa' One of 'world', 'usa', 'europe', 'asia', 'africa', 'north america', or 'south america'
center	dict[str, float] \| None	None	A dictionary of center coordinates. The keys should be 'lat' and 'lon' and the values should be floats that represent the lat and lon of the center of the map.
fitbounds	bool \| str	False	One of False, 'locations', or 'geojson' If 'locations' or 'geojson', the map will zoom to the extent of the locations or geojson bounds respectively.
basemap_visible	bool \| None	None	If True, the basemap layer is visible.
title	str \| None	None	The title of the chart
template	str \| None	None	The template for the chart.
unsafe_update_figure	Callable	<function default_callback>	An update function that takes a plotly figure as an argument and optionally returns a plotly figure. If a figure is not returned, the plotly figure passed will be assumed to be the return value. Used to add any custom changes to the underlying plotly figure. Note that the existing data traces should not be removed. This may lead to unexpected behavior if traces are modified in a way that break data mappings.