Merge pull request #5358 from ajlien/update-hexbin-map-no-mapbox

create_hexbin_mapbox uses *_map chart types instead of *_mapbox

Author: emilykl

doc/apidoc/plotly.figure_factory.rst

@@ -18,7 +18,7 @@
    create_distplot
    create_facet_grid
    create_gantt
-   create_hexbin_mapbox
+   create_hexbin_map
    create_ohlc
    create_quiver
    create_scatterplotmatrix

doc/python/hexbin-mapbox.md

@@ -37,16 +37,13 @@ jupyter:
 
 This page details the use of a [figure factory](/python/figure-factories/). For more examples with Choropleth maps, see [this page](/python/choropleth-maps/).
 
-In order to use mapbox styles that require a mapbox token, set the token with `plotly.express`. You can also use styles that do not require a mapbox token. See more information on [this page](/python/mapbox-layers/).
-
 ```python
 import plotly.figure_factory as ff
 import plotly.express as px
 
-px.set_mapbox_access_token(open(".mapbox_token").read())
 df = px.data.carshare()
 
-fig = ff.create_hexbin_mapbox(
+fig = ff.create_hexbin_map(
     data_frame=df, lat="centroid_lat", lon="centroid_lon",
     nx_hexagon=10, opacity=0.9, labels={"color": "Point Count"},
 )
@@ -60,10 +57,9 @@ fig.show()
 import plotly.figure_factory as ff
 import plotly.express as px
 
-px.set_mapbox_access_token(open(".mapbox_token").read())
 df = px.data.carshare()
 
-fig = ff.create_hexbin_mapbox(
+fig = ff.create_hexbin_map(
     data_frame=df, lat="centroid_lat", lon="centroid_lon",
     nx_hexagon=10, opacity=0.5, labels={"color": "Point Count"},
     min_count=1,
@@ -77,10 +73,9 @@ fig.show()
 import plotly.figure_factory as ff
 import plotly.express as px
 
-px.set_mapbox_access_token(open(".mapbox_token").read())
 df = px.data.carshare()
 
-fig = ff.create_hexbin_mapbox(
+fig = ff.create_hexbin_map(
     data_frame=df, lat="centroid_lat", lon="centroid_lon",
     nx_hexagon=10, opacity=0.5, labels={"color": "Point Count"},
     min_count=1, color_continuous_scale="Viridis",
@@ -97,10 +92,9 @@ import plotly.figure_factory as ff
 import plotly.express as px
 import numpy as np
 
-px.set_mapbox_access_token(open(".mapbox_token").read())
 df = px.data.carshare()
 
-fig = ff.create_hexbin_mapbox(
+fig = ff.create_hexbin_map(
     data_frame=df, lat="centroid_lat", lon="centroid_lon",
     nx_hexagon=10, opacity=0.9, labels={"color": "Average Peak Hour"},
     color="peak_hour", agg_func=np.mean, color_continuous_scale="Icefire", range_color=[0,23]
@@ -115,10 +109,9 @@ import plotly.figure_factory as ff
 import plotly.express as px
 import numpy as np
 
-px.set_mapbox_access_token(open(".mapbox_token").read())
 df = px.data.carshare()
 
-fig = ff.create_hexbin_mapbox(
+fig = ff.create_hexbin_map(
     data_frame=df, lat="centroid_lat", lon="centroid_lon",
     nx_hexagon=10, opacity=0.9, labels={"color": "Summed Car.Hours"},
     color="car_hours", agg_func=np.sum, color_continuous_scale="Magma"
@@ -133,7 +126,6 @@ import plotly.figure_factory as ff
 import plotly.express as px
 import numpy as np
 
-px.set_mapbox_access_token(open(".mapbox_token").read())
 np.random.seed(0)
 
 N = 500
@@ -150,7 +142,7 @@ frame = np.concatenate([
     np.ones(N, int) * i for i in range(n_frames)
 ])
 
-fig = ff.create_hexbin_mapbox(
+fig = ff.create_hexbin_map(
     lat=lat, lon=lon, nx_hexagon=15, animation_frame=frame,
     color_continuous_scale="Cividis", labels={"color": "Point Count", "frame": "Period"},
     opacity=0.5, min_count=1,

plotly/figure_factory/__init__.py

@@ -29,12 +29,18 @@
 
 if optional_imports.get_module("pandas") is not None:
     from plotly.figure_factory._county_choropleth import create_choropleth
-    from plotly.figure_factory._hexbin_mapbox import create_hexbin_mapbox
+    from plotly.figure_factory._hexbin_map import (
+        create_hexbin_map,
+        create_hexbin_mapbox,
+    )
 else:
 
     def create_choropleth(*args, **kwargs):
         raise ImportError("Please install pandas to use `create_choropleth`")
 
+    def create_hexbin_map(*args, **kwargs):
+        raise ImportError("Please install pandas to use `create_hexbin_map`")
+
     def create_hexbin_mapbox(*args, **kwargs):
         raise ImportError("Please install pandas to use `create_hexbin_mapbox`")
 
@@ -57,6 +63,7 @@ def create_ternary_contour(*args, **kwargs):
     "create_distplot",
     "create_facet_grid",
     "create_gantt",
+    "create_hexbin_map",
     "create_hexbin_mapbox",
     "create_ohlc",
     "create_quiver",

plotly/figure_factory/_hexbin_mapbox.py renamed to plotly/figure_factory/_hexbin_map.py

@@ -1,8 +1,9 @@
 from plotly.express._core import build_dataframe
 from plotly.express._doc import make_docstring
-from plotly.express._chart_types import choropleth_mapbox, scatter_mapbox
+from plotly.express._chart_types import choropleth_map, scatter_map
 import narwhals.stable.v1 as nw
 import numpy as np
+import warnings
 
 
 def _project_latlon_to_wgs84(lat, lon):
@@ -322,7 +323,7 @@ def _hexagons_to_geojson(hexagons_lats, hexagons_lons, ids=None):
     return dict(type="FeatureCollection", features=features)
 
 
-def create_hexbin_mapbox(
+def create_hexbin_map(
     data_frame=None,
     lat=None,
     lon=None,
@@ -339,7 +340,7 @@ def create_hexbin_mapbox(
     opacity=None,
     zoom=None,
     center=None,
-    mapbox_style=None,
+    map_style=None,
     title=None,
     template=None,
     width=None,
@@ -444,9 +445,12 @@ def create_hexbin_mapbox(
     )
 
     if range_color is None:
-        range_color = [agg_data_frame["color"].min(), agg_data_frame["color"].max()]
+        range_color = [
+            agg_data_frame["color"].min(),
+            agg_data_frame["color"].max(),
+        ]
 
-    fig = choropleth_mapbox(
+    fig = choropleth_map(
         data_frame=agg_data_frame.to_native(),
         geojson=geojson,
         locations="locations",
@@ -462,18 +466,20 @@ def create_hexbin_mapbox(
         opacity=opacity,
         zoom=zoom,
         center=center,
-        mapbox_style=mapbox_style,
+        map_style=map_style,
         title=title,
         template=template,
         width=width,
         height=height,
     )
 
     if show_original_data:
-        original_fig = scatter_mapbox(
+        original_fig = scatter_map(
             data_frame=(
                 args["data_frame"].sort(
-                    by=args["animation_frame"], descending=False, nulls_last=True
+                    by=args["animation_frame"],
+                    descending=False,
+                    nulls_last=True,
                 )
                 if args["animation_frame"] is not None
                 else args["data_frame"]
@@ -502,8 +508,8 @@ def create_hexbin_mapbox(
     return fig
 
 
-create_hexbin_mapbox.__doc__ = make_docstring(
-    create_hexbin_mapbox,
+create_hexbin_map.__doc__ = make_docstring(
+    create_hexbin_map,
     override_dict=dict(
         nx_hexagon=["int", "Number of hexagons (horizontally) to be created"],
         agg_func=[
@@ -521,6 +527,20 @@ def create_hexbin_mapbox(
             "bool",
             "Whether to show the original data on top of the hexbin aggregation.",
         ],
-        original_data_marker=["dict", "Scattermapbox marker options."],
+        original_data_marker=["dict", "Scattermap marker options."],
     ),
 )
+
+
+def create_hexbin_mapbox(*args, **kwargs):
+    warnings.warn(
+        "create_hexbin_mapbox() is deprecated and will be removed in the next major version. "
+        + "Please use create_hexbin_map() instead. "
+        + "Learn more at: https://plotly.com/python/mapbox-to-maplibre/",
+        stacklevel=2,
+        category=DeprecationWarning,
+    )
+    if "mapbox_style" in kwargs:
+        kwargs["map_style"] = kwargs.pop("mapbox_style")
+
+    return create_hexbin_map(*args, **kwargs)

tests/test_optional/test_figure_factory/test_figure_factory.py

@@ -4228,7 +4228,7 @@ def test_aggregation(self):
         lon = [1, 2, 3, 3, 0, 4, 5, 0, 5, 3, 1, 5, 4, 0, 1, 2, 5]
         color = np.ones(len(lat))
 
-        fig1 = ff.create_hexbin_mapbox(lat=lat, lon=lon, nx_hexagon=1)
+        fig1 = ff.create_hexbin_map(lat=lat, lon=lon, nx_hexagon=1)
 
         actual_geojson = {
             "type": "FeatureCollection",
@@ -4331,7 +4331,7 @@ def test_aggregation(self):
         self.compare_dict_values(fig1.data[0].geojson, actual_geojson)
         assert np.array_equal(fig1.data[0].z, actual_agg)
 
-        fig2 = ff.create_hexbin_mapbox(
+        fig2 = ff.create_hexbin_map(
             lat=lat,
             lon=lon,
             nx_hexagon=1,
@@ -4341,7 +4341,7 @@ def test_aggregation(self):
 
         assert np.array_equal(fig2.data[0].z, np.ones(5))
 
-        fig3 = ff.create_hexbin_mapbox(
+        fig3 = ff.create_hexbin_map(
             lat=np.random.randn(1000),
             lon=np.random.randn(1000),
             nx_hexagon=20,
@@ -4364,8 +4364,8 @@ def test_build_dataframe(self):
             columns=["Latitude", "Longitude", "Metric", "Frame"],
         )
 
-        fig1 = ff.create_hexbin_mapbox(lat=lat, lon=lon, nx_hexagon=nx_hexagon)
-        fig2 = ff.create_hexbin_mapbox(
+        fig1 = ff.create_hexbin_map(lat=lat, lon=lon, nx_hexagon=nx_hexagon)
+        fig2 = ff.create_hexbin_map(
             data_frame=df, lat="Latitude", lon="Longitude", nx_hexagon=nx_hexagon
         )
 
@@ -4375,22 +4375,22 @@ def test_build_dataframe(self):
             fig1.to_plotly_json()["data"][0], fig2.to_plotly_json()["data"][0]
         )
 
-        fig3 = ff.create_hexbin_mapbox(
+        fig3 = ff.create_hexbin_map(
             lat=lat,
             lon=lon,
             nx_hexagon=nx_hexagon,
             color=color,
             agg_func=np.sum,
             min_count=0,
         )
-        fig4 = ff.create_hexbin_mapbox(
+        fig4 = ff.create_hexbin_map(
             lat=lat,
             lon=lon,
             nx_hexagon=nx_hexagon,
             color=color,
             agg_func=np.sum,
         )
-        fig5 = ff.create_hexbin_mapbox(
+        fig5 = ff.create_hexbin_map(
             data_frame=df,
             lat="Latitude",
             lon="Longitude",
@@ -4406,7 +4406,7 @@ def test_build_dataframe(self):
             fig4.to_plotly_json()["data"][0], fig5.to_plotly_json()["data"][0]
         )
 
-        fig6 = ff.create_hexbin_mapbox(
+        fig6 = ff.create_hexbin_map(
             data_frame=df,
             lat="Latitude",
             lon="Longitude",
@@ -4416,7 +4416,7 @@ def test_build_dataframe(self):
             animation_frame="Frame",
         )
 
-        fig7 = ff.create_hexbin_mapbox(
+        fig7 = ff.create_hexbin_map(
             lat=lat,
             lon=lon,
             nx_hexagon=nx_hexagon,