Line Map

A line map plot is a geographic visualization that connects data points with lines on a map using latitude and longitude coordinates or locations. The lines are ideal for visualizing relationships between geographic locations such as paths or routes.

Line map plots are appropriate when the dataset contains geographic coordinates (latitude and longitude) or locations that connect across geographic areas. line_map visualizes data using detailed map tiles. For simpler projection maps, use line_geo. For visualizing values at individual locations, consider using scatter_map.

What are line map plots useful for?

Geographic relationships: They are excellent for showing connections or relationships between different geographic locations, such as routes or paths.
Detailed geographic context: Line map plots provide a rich and detailed way to visualize geographic data with map tile features.
Sequential geographic data: Line map plots specialize in showing how data changes across connected geographic points over time or other ordered dimensions.

Examples

A basic line map plot

Visualize geographic paths 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 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
# Zoom and center are set for better initial view
single_flight = flights_table.where("FlightId = `SAL101`")
line_map_plot = dx.line_map(
    single_flight,
    lat="Lat",
    lon="Lon",
    color_discrete_sequence="red",
    zoom=3,
    center=dx.data.FLIGHT_CENTER
)

Color by group

Denote different routes by using the color of the lines 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
# Zoom and center are set for better initial view
line_map_plot = dx.line_map(
    flights_table,
    lat="Lat",
    lon="Lon",
    by="FlightId",
    color_discrete_sequence=["red", "blue", "green", "orange"],
    zoom=3,
    center=dx.data.FLIGHT_CENTER
)

Customize map style

Use different base map styles with the map_style argument. The default style is dependent on the theme.

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)

# Change the map style for different tiles
# Zoom and center are set for better initial view
line_map_plot = dx.line_map(
    flights_table,
    lat="Lat",
    lon="Lon",
    by="FlightId",
    map_style="open-street-map",
    zoom=3,
    center=dx.data.FLIGHT_CENTER,
)

API Reference

Create a line_map plot

Returns: DeephavenFigure A DeephavenFigure that contains the line_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, line_dash, width, 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.
width	str \| list[str] \| None	None	A column or list of columns that contain width values. If only one column is passed, and it contains numeric values, the value is used as a width. Otherwise, the value is used for a plot by on width. See width_map for additional behaviors.
line_dash	str \| None	None	A column or list of columns that contain line_dash values. If only one column is passed, and it contains numeric values, the value is used as a line_dash. Otherwise, the value is used for a plot by on line_dash. See line_dash_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	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.
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 sizes, sizes will be reused. This is overriden if "size" is specified.
size_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.
width_sequence	list[int] \| None	None	A list of widths to sequentially apply to the markers in the series. The widths loop, so if there are more series than widths, widths will be reused. This is overriden if "width" is specified.
width_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.
line_dash_sequence	list[str] \| None	None	A list of line_dashes to sequentially apply to the markers in the series. The widths loop, so if there are more series than widths, widths will be reused. This is overriden if "line_dash" is specified.
line_dash_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 line_dash.
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.