Scatter Map

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 map plots are appropriate when the dataset contains geographic coordinates (latitude and longitude) or locations that represent individual points on a map. scatter_map visualizes data using detailed map tiles. For simpler projection maps, use scatter_geo. For visualizing connections between locations, consider using line_map.

What are scatter map plots useful for?

Geographic distribution: They are excellent for showing the distribution of individual geographic locations on a map.
Detailed geographic context: Scatter map plots provide a rich and detailed way to visualize geographic data with map tile features.

Examples

A basic scatter map plot

Visualize geographic points by passing longitude and latitude column names to the lon and lat arguments. It’s recommended to set the initial zoom level and center coordinates for better visualization based on the data. Click and drag on the resulting map to pan and zoom.

import deephaven.plot.express as dx

# Load the outages dataset
outages_table = dx.data.outages()

# Create a scatter map showing individual outage points
# Color is set for visibility
# Zoom and center are set for better initial view
scatter_map_plot = dx.scatter_map(
    outages_table,
    lat="Lat",
    lon="Lon",
    color_discrete_sequence="black",
    zoom=9,
    center=dx.data.OUTAGE_CENTER
)

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 outages dataset
outages_table = dx.data.outages().sort_descending("Severity")

# Color each outage point differently based on the cause
# Zoom and center are set for better initial view
scatter_map_plot = dx.scatter_map(
    outages_table,
    lat="Lat",
    lon="Lon",
    by="Severity",
    color_discrete_sequence=["black", "blue", "purple", "green"],
    zoom=9,
    center=dx.data.OUTAGE_CENTER
)

API Reference

Create a scatter_map plot

Returns: DeephavenFigure A DeephavenFigure that contains the scatter_map 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.
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.
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.
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 is "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.
zoom	float \| None	0	The zoom level of the map. 0 is the whole world, and higher values zoom in closer.
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.
map_style	str \| None	None	The style of the map. Defaults to None, which uses the theme's default. If a str, one of 'basic', 'carto-darkmatter', 'carto-darkmatter-nolabels', 'carto-positron', 'carto-positron-nolabels', 'carto-voyager', 'carto-voyager-nolabels', 'dark', 'light', 'open-street-map', 'outdoors', 'satellite', 'satellite-streets', 'streets', 'white-bg'.
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.