fix: DH-21259: Fix maps and add docs

plugins/plotly-express/docs/density-map.md

@@ -0,0 +1,106 @@
+# Density Map
+
+A density map plot is a geographic visualization that connects data points with a heatmap on a geographic map using latitude and longitude coordinates or locations. The heatmap is ideal for visualizing the density of data across geographic areas.
+
+Density map plots are appropriate when the dataset contains geographic coordinates (latitude and longitude) or locations that represent individual points on a map. `density_map` visualizes data using detailed map tiles. For visualizing individual points, use [`scatter_geo`](./scatter-geo.md) or [`scatter_map`](./scatter-map.md).
+
+## What are density map plots useful for?
+
+- **Geographic density**: They are excellent for showing the density of individual geographic locations on a map.
+- **Detailed geographic context**: Density map plots provide a rich and detailed way to visualize geographic data with map tile features.
+
+## Examples
+
+### A basic density map plot
+
+Visualize geographic density 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.
+
+```python order=density_map_plot,outages_table
+import deephaven.plot.express as dx
+
+# Load the outages dataset
+outages_table = dx.data.outages()
+
+# Create a density map showing concentration of outages
+# Zoom and center are set for better initial view
+density_map_plot = dx.density_map(
+    outages_table,
+    lat="Lat",
+    lon="Lon",
+    zoom=9,
+    center=dx.data.OUTAGE_CENTER
+)
+```
+
+### Adjust the density radius
+
+Control how spread out the density visualization appears using the `radius` argument.
+
+```python order=density_map_plot,outages_table
+import deephaven.plot.express as dx
+
+# Load the outages dataset
+outages_table = dx.data.outages()
+
+# Use a larger radius for a more diffuse heatmap
+# Zoom and center are set for better initial view
+density_map_plot = dx.density_map(
+    outages_table,
+    lat="Lat",
+    lon="Lon",
+    radius=10,
+    zoom=9,
+    center=dx.data.OUTAGE_CENTER
+)
+```
+
+### Customize the color scale
+
+Change the color scale using the `color_continuous_scale` argument.
+
+```python order=density_map_plot,outages_table
+import deephaven.plot.express as dx
+
+# Load the outages dataset
+outages_table = dx.data.outages()
+
+# Use a different color scale
+# Zoom and center are set for better initial view
+density_map_plot = dx.density_map(
+    outages_table,
+    lat="Lat",
+    lon="Lon",
+    color_continuous_scale=["yellow", "orange", "red"],
+    zoom=9,
+    center=dx.data.OUTAGE_CENTER
+)
+```
+
+### Change map style
+
+Use different base map styles with the `map_style` argument. The default style is dependent on the theme.
+
+```python order=density_map_plot,outages_table
+import deephaven.plot.express as dx
+
+# Load the outages dataset
+outages_table = dx.data.outages()
+
+# Change the map style for different tiles
+# Zoom and center are set for better initial view
+density_map_plot = dx.density_map(
+    outages_table,
+    lat="Lat",
+    lon="Lon",
+    map_style="open-street-map",
+    zoom=9,
+    center=dx.data.OUTAGE_CENTER
+)
+```
+
+## API Reference
+
+```{eval-rst}
+.. dhautofunction:: deephaven.plot.express.density_map
+```

plugins/plotly-express/docs/line-geo.md

@@ -0,0 +1,90 @@
+# 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`](./line-map.md). For visualizing values at individual locations, consider using [`scatter_geo`](./scatter-geo.md).
+
+## 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.
+
+```python order=line_geo_plot,flights_table
+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.
+
+```python order=line_geo_plot,flights_table
+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.
+
+```python order=line_geo_plot,flights_table
+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
+
+```{eval-rst}
+.. dhautofunction:: deephaven.plot.express.line_geo
+```

plugins/plotly-express/docs/line-map.md

@@ -0,0 +1,92 @@
+# 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`](./line-geo.md). For visualizing values at individual locations, consider using [`scatter_map`](./scatter-map.md).
+
+## 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.
+
+```python order=line_map_plot,flights_table
+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.
+
+```python order=line_map_plot,flights_table
+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.
+
+```python order=line_map_plot,flights_table
+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
+
+```{eval-rst}
+.. dhautofunction:: deephaven.plot.express.line_map
+```

plugins/plotly-express/docs/scatter-geo.md

@@ -0,0 +1,89 @@
+# 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`](./scatter-map.md). For visualizing connections between locations, consider using [`line_geo`](./line-geo.md).
+
+## 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.
+
+```python order=scatter_geo_plot,flights_table
+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.
+
+```python order=scatter_geo_plot,flights_table
+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.
+
+```python order=scatter_geo_plot,flights_table
+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
+
+```{eval-rst}
+.. dhautofunction:: deephaven.plot.express.scatter_geo
+```