Improve documentation on geographical visualizations

There is currently some information on this at the end of the “Specifying data” section of the user guide and in the Examples Gallery. I think it would be great to have a dedicated documentation page in the user guide for geographical visualization in Altair that includes more extensive examples and more hand-holding to get started (this could be place just above the temporal data page). Here are the main ideas I have around this:

1. Ideally, we can use the UWdata viz curriculum as a base, I will ask if this is OK (edit: approved in this comment).
2. Working with different geodata sources. I don’t have much experience with geo data or the __geo_interface__, but I think it would be really helpful to show how to work with geojson, geopandas, and shapely (any others I missed?). I imagine this could involve showing how to read data from each source up until a common point from which they are all treated the same in Altair (this reflects my limited understanding of https://github.com/altair-viz/altair/pull/1664, which is that we can read all these formats and then work with them the same way in Altair). This could also include Plotting points with long lat on a GeoPandas background.
   • I think one of these glowing heatmaps would be a really cool example, like the NY taxi one from datashader or this tutorial using matplotlib (I guess really anything using that firey colorscheme on a dark background, not sure if VL has a similar one).
3. Subsetting which countries are shown in a map. Is there an easy way to do this that is not simply zooming in? Can we filter the Geo data when reading it in? Or can we use a filter transform in altair using the IDs/Names of the geo objects/states/countries?
4. Add an interactive narrative example in the user guide, I have material that gradually builds up to this viz.
   • To link the geodata source to another table with a transform_lookup, it seems like we need to use the IDs of the geojson objects. These IDs exists in the employment data set for the US states, but nowhere for the world data. I think it would be nice to provide these IDs in separate example datasets so that they are easily available for people. Maybe this should go into VegaDatasets eventually, but in the meantime I can link to where I know they exist.

Thoughts on this? @mattijn from what I can see you are the geo-viz expert so would love to hear your ideas and if you would have time to contribute some of this based on your previous material (particularly point 2-3).

[mattijn]

Great! I made a start yesterday, you can see what I did here: https://github.com/joelostblom/altair/pull/1. It includes a few approaches how to use mark_geoshape. You could iterate from there or use it as inspirational material if you have something else in mind.

[mattijn]

Regarding the __geo_interface__, yes, this is an common protocol for geopackages and builds on GeoJSON. Just like there is an __array_inferface__ in Numpy. But to improve documentation on geographical materials I would not focus on this interface, but just stick to the package GeoPandas. Its a joy to work with and it just works for almost any spatial data source. In Vega/VL there are multiple examples based on TopoJSON and while I created a python package for it, I would not advocate to use this format in examples for geo-vizs in the Altair docs. Keep it simple, GeoPandas DataFrames are great.

There is one reason though, why GeoPandas examples are currently not included in the docs. It creates another dependency and the package is not easily pip-installed, but requires more a conda-forge-installation (since its dependency on GEOS, just like Shapely).

This heatmaps you link to are currently not really an option in Altair. I think it goes as wide to anything that is shown by plt.imshow in matplotlib. In Vega there are nice examples already, such as https://vega.github.io/vega/examples/density-heatmaps/ (using kd2d and heatmap transform) and a geo-one using array-data https://vega.github.io/vega/examples/annual-precipitation/ (using isocontours transform), but its still stuck for VL at https://github.com/vega/vega-lite/issues/6043. Just like support for basemaps, https://github.com/vega/vega-lite/issues/5758

For filtering and zooming. If possible, I would do the filtering in the GeoDataFrame, but to include an example of a map and a binded selection makes sense.

A few examples how to do interactions will be helpful. This is how many people use maps, in combination with another chart. Examples on lookup, both ways and including aggregation.

Existing examples in the issues we could build on: https://github.com/altair-viz/altair/issues/2203 # add points from within geodataframe geom https://github.com/altair-viz/altair/issues/1357 # interesting approach for lookup the geom. https://github.com/altair-viz/altair/issues/2458#issuecomment-823636878 # reading raw GeoJSON https://stackoverflow.com/a/55950538/2459096 # differences between GeoJSON, TopoJSON, so complicated https://github.com/altair-viz/altair/issues/1647#issuecomment-581289833 # projected/unprojected data.

Sure like to help with stuff. Also need to see if we can agree on including GeoPandas as a package in the docs, ping @jakevdp.