geopandas.datasets is deprecated (#3043)

doc/user_guide/marks/geoshape.rst

@@ -12,16 +12,17 @@ A ``geoshape`` mark can contain any :ref:`standard mark properties <mark-propert
 
 Basic Map
 ^^^^^^^^^
-Altair can work with many different geographical data formats, including geojson and topojson files. Often, the most convenient input format to use is a ``GeoDataFrame``. Here we load the Natural Earth dataset and create a basic map using ``mark_geoshape``:
+Altair can work with many different geographical data formats, including geojson and topojson files. Often, the most convenient input format to use is a ``GeoDataFrame``. Here we load the Natural Earth 110m Cultural Vectors dataset and create a basic map using ``mark_geoshape``:
 
 .. altair-plot::
 
     import altair as alt
     from vega_datasets import data
     import geopandas as gpd
 
-    fp = gpd.datasets.get_path('naturalearth_lowres')
-    gdf_ne = gpd.read_file(fp)  # shapefile
+    url = "https://naciscdn.org/naturalearth/110m/cultural/ne_110m_admin_0_countries.zip"
+    gdf_ne = gpd.read_file(url)  # zipped shapefile
+    gdf_ne = gdf_ne[["NAME", "CONTINENT", "POP_EST", 'geometry']]
 
     alt.Chart(gdf_ne).mark_geoshape()
 
@@ -51,7 +52,7 @@ The following examples applies these approaches to focus on continental Africa:
 
 .. altair-plot::
 
-    gdf_sel = gdf_ne[gdf_ne.continent == 'Africa']
+    gdf_sel = gdf_ne.query("CONTINENT == 'Africa'")
 
     alt.Chart(gdf_sel).mark_geoshape()
 
@@ -60,7 +61,7 @@ The following examples applies these approaches to focus on continental Africa:
 .. altair-plot::
 
     alt.Chart(gdf_ne).mark_geoshape().transform_filter(
-        alt.datum.continent == 'Africa'
+        alt.datum.CONTINENT == 'Africa'
     )
 
 3. Specify ``scale`` (zoom level) and ``translate`` (panning) within the ``project`` method:
@@ -76,10 +77,10 @@ The following examples applies these approaches to focus on continental Africa:
 
 .. altair-plot::
 
-    extent_roi = gdf_ne.query("continent == 'Africa'")
+    extent_roi = gdf_ne.query("CONTINENT == 'Africa'")
     xmin, ymin, xmax, ymax = extent_roi.total_bounds
 
-    # fit object should be an array of GeoJSON-like features
+    # fit object should be a GeoJSON-like Feature or FeatureCollection 
     extent_roi_feature = {
         "type": "Feature", 
         "geometry": {"type": "Polygon", 
@@ -112,12 +113,12 @@ In the following example the input geometry is not projected and is instead rend
 
 Mapping Polygons
 ^^^^^^^^^^^^^^^^
-The following example maps the visual property of the ``name`` column using the ``color`` encoding.
+The following example maps the visual property of the ``NAME`` column using the ``color`` encoding.
 
 .. altair-plot::
 
     alt.Chart(gdf_sel).mark_geoshape().encode(
-        color='name:N'
+        color='NAME:N'
     )
 
 Since each country is represented by a (multi)polygon, we can separate the ``stroke`` and ``fill`` definitions as such:
@@ -128,7 +129,7 @@ Since each country is represented by a (multi)polygon, we can separate the ``str
         stroke='white',
         strokeWidth=1.5
     ).encode(
-        fill='name:N'
+        fill='NAME:N'
     )
 
 Mapping Lines
@@ -166,7 +167,7 @@ Using this approach one can also style Polygons as if they are Linestrings:
         filled=False,
         strokeWidth=1.5
     ).encode(
-        stroke='name:N'
+        stroke='NAME:N'
     )
 
 Mapping Points
@@ -194,7 +195,7 @@ Caveat: To use the ``size`` encoding for the Points you will need to use the ``m
     gdf_centroid["lat"] = gdf_centroid.geometry.y
 
     alt.Chart(gdf_centroid).mark_circle().encode(
-        longitude="lon:Q", latitude="lat:Q", size="pop_est:Q"
+        longitude="lon:Q", latitude="lat:Q", size="POP_EST:Q"
     )
 
 Altair also contains expressions related to geographical features. We can for example define the ``centroids`` using a ``geoCentroid`` expression:
@@ -214,7 +215,7 @@ Altair also contains expressions related to geographical features. We can for ex
     ).encode(
         longitude='centroid[0]:Q',
         latitude='centroid[1]:Q',
-        size="pop_est:Q"
+        size="POP_EST:Q"
     )
 
     (basemap + bubbles).project(
@@ -229,7 +230,7 @@ An alternative to showing the population sizes as bubbles, is to create a "Choro
 .. altair-plot::
 
     alt.Chart(gdf_sel).mark_geoshape().encode(
-        color='pop_est'
+        color='POP_EST'
     )
 
 When we create choropleth maps, we need to be careful, because although the color changes according to the value of the column we are interested in, the size is tied to the area of each country and we might miss interesting values in small countries just because we can't easily see them on the map (e.g. if we were to visualize population density).