Line Geo

A line geo 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 geo plots are appropriate when the dataset contains geographic coordinates (latitude and longitude) or locations that connect across geographic areas. line_geo visualizes data using a basic map projection, without a high degree of detail. For richer tile maps, use line_map. For visualizing values at individual locations, consider using scatter_geo.

What are line geo plots useful for?

Geographic relationships: They are excellent for showing connections or relationships between different geographic locations, such as routes or paths.
Simple geographic context: Line geo plots provide a clear and straightforward way to visualize geographic data that does not require detailed map features.
Sequential geographic data: Line geo plots specialize in showing how data changes across connected geographic points over time or other ordered dimensions.

Examples

A basic line geo plot

Visualize geographic paths 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`")
line_geo_plot = dx.line_geo(
    single_flight,
    lat="Lat",
    lon="Lon",
    color_discrete_sequence="red",
    fitbounds="locations",
)

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
# fitbounds is set for better view
line_geo_plot = dx.line_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
line_geo_plot = dx.line_geo(
    flights_table,
    lat="Lat",
    lon="Lon",
    by="FlightId",
    projection="orthographic",
    scope="north america",
    center=dx.data.FLIGHT_CENTER
)

API Reference

Create a line_geo plot

Returns: DeephavenFigure A DeephavenFigure that contains the line_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, 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 \| list[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[float] \| 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[float] \| 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.
markers	bool	False	If True, markers are shown.
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.