Move the geospatial section in the "Specifying data" page to the geoshape mark page

[joelostblom]

I think we should move everything from the heading "Graticule generator" and down to the geoshape mark page. Although (some of) this section is technically about specifying data, I think it is more intuitive for readers to find all the info about how to work with geographical data in one place in the Altair documentation. The rest of the "Specifying data" page is relevant for almost all readers as they lay a foundation for how to use data with most marks in altair, but the geoparts are specific to just the geoshape and feels a bit out of place to me (and at the same time harder to find for readers who want to work with only geo data).

Possibly we could have a heading "Working with geographical data" which just links to the geoshape mark page so that we improve the discoverability of this page (which I think would be helpful since it is a little bit hidden under the "marks" section, I'm even considering a separate side bar item for geoviz like the Time side bar item we have now.).

@mattijn @binste Thoughts on this?

[mattijn]

I think we should keep the mark geoshape page about the mark geoshape options.

But I also agree it would be good to have a section on defining spatial data. I really like the current structure of nested options below Marks and Transformations (although I wished they are not collapsed by default).
Maybe we can set up something similar for the Specifying Data section?

I mentioned this before in this issue from a while ago:

By the way, in the docs of Vega-Lite there are no options under Data / Datasets:

I think there should be some sub-options, especially for Altair.

There we can then have a section named Spatial Data and place these GeoPandas and Graticule/Sphere generator sections and info from this SO-answer and also some info how to use the :G encoding, with a simplified of #2727 (comment).

But in this Specifying Data section I wish there also is a section how to use eg. dict with Altair. Pandas is great, but Dicts? Mindblowing;)!

Btw, I prefer the name Spatial Data over Geographical data, since there are many things spatially related but not necessarily geographical:

import altair as alt

data = [
    {"color": "#F3C14F", "geo": {"type": "Feature", "geometry": {"type": "Polygon", "coordinates": [[[1.45, 3.75], [1.45, 0], [0, 0], [1.45, 3.75]]]}}},
    {"color": "#4098D7", "geo": {"type": "Feature", "geometry": {"type": "Polygon", "coordinates": [[[1.45, 0], [1.45, 3.75], [2.57, 3.75], [2.57, 0], [2.33, 0], [1.45, 0]]]}}},
    {"color": "#66B4E2", "geo": {"type": "Feature", "geometry": {"type": "Polygon", "coordinates": [[[2.33, 0], [2.33, 2.5], [3.47, 2.5], [3.47, 0], [3.2, 0], [2.57, 0], [2.33, 0]]]}}},
    {"color": "#A9CDE0", "geo": {"type": "Feature", "geometry": {"type": "Polygon", "coordinates": [[[3.2, 0], [3.2, 1.25], [4.32, 1.25], [4.32, 0], [3.47, 0], [3.2, 0]]]}}},
]
source = alt.Data(values=data)

alt.Chart(source, title="Vega-Altair").mark_geoshape().encode(
    shape="geo:G", 
    color=alt.Color("color:N", scale=None)
).project(type="identity", reflectY=True)

[joelostblom]

I really like the current structure of nested options below Marks and Transformations (although I wished they are not collapsed by default). Maybe we can set up something similar for the Specifying Data section?

That sounds like a great idea! Based on what I see on the VegaLite Data page, the relevant sections for Altair might be Dictionary, Dataframe, URL, Spatial and Generator? I don't think we need the format, and datasets section?

There we can then have a section named Spatial Data and place these GeoPandas and Graticule/Sphere generator sections and info from this SO-answer and also some info how to use the :G encoding, with a simplified of #2727 (comment).

Yes, that would be super useful!

Btw, I prefer the name Spatial Data over Geographical data, since there are many things spatially related but not necessarily geographical

That sounds more appropriate. Maybe also including that exxample you made somewhere as a basic intro?

Would you be willing to take this on whenever you have time to work on it?