diff --git a/doc/python/axes.md b/doc/python/axes.md index df8672e0e2..82dca682b2 100644 --- a/doc/python/axes.md +++ b/doc/python/axes.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.3' - jupytext_version: 1.16.3 + jupytext_version: 1.17.2 kernelspec: display_name: Python 3 (ipykernel) language: python @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.10.14 + version: 3.9.0 plotly: description: How to adjust axes properties in Python - axes titles, styling and coloring axes and grid lines, ticks, tick labels and more. @@ -619,6 +619,38 @@ fig.update_yaxes(zeroline=True, zerolinewidth=2, zerolinecolor='LightPink') fig.show() ``` +##### Controlling Zero Line Layer + +*New in 6.3* + +By default, zero lines are displayed below traces. Set `zerolinelayer="above traces"` on an axis to display its zero line above traces: + +```python +import plotly.graph_objects as go + +x = ['A', 'B', 'C', 'D', 'A'] +y = [2, 0, 4, -3, 2] + +fig = go.Figure( + data=[ + go.Scatter( + x=x, + y=y, + fill='toself', + mode='none', + fillcolor='lightpink' + ) + ], + layout=dict( + yaxis=dict( + zerolinelayer="above traces" # Change to "below traces" to see the difference + ), + ) +) + +fig.show() +``` + #### Setting the Range of Axes Manually The visible x and y axis range can be configured manually by setting the `range` axis property to a list of two values, the lower and upper bound. diff --git a/doc/python/choropleth-maps.md b/doc/python/choropleth-maps.md index e38e51befd..7f9984478f 100644 --- a/doc/python/choropleth-maps.md +++ b/doc/python/choropleth-maps.md @@ -208,15 +208,16 @@ fig.show() Plotly comes with two built-in geometries which do not require an external GeoJSON file: 1. USA States -2. Countries as defined in the Natural Earth dataset. +2. Countries -**Note and disclaimer:** cultural (as opposed to physical) features are by definition subject to change, debate and dispute. Plotly includes data from Natural Earth "as-is" and defers to the [Natural Earth policy regarding disputed borders](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/) which read: +In **Plotly.py 6.3 and later**, the built-in countries geometry is created from the following sources: +- [UN data](https://geoportal.un.org/arcgis/sharing/rest/content/items/d7caaff3ef4b4f7c82689b7c4694ad92/data) for country borders, coastlines, land, and ocean layers. +- Natural Earth data for lakes, rivers, and subunits layers. -> Natural Earth Vector draws boundaries of countries according to defacto status. We show who actually controls the situation on the ground. +In **earlier versions of Plotly.py**, the built-in countries geometry is based on Natural Earth data only. Plotly includes data from Natural Earth "as-is". This dataset draws boundaries of countries according to de facto status. See the [Natural Earth page for more details](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/). To use the built-in countries geometry, provide `locations` as [three-letter ISO country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3). - ```python import plotly.express as px diff --git a/doc/python/configuration-options.md b/doc/python/configuration-options.md index a7ffd46fed..7e16dc4e62 100644 --- a/doc/python/configuration-options.md +++ b/doc/python/configuration-options.md @@ -5,10 +5,10 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.2' - jupytext_version: 1.4.2 + format_version: '1.3' + jupytext_version: 1.17.2 kernelspec: - display_name: Python 3 + display_name: Python 3 (ipykernel) language: python name: python3 language_info: @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.7.7 + version: 3.12.4 plotly: description: How to set the configuration options of figures using the Plotly Python graphing library. @@ -323,6 +323,42 @@ fig.update_layout(xaxis={'type': 'date'}) fig.show(config=config) ``` +### Disabling Buttons for Specific Axes + +*New in 6.3* + +Disabling the zoom in, zoom out, and autoscale buttons for specific axes is supported on cartesian axes using the `modebardisable` attribute. In the following example, the zoom in and zoom out buttons are disabled on the `xaxis`, meaning these buttons only zoom in and out on the `yaxis`. Disable the autoscale button using `modebardisable='autoscale'`. You can also disable the zoom and autoscale buttons using `modebardisable='zoominout+autoscale'`. + +```python +import plotly.graph_objects as go +import plotly.data + +df = plotly.data.stocks() + +fig = go.Figure( + data=[ + go.Scatter( + x=df['date'], + y=df['GOOG'], + mode='lines+markers', + name='Google Stock Price' + ) + ], + layout=go.Layout( + title='Google Stock Price Over Time with Mode Bar Disabled', + xaxis=dict( + title='Date', + # Try zooming in or out using the modebar buttons. These only apply to the yaxis in this exampe. + modebardisable='zoominout' + ), + yaxis=dict( + title='Stock Price (USD)', + ) + ) +) +fig.show() +``` + ### Configuring Figures in Dash Apps The same configuration dictionary that you pass to the `config` parameter of the `show()` method can also be passed to the [`config` property of a `dcc.Graph` component](https://dash.plotly.com/dash-core-components/graph). diff --git a/doc/python/hover-text-and-formatting.md b/doc/python/hover-text-and-formatting.md index 068095c69e..cdbc4058da 100644 --- a/doc/python/hover-text-and-formatting.md +++ b/doc/python/hover-text-and-formatting.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.3' - jupytext_version: 1.16.1 + jupytext_version: 1.17.2 kernelspec: display_name: Python 3 (ipykernel) language: python @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.10.11 + version: 3.12.4 plotly: description: How to use hover text and formatting in Python with Plotly. display_as: file_settings @@ -83,6 +83,57 @@ fig.update_layout(hovermode="x unified") fig.show() ``` +#### Customize Title in Unified Hovermode + +*New in 6.3* + +Customize the title shown in unified hovermode, by specifing `unifiedhovertitle.text`. + +The unified hover title is a template string that supports using variables from the data. Numbers are formatted using d3-format's syntax `%{variable:d3-format}`, for `example \"Price: %{y:$.2f}\"`. Dates are formatted using d3-time-format's syntax `%{variable|d3-time-format}`, for example `\"Day: %{2019-01-01|%A}\"`. + +The following example uses `'x unified'` hover and specifies a unified hover title that shows the full weekday, month, day, and year. + +```python +import plotly.graph_objects as go +import plotly.express as px + +df = px.data.stocks() + +fig = go.Figure( + data=[ + go.Scatter( + x=df['date'], + y=df['GOOG'], + mode='lines', + name='Google' + ), + go.Scatter( + x=df['date'], + y=df['AAPL'], + mode='lines', + name='Apple' + ) + ], + layout=go.Layout( + title_text="Stock Prices with Custom Unified Hover Title", + hovermode='x unified', + xaxis=dict( + title_text='Date', + unifiedhovertitle=dict( + text='%{x|%A, %B %d, %Y}' + ) + ), + yaxis=dict( + title_text='Price (USD)', + tickprefix='$' + ) + ) +) + +fig.show() + +``` + #### Control hovermode with Dash [Dash](https://plotly.com/dash/) is the best way to build analytical apps in Python using Plotly figures. To run the app below, run `pip install dash`, click "Download" to get the code and run `python app.py`. diff --git a/doc/python/legend.md b/doc/python/legend.md index d9042bb97a..6fc879fbc9 100644 --- a/doc/python/legend.md +++ b/doc/python/legend.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.3' - jupytext_version: 1.16.1 + jupytext_version: 1.17.2 kernelspec: display_name: Python 3 (ipykernel) language: python @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.10.11 + version: 3.9.0 plotly: description: How to configure and style the legend in Plotly with Python. display_as: file_settings @@ -254,6 +254,46 @@ fig.update_layout(legend=dict( fig.show() ``` +#### Legend Max Height + +*New in 6.3* + +By default, a legend can expand to fill up to half of the layout area height for a horizontal legend and the full height for a vertical legend. You can change this by specifying a `maxheight` for the legend. `maxheight` is interpreted as a ratio if it is 1 or less, and as an exact pixel value if it is greater than 1. In the following plot with many legend items, we set `maxheight` to a ratio of 0.10, giving the plot more space. + +```python +import plotly.express as px +from plotly import data + +df = data.gapminder().query("year==2007 and continent == 'Europe'") + +fig = px.scatter(df, + x="gdpPercap", + y="lifeExp", + color="country", + size="pop", + size_max=45, + title="Life Expectancy vs. GDP per Capita in 2007 (by Country)", + labels={"gdpPercap": "GDP per Capita"}, + ) + +fig.update_layout( + xaxis=dict( + side="top" + ), + legend=dict( + orientation="h", + yanchor="bottom", + y=-0.35, + xanchor="center", + x=0.5, + maxheight=0.1, # Comment maxheight to see legend take up 0.5 of plotting area + title_text="Country" + ), +) + +fig.show() +``` + #### Styling Legends Legends support many styling options. diff --git a/doc/python/log-plot.md b/doc/python/log-plot.md index 27d19febd1..edce8eeb09 100644 --- a/doc/python/log-plot.md +++ b/doc/python/log-plot.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.3' - jupytext_version: 1.13.7 + jupytext_version: 1.17.2 kernelspec: display_name: Python 3 (ipykernel) language: python @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.9.7 + version: 3.12.4 plotly: description: How to make Log plots in Python with Plotly. display_as: scientific @@ -80,6 +80,38 @@ fig.update_xaxes(minor=dict(ticks="inside", ticklen=6, showgrid=True)) fig.show() ``` +#### Controlling Minor Log Labels + +*New in 6.3* + +You can control how minor log labels are displayed using the `minorloglabels` attribute. Set to `"complete"` to show complete digits, or `None` for no labels. By default, minor log labels use `"small digits"`, as shown in the previous example. + +```python +import plotly.express as px + +df = px.data.gapminder().query("year == 2007") + +fig = px.scatter( + df, x="gdpPercap", + y="lifeExp", + hover_name="country", + log_x=True, + range_x=[1,100000], + range_y=[0,100] +) + +fig.update_xaxes( + minor=dict( + ticks="inside", + ticklen=6, + showgrid=True + ), + minorloglabels="complete" +) + +fig.show() +``` + ### Logarithmic Axes with Graph Objects If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Figure` class from `plotly.graph_objects`](/python/graph-objects/). diff --git a/doc/python/map-configuration.md b/doc/python/map-configuration.md index 3f4553b3f7..f7cee50282 100644 --- a/doc/python/map-configuration.md +++ b/doc/python/map-configuration.md @@ -51,7 +51,15 @@ Geo maps are outline-based maps. If your figure is created with a `px.scatter_ge ### Physical Base Maps -Plotly Geo maps have a built-in base map layer composed of "physical" and "cultural" (i.e. administrative border) data from the [Natural Earth Dataset](https://www.naturalearthdata.com/downloads/). Various lines and area fills can be shown or hidden, and their color and line-widths specified. In the [default `plotly` template](/python/templates/), a map frame and physical features such as a coastal outline and filled land areas are shown, at a small-scale 1:110m resolution: +Plotly Geo maps have a built-in base map layer composed of *physical* and *cultural* (i.e. administrative border) data. + +In **Plotly.py 6.3 and later**, the base map layer is created from the following sources: +- [UN data](https://geoportal.un.org/arcgis/sharing/rest/content/items/d7caaff3ef4b4f7c82689b7c4694ad92/data) for country borders, coastlines, land, and oceans layers. +- Natural Earth data for lakes, rivers, and subunits layers. + +In **earlier versions of Plotly.py**, the base map layer is based on Natural Earth data only. Plotly includes data from Natural Earth "as-is". This dataset draws boundaries of countries according to de facto status. See the [Natural Earth page for more details](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/). + +Various lines and area fills can be shown or hidden, and their color and line-widths specified. In the [default `plotly` template](/python/templates/), a map frame and physical features such as a coastal outline and filled land areas are shown, at a small-scale 1:110m resolution: ```python import plotly.graph_objects as go @@ -102,9 +110,9 @@ fig.show() In addition to physical base map features, a "cultural" base map is included which is composed of country borders and selected sub-country borders such as states. -**Note and disclaimer:** cultural features are by definition subject to change, debate and dispute. Plotly includes data from Natural Earth "as-is" and defers to the [Natural Earth policy regarding disputed borders](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/) which read: +In **Plotly.py 6.3 and later**, this base map is created from [UN data](https://geoportal.un.org/arcgis/sharing/rest/content/items/d7caaff3ef4b4f7c82689b7c4694ad92/data) for country borders, and Natural Earth data for sub-country borders. -> Natural Earth Vector draws boundaries of countries according to defacto status. We show who actually controls the situation on the ground. +In **earlier versions of Plotly.py**, this base map is based on Natural Earth data only. Plotly includes data from Natural Earth "as-is". This dataset draws boundaries of countries according to defacto status. See the [Natural Earth page for more details](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/). **To create a map with your own cultural features** please refer to our [choropleth documentation](/python/choropleth-maps/). diff --git a/doc/python/pattern-hatching-texture.md b/doc/python/pattern-hatching-texture.md index 25d7757163..ec5649eb32 100644 --- a/doc/python/pattern-hatching-texture.md +++ b/doc/python/pattern-hatching-texture.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.3' - jupytext_version: 1.14.6 + jupytext_version: 1.17.2 kernelspec: display_name: Python 3 (ipykernel) language: python @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.10.11 + version: 3.9.0 plotly: description: How to use patterns (also known as hatching or texture) with bar charts. @@ -150,6 +150,55 @@ fig.add_trace(go.Bar(x=["a","b"], y=[2,3], marker_pattern_shape="+")) fig.show() ``` +### Patterns Using SVG Paths + +*New in 6.3* + +You can make custom patterns for graphs by using an SVG path. Set `marker.pattern.path` to the SVG path to use: + +```python +import plotly.graph_objects as go +import plotly.data + +df = plotly.data.gapminder().query("year == 2007 and continent == 'Europe'").copy() +df['gdp'] = df['gdpPercap'] * df['pop'] +df = df.sort_values('gdp', ascending=False).head(4) + +fig = go.Figure( + data=[go.Bar( + x=df['country'], + y=df['gdp'], + marker=dict( + color=["lightsteelblue", "mistyrose", "palegreen", "thistle"], + pattern=dict( + path=[ + "M0,0H4V4H0Z", + "M0,0H6V6Z", + "M0,0V4H4Z", + "M0,0C0,2,4,2,4,4C4,6,0,6,0,8H2C2,6,6,6,6,4C6,2,2,2,2,0Z" + ], + fgcolor=["midnightblue", "crimson", "seagreen", "indigo"], + bgcolor=["mintcream", "lavenderblush", "azure", "honeydew"], + size=20, + solidity=0.7 + ) + ), + name="GDP (2007)" + )], + layout=dict( + title="Top 4 European Countries by GDP (Gapminder 2007) with Custom SVG Path Patterns", + xaxis_title="Country", + yaxis_title="GDP (USD)", + yaxis_tickformat="$.2s", + width=800, + height=500, + bargap=0.3 + ) +) + +fig.show() +``` + #### Reference See https://plotly.com/python/reference/bar/ for more information and chart attribute options!