diff --git a/doc/apidoc/plotly.figure_factory.rst b/doc/apidoc/plotly.figure_factory.rst index 44f44b8d36c..be2a4613abf 100644 --- a/doc/apidoc/plotly.figure_factory.rst +++ b/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 diff --git a/doc/python/hexbin-mapbox.md b/doc/python/hexbin-mapbox.md index ed30f329774..079b337f952 100644 --- a/doc/python/hexbin-mapbox.md +++ b/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, diff --git a/plotly/figure_factory/__init__.py b/plotly/figure_factory/__init__.py index 1919ca875f3..c0ded37ca28 100644 --- a/plotly/figure_factory/__init__.py +++ b/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", diff --git a/plotly/figure_factory/_hexbin_mapbox.py b/plotly/figure_factory/_hexbin_map.py similarity index 93% rename from plotly/figure_factory/_hexbin_mapbox.py rename to plotly/figure_factory/_hexbin_map.py index c76352248b0..792cae5e238 100644 --- a/plotly/figure_factory/_hexbin_mapbox.py +++ b/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,7 +466,7 @@ def create_hexbin_mapbox( opacity=opacity, zoom=zoom, center=center, - mapbox_style=mapbox_style, + map_style=map_style, title=title, template=template, width=width, @@ -470,10 +474,12 @@ def create_hexbin_mapbox( ) 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) diff --git a/tests/test_optional/test_figure_factory/test_figure_factory.py b/tests/test_optional/test_figure_factory/test_figure_factory.py index f131bacdc5e..91aee8d4a00 100644 --- a/tests/test_optional/test_figure_factory/test_figure_factory.py +++ b/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,7 +4375,7 @@ 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, @@ -4383,14 +4383,14 @@ def test_build_dataframe(self): 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,