fix: DH-21259: Fix maps and add docs #1279

jnumainville · 2025-12-30T19:35:21Z

Adds basic docs for map type charts.
Contains a fix for center, which was broken by default for scatter_map, line_map, and density_map.
Also modified default zoom to be 0 instead of 8 (which we did not specify but px sets this). A value of 0 will zoom out to the entire world, which makes more sense if you're not auto calculating the center based on data.

BREAKING CHANGE: scatter_map, line_map, and density_map now have an explicit default zoom of 0 instead of an implicit default zoom of 8. The default map style is now set based on the theme.

mofojed

Just some minor things to fix up, but some other thoughts/comments:

There's a lot of options here we're not showing (projection, map_style, zoom, center, etc). Not saying we need to show all of them, but one example showing a few of those other options would be great to show off the variety of things we can do. The options are already documented which is nice.
Maybe we should make a data generator like we have for stocks/fish_market to generate an interesting data set. Doing a wave with the lat/lon is okay, but it's not interesting. Having a data generator that generates something a little more interesting or having a couple options would be nice; e.g. even something that's just focused on one country (e.g. Canada 🍁 ) would be interesting and may drive home some of the differences in the examples. Like right now all the plots kind of start off looking the same, and even between line_map and line_geo, it's not clear the level of detail that is different on these maps since we're zoomed all the way out.

mofojed · 2025-12-31T15:39:11Z

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

+)
+
+# Create the density map plot
+# Color is set for better visibility


Colour isn't being set here, this comment is confusing.

Suggested change

# Color is set for better visibility

mofojed · 2025-12-31T15:39:22Z

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

+)
+
+# Create the density map plot
+# Color is set for better visibility


Suggested change

# Color is set for better visibility

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

mofojed · 2025-12-31T15:54:33Z

plugins/plotly-express/src/deephaven/plot/express/plots/_private_utils.py

+        if center is None:
+            # Set a default center to prevent px from auto-centering based on data
+            # which breaks the initial view for map plots since the data may be null initially
+            # Auto centering on the server side is also a bad idea since the data can change,


Hmm I could us wanting to auto-centre based on the data, when it ticks again... would that be possible? Any way to force Plotly to re-centre when we get a new tick if no centre is specified? I think that might be better than this... either way can file as a separate ticket.

I think that should be possible if done on the client (and using the JS API) and that was my future intention. I do think it's best to create another ticket for this so it can be properly designed as this is more of a quick fix. I just want to be intentional about it because, for example, we'll have to listen to user events on the map because if the user zooms, pans, etc. we don't want to keep auto centering.

Created DH-21351

jnumainville · 2026-01-05T18:28:42Z

I went for very surface level, basic docs to start so I'll work on a data generator and adding more detail.

github-actions · 2026-01-08T21:25:55Z

plotly-express docs preview (Available for 14 days)

Copilot

Pull request overview

This pull request fixes a bug with the center parameter in map-type charts and adds comprehensive documentation for map visualizations. The key changes include:

Fixed the center parameter default handling to prevent auto-centering based on null data, which broke initial map views
Changed default zoom from implicit 8 to explicit 0 (world view) for better initial visibility
Added two new data generator functions (outages() and flights()) to support map examples
Created documentation for five map chart types with examples and API references

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
`test_maps.py`	Updated test expectations to reflect new default center (0,0) and zoom (0) values
`maps.py`	Changed default zoom parameter from None to 0 and updated documentation strings
`_private_utils.py`	Added center parameter processing logic to set default (0,0) when None
`data_generators.py`	Added `outages()` and `flights()` data generator functions for map examples
`__init__.py`	Exported new data generator functions
`scatter-map.md`	Added documentation for scatter map visualizations
`scatter-geo.md`	Added documentation for scatter geo visualizations
`line-map.md`	Added documentation for line map visualizations
`line-geo.md`	Added documentation for line geo visualizations
`density-map.md`	Added documentation for density map visualizations (snapshot only)
`sidebar.json`	Added menu entries for new documentation pages
`*.json` (snapshots)	Added documentation snapshot files for testing

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

plugins/plotly-express/src/deephaven/plot/express/data/data_generators.py

mofojed

Change it to dx.data instead of dx_data. Styling questions for in demo this after.

Looks much better now overall though, thank you!

mofojed · 2026-01-09T14:46:37Z

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

+    lat="Lat",
+    lon="Lon",
+    zoom=9,
+    center={"lat": 44.97, "lon": -93.17}


These examples are much better, but it sucks that we have to provide the centre... has me yearning for DH-21259.
In Plotly's docs it looks like they have to provide the center as well: https://plotly.com/javascript/tile-density-heatmaps/
In their case looks like they just do somewhere in Africa so they can specify an easier to remember longitude (20)...
Can we at least provide this center as a constant in the data generator so we can just use that? e.g. dx.data.outages_center

I think providing the center is something lots of people are going to want to do anyways so I want this example to be illustrative of how it needs to be set. What about dx.data.OUTAGE_LAT and dx.data.OUTAGE_LON?

mofojed · 2026-01-09T14:47:30Z

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

+from deephaven.plot.express import data as dx_data
+
+# Load the outages dataset
+outages_table = dx_data.outages()


This is inconsistent with the rest of the docs, just reference it using dx.data instead of assigning data to it's own variable.

Suggested change

from deephaven.plot.express import data as dx_data

# Load the outages dataset

outages_table = dx_data.outages()

# Load the outages dataset

outages_table = dx.data.outages()

mofojed · 2026-01-09T14:52:38Z

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

+    outages_table,
+    lat="Lat",
+    lon="Lon",
+    color_discrete_sequence="black",


We should probably have different default colours for maps, as our colour is pretty close to that of water:

Make a ticket for that, unsure how easy it is to do a default for this and leave the other plots the same...
Or maybe we just want to default to map_style=dark, as that looks pretty cool with our default colours:

Let's ask Don in the demo this aft.

Attempted to set based on theme in deephaven/web-client-ui#2605

github-actions · 2026-01-09T18:22:51Z

plotly-express docs preview (Available for 14 days)

github-actions · 2026-01-09T23:20:23Z

plotly-express docs preview (Available for 14 days)

github-actions · 2026-01-10T00:01:46Z

plotly-express docs preview (Available for 14 days)

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

margaretkennedy · 2026-01-12T14:32:18Z

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

+
+### 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 america'. Set the `center` argument for a better initial view, especially when scoping to a specific region.


would it be better to use double quotes since that is what is used in the example? avoids any possible confusion

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

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

github-actions · 2026-01-12T15:47:47Z

plotly-express docs preview (Available for 14 days)

mofojed

Styles look good, everything looks good but I'd also do a FLIGHT_CENTER and/or OUTAGES_CENTER, seems a little cleaner for the data set usage.

mofojed · 2026-01-12T20:05:47Z

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

    lon="Lon",
    zoom=9,
-    center={"lat": 44.97, "lon": -93.17}
+    center={"lat": dx.data.OUTAGE_LAT, "lon": dx.data.OUTAGE_LON}


I kinda just want OUTAGE_CENTER, would make it more concise...

I suppose I don't oppose it that much. Easy enough to figure out the format. Done

@jnumainville We should be more informative/restrictive with the center type anyway. We should use a TypedDict for the center type instead of just a dict[str, float].

mofojed · 2026-01-12T20:06:12Z

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

    zoom=3,
-    center={"lat": 50, "lon": -100},
-    map_style="carto-darkmatter"
+    center={"lat": dx.data.FLIGHT_LAT, "lon": dx.data.FLIGHT_LON},


Ditto - FLIGHT_CENTER

github-actions · 2026-01-12T20:48:46Z

plotly-express docs preview (Available for 14 days)

This doesn't really block deephaven/deephaven-plugins#1279 but is used for it. I do think it's best to allow anyone to override the `map_style` in the theme if we want it to be allowed in the theme, although this method is a bit wonky so I'm not sure if it's the best way to do it.

jnumainville added 3 commits December 30, 2025 12:47

initial fix and docs

2e9fabf

fix tests

b68a931

remove AI slop

e4f78f1

jnumainville requested a review from mofojed December 30, 2025 19:35

github-actions bot requested a review from margaretkennedy December 30, 2025 19:35

mofojed requested changes Dec 31, 2025

View reviewed changes

jnumainville added 3 commits January 7, 2026 10:27

wip outages

64a4c89

update docs and generators

c539460

snapshots

6bc04f0

jnumainville requested review from Copilot and mofojed January 8, 2026 22:08

Copilot started reviewing on behalf of jnumainville January 8, 2026 22:08 View session

Copilot AI reviewed Jan 8, 2026

View reviewed changes

mofojed requested changes Jan 9, 2026

View reviewed changes

jnumainville added 2 commits January 9, 2026 11:30

wip

19dd49b

snapshots

63c7df3

comments and theme fix

973f19b

remove default map from tests

5d1067d

margaretkennedy reviewed Jan 12, 2026

View reviewed changes

docs

958dbd0

jnumainville mentioned this pull request Jan 12, 2026

feat: DH-21259: Add map_style to theme deephaven/web-client-ui#2605

Merged

jnumainville requested review from margaretkennedy and mofojed January 12, 2026 18:21

margaretkennedy previously approved these changes Jan 12, 2026

View reviewed changes

mofojed requested changes Jan 12, 2026

View reviewed changes

switch to center

af9d4ae

jnumainville dismissed margaretkennedy’s stale review via af9d4ae January 12, 2026 20:26

updated snapshots

431c6c6

jnumainville enabled auto-merge (squash) January 12, 2026 21:38

jnumainville requested a review from mofojed January 12, 2026 21:38

mofojed approved these changes Jan 12, 2026

View reviewed changes

jnumainville merged commit 99656a9 into deephaven:main Jan 12, 2026
17 checks passed


		### 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 america'. Set the `center` argument for a better initial view, especially when scoping to a specific region.

fix: DH-21259: Fix maps and add docs #1279

fix: DH-21259: Fix maps and add docs #1279

Uh oh!

Conversation

jnumainville commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mofojed left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jnumainville Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jnumainville commented Jan 5, 2026

Uh oh!

github-actions bot commented Jan 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mofojed left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 9, 2026

Uh oh!

github-actions bot commented Jan 9, 2026

Uh oh!

github-actions bot commented Jan 10, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jan 12, 2026

Uh oh!

mofojed left a comment

Choose a reason for hiding this comment

Uh oh!

jnumainville commented Dec 30, 2025 •

edited

Loading

jnumainville Jan 5, 2026 •

edited

Loading

jnumainville Jan 12, 2026 •

edited

Loading